11. Supporting PC-BSD®¶

11.2.1. Interface Translation¶

PC-BSD® uses Pootle for managing localization of the menu screens used by the installer and the PC-BSD® utilities. Pootle makes it possible to find out if your native language has been fully localized for PC-BSD®. Pootle also makes it easy for users to check and submit translated text as it provides a web editor and commenting system. This means that translators can spend their time making and reviewing translations rather than learning how to use a translation tool.

To see the status of a localization, open up the translation website in a web browser, as seen in Figure 11.2.1: The PC-BSD® Pootle Translation System.

The localizations PC-BSD® users have requested are listed alphabetically on the left. If your language is missing and you would like to help in its translation, send an email to the translations mailing list so it can be added.

The green bar in the “Progress” column indicates the percentage of PC-BSD® menus that have been localized. If a language is not at 100%, it means that the menus that currently are not translated will appear in English instead of in that language.

If you click on a language name then click on the “PC-BSD” hyperlink under the “Name” column, you will see each menu item that is available for translation. The example shown in Figure 11.2.2: Viewing a Language’s Available Menus is for the Greek localization. In this example, the menu for “ethernetconfig” is complete, but the one for “LifePreserver” is not.

In order to edit a translation, you need to first create a Pootle login account. Once you are logged in to Pootle, navigate to the menu item that you wish to translate. In Figure 11.2.3: Using the Pootle Interface to Edit a Translation String, the translator has clicked on “LifePreserver.ts” then clicked the “Translate” tab.

In this example, the first string, the phrase “Classic Home-Dir Backup” has not yet been translated. To add the translation, type the translated text into the white text field and click the “Submit” button. To translate another text field, click on the hyperlink associated with its name, or use the “Next” and “Previous” links to navigate between text fields. Sometimes, a text field exists in another screen and already has a translation. Figure 11.2.4: Selecting a Suggested Translation provides an example where the translator clicked the hyperlink for “Filename” which displays three previous translations. The translator then clicked the first suggestion and it was automatically added to the white text field.

If you need help with a translation or using the Pootle system, you can ask for help on the translations mailing list or in the translations forum.

11.2.2. Documentation Translation¶

The source for the PC-BSD® Users Handbook is stored in the PC-BSD® github repository. This means that the documentation and any translations can be built with the operating system and updates to this documentation can be automatically installed when the system is updated using Update Manager. This has the added advantage of making sure that the installed version of the Handbook always matches the operating system version and that, as new features are added, that they are documented and appear as a local copy on the user’s system. The local copy is stored in /usr/local/share/pcbsd/doc/html and a desktop shortcut provides easy access to the documentation.

At this time, the PC-BSD® build server has been configured to automatically build the HTML version of the PC-BSD® Users Handbook. Over time, additional Makefiles will be tested and added to provide the documentation in other formats, such as single HTML, PDF, and EPUB. Instructions for building your own HTML or PDF version can be found in this README.md.

The documentation source files have been integrated into the Pootle translation system so that the PC-BSD® documentation can be translated using a web browser. The process is similar to Interface Translation except that you must first select “PC-BSD Handbook” from the “Projects” drop-down menu shown in Figure 11.2.5: Selecting the Handbook Project.

You can then select the language to translate into from the available languages list. If the language that you want to translate is not listed, send an email to the translations mailing list and request that it be added.

When translating the documentation, be aware of the following:

• At this time, some formatting tags are still displayed in raw text, as seen in the examples in Figure 11.2.6: Do Not Remove Formatting Characters and Figure 11.2.7: Another Formatting Characters Example. It is IMPORTANT that you do not accidentally remove the formatting as this can break the documentation build for that language. In the first example, it is OK to translate the phrase “Using the Text Installer” but care must be taken to not accidental remove any of the surrounding colons and backticks, or to change the text of the “ref” tag. In the second example, the asterisks are used to bold the word “install”. It is OK to translate “install”, but do not remove the asterisks.

If you would like to receive notifications of documentation changes that affect translations, subscribe to the Translation-notifications mailing list.

If you would like to build a local HTML copy that includes the latest translations, either for your own use or to visualize the translated Guide, do the following from the command line. These instructions are for a PC-BSD® system:

sudo pkg install pcbsd-toolchain
rehash
git clone git://github.com/pcbsd/pcbsd.git
cd pcbsd/src-qt5/docs
sudo make i18n
make html
ls _build
doctrees                html-es                 html-tr                pcbsd-handbook-i18n.txz
html                    html-fr                 html-uk
html-da                 html-id                 locale
html-de                 html-pt_BR              locale-po

This will make an HTML version of the Guide for each of the available translations. In this example, translations are available for English (in html), Danish, German, Spanish, French, Indonesian, Brazilian Portuguese, Turkish, and UK English. To update the HTML at a later time:

cd ~/pcbsd
git pull
cd src-qt5/docs
sudo make i18n
sudo make html

11.2.3. Website Translation¶

If you are interested in translating the PC-BSD® website, send an email to the translations mailing list. Someone will introduce you to the webmaster who will get you started on website translation.

