22. Contributing to FreeNAS^®¶

FreeNAS^® is an open source community, relying on the input and expertise of users to grow and improve. When users take time to assist the community, their contributions benefit everyone.

This section describes how to participate and contribute to FreeNAS^®. It is by no means an exhaustive list. If you have an idea that will benefit the community, bring it up on one of the resources mentioned in Support Resources.

This section demonstrates how to:

Help with Translation

22.1. Translation¶

FreeNAS^® is developed and documented in English. Having complete translations of the user interface into other languages helps make FreeNAS^® much more useful to communities around the world.

FreeNAS^® uses .po files stored in the webui GitHub repository to manage the translation of text shown in the FreeNAS^® graphical administrative interface. GitHub provides an easy to use web-based editor, making it possible for individuals to assist with translation or comment on existing translations.

To view translation files, open the /src/assets/i18n directory of the FreeNAS^® webui repository, as shown in Figure 22.1.1.

Fig. 22.1.1 FreeNAS^® Translation Files

To assist with translating FreeNAS^®, first create an account with GitHub.

There are two methods to contribute translations to the project:

Edit po files and submit pull requests through the GitHub website.

OR

Copy the freenas/webui repository, make changes using a po editor, and submit these changes back “upstream” to the freenas/webui repository.

22.1.1. Translate with GitHub¶

Go to the freenas/webui repository. Select src ➞ assets and click the i18n directory. Click on the desired language po file to begin translating.

Tip

Here is a list of common language abbreviations

Click the Pencil icon in the upper right area to open the online file editor. Figure 22.1.2 shows the page that appears:

Fig. 22.1.2 GitHub Online Editor

There are numerous msgid "" and msgstr "" entries in the file. Read the msgid text and enter the translation between the msgstr quotes.

Scroll to the bottom of the page when finished entering translations. Enter a descriptive title and summary of changes for the edits and set Create a new branch. Click Propose file change to submit the translations to the FreeNAS^® project.

22.1.2. Download and Translate Offline¶

Install Git. There are numerous examples in these instructions of using git, but full documentation for git is available online.

Open a Command Line Interface (CLI). Navigate to or create a suitable location to store the local copy of the webui repository. Download the repository with git clone:

% git clone https://github.com/freenas/webui.git

The download can take several minutes, depending on connection speed.

cd into the webui directory and create a new branch of the repository to store the translation changes:

% git checkout -b new_translations

Tip

Type git status at any time to see which branch of the repository is active.

Navigate to the i18n directory:

% cd src/assets/i18n/

Use a po editor to add translations to the desired language file. Any capable editor will work, but poedit and gtranslator are two common options.

Commit any file changes with git commit:

% git commit ar.po

Enter a descriptive message about the changes and save the commit.

When finished making commits to the branch, git push the branch to the online freenas/webui repository:

% git push origin new_translations
Username for `https://github.com`:
Password for `https://account@github.com`:
Counting objects: 6, done.
Delta compression using up to 4 threads.
Compressing objects: 100% (6/6), done.
Writing objects: 100% (6/6), 8.56 KiB | 4.28 MiB/s, done.
Total 6 (delta 5), reused 0 (delta 0)
remote: Resolving deltas: 100% (5/5), completed with 5 local objects.
To https://github.com/freenas/webui.git
* [new branch]        new_translations -> new_translations

Open a web browser and navigate to the freenas/webui repository. GitHub automatically detects when a new branch is pushed to the repository and displays a message with an option to Compare & pull request. Click this, review the changes, and click Create pull request.

22.1.3. Translation Pull Requests¶

The FreeNAS^® project automatically tests pull requests for compatibility. If there any issues with a pull request, either the automated system will update the request or a FreeNAS^® team member will leave a message in the comment section of the request.

All assistance with translations helps to benefit the FreeNAS^® community. Thank you!

22. Contributing to FreeNAS®¶