Localization

Localization - "L10N" for short - is the process of creating new locales (language translations) for an existing application. For convenience, XTrackCAD provides several "make targets" to automate the localization process. In this document, those make targets are used.

GNU/Linux

The following setup is used in this manual:
1) Change to CMake build directory:
$ cd ~/build/xtrkcad

2) If you are editing an existing locale, go straight to step 3.
If you are adding a new locale to XTrackCAD, edit the src/xtrkcad/app/i18n/CMakeLists.txt file. There is a variable called XTRKCAD_LOCALES in the top of the file. This is the list of the supported locales. Add the new locale on it's own line and keep the list sorted alphabetically. Here is an example of what the list might be:
SET(XTRKCAD_LOCALES
  en_GB
  en_US
  fi
  sv
  ...
  )

3) Configure your build environment:
$ ccmake ~/src/xtrkcad

The following parameters are relevant to translation progress:

XTRKCAD_USE_GETTEXT (Default: ON)
Defines if gettext is used or not. If this is set to OFF, then the following parameters are ignored and no gettext support is compiled in the XTrackCAD.

XTC_TRANSLATOR (Default: <empty>)
Optional parameter. Translation program to edit the .po files. If this is set, "msgtranslate-<locale>" targets are created in i18n/Makefile to make the translation process easier(?). These targets calls the translation program with the .po file as a command line parameter.

4) Build the project. This will automatically update or create the required .po files to the source tree:
$ make

5) Translate. If you set the XTC_TRANSLATOR parameter in step 3, you may use the make targets that was created by CMake:
$ make msgtranslate-<locale>

Change <locale> to the locale you want to edit, for example:
$ make msgtranslate-fi

6) Install XTrackCAD and the language files. The language files (.mo files) will be created automatically:
$ make install

7) Test your translation:
$ ~/install/xtrkcad/bin/xtrkcad

If you are using English locale in your Linux session, you can still test XTrackCAD with any other locale by setting the LANG environment variable in terminal. In this example, Finnish locale is used:
$ export LANG=fi_FI.UTF-8
$ ~/install/xtrkcad/bin/xtrkcad

If translation needs to be modified, go back to step 5. When done, continue to step 8.
8) Update modified or add new locale file to version control:
src/xtrkcad/app/i18n/locale/<locale>.po

Useful tip

Fingers(tm) and Keyboard Buttons(tm) are both non-renewable natural resources, so it's recommended to combine the steps 5 to 7 into a one single command line while translating and testing:
$ make msgtranslate-<locale> && make install && \
   ~/install/xtrkcad/bin/xtrkcad

Then it's easy to hit the UpArrow and Enter to make the changes to translation and then test again.

Internationalization

"Internationalization" - or "I18N" for short - is the process of writing software that can display different locales.

All strings that are to be visible to the end user should be internationalized.

This means that every source file that contains translatable strings should include "i18n.h" file, and the code like this:
printf("Hello, World!\n");

should be written like this instead:
printf(_("Hello, World!\n"));

The macro _() has two jobs. It makes the string visible to xgettext string extractor utility, and it does the run time translation. To make things more complicated, there are some exceptions:
char * myString = "Some important string";
printf( myString );

converts to:
char * myString = N_("Some important string");
printf( _(myString) );

The N_() macro means "no-operation", and it's there only for telling the xgettext that the string should be added to .pot file for translation. The actual run time translation is done on the next line with _() macro. The _() macro cannot be used in the string initializer.

Gettext has also functions for plural forms and solving ambiguities, but currently they are not implemented in XTrackCAD. If these are added later, new macros (xgettext keywords) must be added to XGTKEYWORDS in i18n/CMakeLists.txt.

To enable or disable gettext internationalization in XTrkCad, set the parameter XTRKCAD_USE_GETTEXT to ON or OFF with ccmake.

Related links

GNU gettext

CMake

CategoryDevel

There are no comments on this page. [Add comment]

Download XTrkCAD Model RR Track Planner
Valid XHTML 1.0 Transitional :: Valid CSS :: Powered by WikkaWiki