16. Internationalization

The Control Software integrates a Languange Engine which permits to switch UI language from a list of available languages.
The UI Language Engine uses gettext, a standard internationalization and localization system commonly used for writing multilingual programs.

To edit an existent language, or add a new language to the Control Software, you can use the program Poedit.
Poedit exists in the freeware version or in the PRO version, which adds a lot of useful features to reduce the translation time and increase translation accuracy.

There are other translation tools that manage gettext .po/.mo files but in this document, we will use Poedit.

In gettext for each language translations there are one or two files:

• default.mo

This file contains the compiled language translations and is directly used by Control Software.

PS: This file is mandatory in Control Software Language Engine.

• default.po

This file contains the language translations project used by Poedit.

As the final step, of a language translation, Poedit will compile the default.po file to get the default.mo.

PS: This file is used only by Poedit to generate the default.mo file.

As shown in the upon scheme:

1. The source translation file default.po is loaded in Poedit translator for the translation in the target language.
2. When the translation is done or only desired texts are done the Poedit creates del output file default.mo.
3. The Control Software, during starting, check for available translation languages and load default.mo with translated texts.

Both gettext and Poedit support Unicode texts, so default.po and default.mo will contain Unicode translations.

The gettext Language Engine needs a well-defined path organization where to get info about available translation languages.
The Control Software reaches the translations files from %APPDATA\RosettaCNC-1\locale folder:

%APPDATA%\RosettaCNC-1\locale
                       |
                       + default.po (this is the main translation file to use to add a new language translation or merge already translated with new version).
                       |
		       +--\de
		       |   |
		       |   +----\LC_MESSAGES\default.mo  (Compiled Translation File for German)
		       |
		       +--\en
		       |   |
		       |   +----\LC_MESSAGES\default.mo  (Compiled Translation File for English)
		       |                    \default.po  (Source Translation File for Poedit)
		       |
		       +--\fr_FR
		       |   |
		       |   +----\LC_MESSAGES\default.mo  (Translation File for Francaise of France)
		       |
		       +--\it_IT
		       |   |
		       |   +----\LC_MESSAGES\default.mo  (Translation File for Italian of Italy)
		       |
		       +--\pt_BR
		           |
		           +----\LC_MESSAGES\default.mo  (Translation File for Portughese of Brazil)

The folders after locale define the translation language ad use the ISO 639-1 standard ( List of ISO 639-1 codes ).
The ISO 639-1 permits to define a language (e.g. en for common English) or a derivation of a language for a specific country (e.g: en_CA English for Canada).

The locale\en\LC_MESSAGES folder is then only that contains also the Source Translation File for Poedit ( poedit.po ) to use to create a new translation language.
The Control Software texts are natively in English so actually no need for any translation and poedit.mo will be an empty container.

To add a new language, e.g. Spanish, the steps to do are:

1. Close any open instance of the Control Software.
2. Copy/Paste the en folder, available in %APPDATA%\RosettaCNC-1\locale in %APPDATA%\RosettaCNC-1\locale.
   
3. Rename the copied folder to ..\locale\es folder to to have the %APPDATA%\RosettaCNC-1\locale\es and related sub-folders.
4. Run the Poedit and open %APPDATA%\RosettaCNC-1\locale\sp\LC_MESSAGES\default.po file or double click on it in Explorer to start Poedit and load it.
   

At this point Poedit will indicate to you that a Language of the Translation isn't set:

Clicking on the Set Language button will appear the Catalogue properties panel to define the Language, Charset, and info about translator identity:

Now the editor is ready to receive translations from English to Spanish.

• The Source Text will be always unmodifiable and in English, the native language of Control Software.
• Any untranslated text will remain in English in the Control Software UI.
• To be untranslated the Translation row must be empty without any space char or translation will be an empty string.
• Keep translation text shorter possible, or close to English string chars, not all UI fields have a width space for long strings.
• If Source Text has header/tail spaces these MUST be used also in the Translation.
• If Source Text uses HTML Tags SAME HTML Tags MUST be present also in the Translation.
• If Sorce Text presents data wildcard (%s for string, %d for data, %f for load or \n, etc. these MUST be present in same order also in the Translation.

The last point is very IMPORTANT because a missing or wrong order in a wildcard can produce an issue in the Translation Engine.
A practical way to translate a text is to copy the original one from the Source Text row to the Translate row and after modify the contents.
In this mode, it is more improbable to miss or mistake the order of wildcards or special chars.

To save the translation project and create the final translation file default.mo is only necessary to click the Save button in the toolbar:

The resulting localization path will be:

%APPDATA%\RosettaCNC-1\locale
                       |
		       +--\de
		       |   |
		       |   +----\LC_MESSAGES\default.mo  (Compiled Translation File for German)
		       |
		       +--\en
		       |   |
		       |   +----\LC_MESSAGES\default.mo  (Compiled Translation File for English)
		       |                    \default.po  (Source Translation File for Poedit)
		       |
		       +--\fr_FR
		       |   |
		       |   +----\LC_MESSAGES\default.mo  (Translation File for Francaise of France)
		       |
		       +--\it_IT
		       |   |
		       |   +----\LC_MESSAGES\default.mo  (Translation File for Italian of Italy)
		       |
		       +--\pt_BR
		       |   |
		       |   +----\LC_MESSAGES\default.mo  (Translation File for Portughese of Brazil)
		       |
		       +--\es
		           |
		           +----\LC_MESSAGES\default.mo  (Translation File for Spanish)
		                            \default.po  (Source Translation File for Poedit with Spanish Texts)

To check the translation just Start Control Software and choose the Spanish language in menu Program Settings… at Languages panel:

Every Control Software update or new version adds or changes some text so it is important to manage translations in time.
For a better management of a newly added language, we suggest saving the source translated file default.po for future translations.
Much better if you will send the file to support@rosettacnc.com, in this way we will add it to the new installation packages and we will maintain the new entry texts in that language.