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

This is actually a toolset, which supports internationalization and localization of software being constructed with SCons. The toolset loads following tools: &t-link-xgettext; - to extract internationalized messages from source code to POT file(s), &t-link-msginit; - may be optionally used to initialize PO files, &t-link-msgmerge; - to update PO files, that already contain translated messages, &t-link-msgfmt; - to compile textual PO file to binary installable MO file. When you enable &t-gettext;, it internally loads all abovementioned 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 builder &b-Translate; described few paragraphs later. To use &t-gettext; tools add 'gettext' tool to your environment: env = Environment( tools = ['default', 'gettext'] )

This pseudo-builder belongs to &t-link-gettext; toolset. The builder extracts internationalized messages from source files, updates 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 acount 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'] = 1 env.Translate(['en','pl'], ['../a.cpp','../b.cpp']) Example 2. If you wish, you may also stick to conventional style known from autotools, i.e. using POTFILES.in and LINGUAS files # LINGUAS en pl #end # POTFILES.in a.cpp b.cpp # end # SConscript env = Environment( tools = ["default", "gettext"] ) env['POAUTOINIT'] = 1 env['XGETTEXTPATH'] = ['../'] env.Translate(LINGUAS_FILE = 1, 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). Additionaly, 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 variant directory. Write the top-level SConstruct script as follows # SConstruct env = Environment( tools = ["default", "gettext"] ) VariantDir('build', 'src', duplicate = 0) env['POAUTOINIT'] = 1 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=1, XGETTEXTFROM='POTFILES.in', XGETTEXTPATH=['../']) and the src/po/SConscript # src/po/SConscript Import('env') env.MOFiles(LINGUAS_FILE = 1) Such setup produces POT and PO files under source tree in src/po/ and binary MO files under 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 above example, the PO files are not updated, nor created automatically when you issue scons '.' command. 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 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 True (or non-zero numeric value), the list will be read from default file named LINGUAS.