%scons; %builders-mod; %functions-mod; %tools-mod; %variables-mod; ]>

A toolset supporting internationalization and localization of software being constructed with &SCons;. The toolset loads the following tools: &t-link-xgettext; - extract internationalized messages from source code to POT file(s). &t-link-msginit; - initialize PO files during initial translation of a project. &t-link-msgmerge; - update PO files that already contain translated messages, &t-link-msgfmt; - compile textual PO files to binary installable MO files. When you enable &t-gettext;, it internally loads all the above-mentioned tools, so you're encouraged to see their individual documentation. Each of the above tools provides its own builder(s) which may be used to perform particular activities related to software internationalization. You may be however interested in top-level &b-link-Translate; builder. To use the &t-gettext; tools, add the 'gettext' tool to your &consenv;: env = Environment(tools=['default', 'gettext'])

This pseudo-Builder is part of the &t-link-gettext; toolset. The builder extracts internationalized messages from source files, updates the POT template (if necessary) and then updates PO translations (if necessary). If &cv-link-POAUTOINIT; is set, missing PO files will be automatically created (i.e. without translator person intervention). The variables &cv-link-LINGUAS_FILE; and &cv-link-POTDOMAIN; are taken into account too. All other construction variables used by &b-link-POTUpdate;, and &b-link-POUpdate; work here too. Example 1. The simplest way is to specify input files and output languages inline in a SCons script when invoking &b-Translate;: # SConscript in 'po/' directory env = Environment(tools=["default", "gettext"]) env['POAUTOINIT'] = True env.Translate(['en', 'pl'], ['../a.cpp', '../b.cpp']) Example 2. If you wish, you may also stick to the conventional style known from autotools, i.e. using POTFILES.in and LINGUAS files to specify the targets and sources: # LINGUAS en pl # end # POTFILES.in a.cpp b.cpp # end # SConscript env = Environment(tools=["default", "gettext"]) env['POAUTOINIT'] = True env['XGETTEXTPATH'] = ['../'] env.Translate(LINGUAS_FILE=True, XGETTEXTFROM='POTFILES.in') The last approach is perhaps the recommended one. It allows easily split internationalization/localization onto separate SCons scripts, where a script in source tree is responsible for translations (from sources to PO files) and script(s) under variant directories are responsible for compilation of PO to MO files to and for installation of MO files. The "gluing factor" synchronizing these two scripts is then the content of LINGUAS file. Note, that the updated POT and PO files are usually going to be committed back to the repository, so they must be updated within the source directory (and not in variant directories). Additionally, the file listing of po/ directory contains LINGUAS file, so the source tree looks familiar to translators, and they may work with the project in their usual way. Example 3. Let's prepare a development tree as below project/ + SConstruct + build/ + src/ + po/ + SConscript + SConscript.i18n + POTFILES.in + LINGUAS with build being the variant directory. Write the top-level SConstruct script as follows # SConstruct env = Environment(tools=["default", "gettext"]) VariantDir('build', 'src', duplicate=False) env['POAUTOINIT'] = True SConscript('src/po/SConscript.i18n', exports='env') SConscript('build/po/SConscript', exports='env') the src/po/SConscript.i18n as # src/po/SConscript.i18n Import('env') env.Translate(LINGUAS_FILE=True, XGETTEXTFROM='POTFILES.in', XGETTEXTPATH=['../']) and the src/po/SConscript # src/po/SConscript Import('env') env.MOFiles(LINGUAS_FILE=True) Such a setup produces POT and PO files under the source tree in src/po/ and binary MO files under the variant tree in build/po/. This way the POT and PO files are separated from other output files, which must not be committed back to source repositories (e.g. MO files). In the above example, the PO files are not updated, nor created automatically when you issue the command scons .. The files must be updated (created) by hand via scons po-update and then MO files can be compiled by running scons ..

The &cv-POTDOMAIN; defines default domain, used to generate POT filename as &cv-POTDOMAIN;.pot when no POT file name is provided by the user. This applies to &b-link-POTUpdate;, &b-link-POInit; and &b-link-POUpdate; builders (and builders, that use them, e.g. &b-Translate;). Normally (if &cv-POTDOMAIN; is not defined), the builders use messages.pot as default POT file name.

The &cv-POAUTOINIT; variable, if set to True (on non-zero numeric value), let the &t-link-msginit; tool to automatically initialize missing PO files with msginit(1). This applies to both, &b-link-POInit; and &b-link-POUpdate; builders (and others that use any of them).

The &cv-LINGUAS_FILE; defines file(s) containing list of additional linguas to be processed by &b-link-POInit;, &b-link-POUpdate; or &b-link-MOFiles; builders. It also affects &b-link-Translate; builder. If the variable contains a string, it defines the name of the list file. The &cv-LINGUAS_FILE; may be a list of file names as well. If &cv-LINGUAS_FILE; is set to a non-string truthy value, the list will be read from the file named LINGUAS.