Currently, the the website is being translated to several languages, including: Dutch, French, German, Polish, Spanish, Swedish, and Turkish.

11.3.1. Getting the Source Code¶

The PC-BSD® source code is available from github and git needs to be installed in order to download the source code. When using PC-BSD®, git is included in the base install.

To download the source code, cd to the directory to store the source and type:

git clone git://github.com/pcbsd/pcbsd.git

This will create a directory named pcbsd/ which contains the local copy of the repository. To keep the local copy in sync with the official repository, run git pull within the pcbsd directory.

PC-BSD® graphical applications use Qt version 5 and their source is located in pcbsd/src-qt5/. In order to compile the applications in this directory, install the “PC-BSD Build Toolchain” package using AppCafe®. To instead install this software from the command line, type pkg install pcbsd-toolchain.

Most of the PC-BSD® source code is divided into two sub-categories:

• src-sh/ contains shell and C programs which do not include GUIs. These are the command line utilities used in TrueOS® and PC-BSD®.
• src-qt5/ contains the Qt5-based GUIs seen in PC-BSD®.

To compile the command line utilities:

cd src-sh

make

To compile the graphical utilities:

cd src-qt5

/usr/local/lib/qt5/bin/qmake

make

Several Qt IDEs are available in AppCafe®. The QtCreator application is a full-featured IDE designed to help new Qt users get up and running faster while boosting the productivity of experienced Qt developers. Qt Designer is lighter weight as it is only a .ui file editor and does not provide any other IDE functionality. To install this package, check the “Search all available software” in the “App Search” tab of AppCafe® and search for “qt5-designer”. Alternately, install it using pkg install qt5-designer.

If you plan to submit changes so that they can be included in PC-BSD®, fork the repository using the instructions in fork a repo. Make your changes to the fork, then submit them by issuing a git pull request. Once your changes have been reviewed, they will be committed or sent back with suggestions.

11.3.2. Design Guidelines¶

PC-BSD® is a community driven project that relies on the support of developers in the community to help in the design and implementation of new utilities and tools for PC-BSD®. The Project aims to present a unified design so that programs feel familiar to users. As an example, while programs could have “File”, “Main”, or “System” as their first entry in a menu bar, “File” is used as the accepted norm for the first category on the menu bar.

This section describes a small list of guidelines for menu and program design in PC-BSD®.

Any graphical program that is a full-featured utility, such as Life Preserver, should have a “File” menu. However, file menus are not necessary for small widget programs or dialogue boxes. When making a file menu, a good rule of thumb is keep it simple. Most PC-BSD® utilities do not need more than two or three items on the file menu.

“Configure” is our adopted standard for the category that contains settings or configuration-related settings. If additional categories are needed, check to see what other PC-BSD® utilities are using.

File menu icons are taken from the KDE Oxygen theme located in /usr/local/share/icons/oxygen. Use these file menu icons so we do not have a bunch of different icons used for the same function. Table 11.3a lists the commonly used icons and their default file names.

Table 11.3a: Commonly Used File Menu Icons

PC-BSD® utilities use these buttons as follows:

• Apply: applies settings and leaves the window open.
• Close: closes program without applying settings.
• OK: closes dialogue window and saves settings.
• Cancel: closes dialog window without applying settings.
• Save: saves settings and closes window.

Fully functional programs like Life Preserver do not use close buttons on the front of the application. Basically, whenever there is a “File” menu, that and an “x” in the top right corner of the application are used instead. Dialogues and widget programs are exceptions to this rule. A good example of a widget program would be Update Manager.

Many users benefit from keyboard shortcuts and we aim to make them available in every PC-BSD® utility. Qt makes it easy to assign keyboard shortcuts. For instance, to configure keyboard shortcuts that browse the “File” menu, put &File in the text slot for the menu entry when making the application. Whichever letter has the & symbol in front of it will become the hot key. You can also make a shortcut key by clicking the menu or submenu entry and assigning a shortcut key. Be careful not to duplicate hot keys or shortcut keys. Every key in a menu and submenu should have a key assigned for ease of use and accessibility. Tables 11.3b and 11.3c summarize the commonly used shortcut and hot keys.

Table 11.3b: Shortcut Keys

Table 11.3c: Hot Keys

When saving an application’s settings, the QSettings class should be used if possible. There are two different “organizations”, depending on whether the application is running with root permissions or user permissions. Use “PCBSD” for the organization for applications that run with user permissions and “PCBSD-root” for applications that are started with root permissions via sudo. Proper use prevents the directory where settings files are saved from being locked down by root applications, allowing user applications to save and load their settings. Examples 11.3a and 11.3b demonstrate how to use the QSettings class for each type of permission.

Example 11.3a: User Permission Settings:

(user application - C++ code):
QSettings settings("PCBSD", "myapplication");

Example 11.3b: Root Permission Settings:

(root application - C++ code):
QSettings settings("PCBSD-root", "myapplication");

Developers will also find the following resources helpful:

• Commits Mailing List
• Qt 5.4 Documentation
• C++ Tutorials