Localization

From K-3D

Overview

Beginning with version 0.5, K-3D provides Native Language Support using the GNU gettext library. This article discusses localization, the process of creating and maintaining locales (language translations). For technical information on how to write code that can be localized, see Internationalization. To specify your preferred language when running K-3D see Native Language Support.

K-3D Localization for Maintainers

As new files requiring localization are added to the project and old files are removed, maintainers will need to update K-3D's message catalogs.

Initial Setup

You must build K-3D from source with the K3D_BUILD_NLS option enabled in CMake.

Update Localization File List

The files po/POTFILES.in and po/POTFILES.skip specify an explicit list of source files to be scanned for message strings that should be localized. As new sources are added to the project and old sources are removed, this list must be updated. To do this use we run a special makefile target which scans the source tree and detects files containing strings that require localization:

$ cd ~/k3d-build
$ make nls-update-sources

This requires that you have intltool-update installed. It will scan the entire source tree and print a list of new files that need to be added to POTFILES.in and missing files that should be removed. If intltool-update detects files that shouldn't be localized, add them to POTFILES.skip and they will be ignored in the future.

Generate Message Catalog

As string constants in the files requiring localization are added, modified, and changed, maintainers will need to update K-3D's message catalog - k3d.pot - which contains the complete list of strings requiring localization:

$ cd ~/k3d-build
$ rm po/k3d.pot
$ make nls

This process uses xgettext, which will scan all of the files listed in po/POTFILES.in, and produce a file k3d.pot which contains a record for every string that can be localized.

Create A New Locale

Translated versions of the K-3D message catalog k3d.pot are stored in ".po" files which are normally named for the locale they represent, e.g. "fr.po", "se.po", etc.

To begin a new translation, make a copy of k3d.pot, renaming it appropriately to <locale>.po, and add <locale> to the "K3D_CATALOGS" variable in po/CMakeLists.txt. Modify the contents of your new <locale>.po file, entering your translations and using UTF-8 for characters that cannot be represented using ASCII.

Update An Existing Locale

Anytime the k3d.pot message catalog is updated, existing po files will need to be modified by translators to reflect additions, deletions, and modifications to localized strings. Fortunately, translators do not have to start-over with an empty copy of k3d.pot - to update the <locale>.po file, do:

$ cd ~/k3d-build
$ make nls-update-<locale>.po

The msgmerge tool will merge new strings to be localized into the existing <locale>.po file. Obsolete strings will be commented-out, and strings that may have changed will be marked "fuzzy". Translators can easily find the new strings to be translated, and review the "fuzzy" strings for errors.

Generate Binary Catalogs

Once the localization process is complete, the up-to-date <locale>.po files are converted from text to binary k3d.mo files for efficient lookup at runtime, by the normal build process:

$ cd ~/k3d-build
$ make