diff options
Diffstat (limited to 'src/engine/SCons/Tool/gettext.xml')
| -rw-r--r-- | src/engine/SCons/Tool/gettext.xml | 97 |
1 files changed, 77 insertions, 20 deletions
diff --git a/src/engine/SCons/Tool/gettext.xml b/src/engine/SCons/Tool/gettext.xml index 1383fa1..667d6a7 100644 --- a/src/engine/SCons/Tool/gettext.xml +++ b/src/engine/SCons/Tool/gettext.xml @@ -1,15 +1,37 @@ +<?xml version="1.0" encoding="UTF-8"?> <!-- -Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation +Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014 The SCons Foundation This file is processed by the bin/SConsDoc.py module. See its __doc__ string for a discussion of the format. --> + +<!DOCTYPE sconsdoc [ +<!ENTITY % scons SYSTEM '../../../../doc/scons.mod'> +%scons; +<!ENTITY % builders-mod SYSTEM '../../../../doc/generated/builders.mod'> +%builders-mod; +<!ENTITY % functions-mod SYSTEM '../../../../doc/generated/functions.mod'> +%functions-mod; +<!ENTITY % tools-mod SYSTEM '../../../../doc/generated/tools.mod'> +%tools-mod; +<!ENTITY % variables-mod SYSTEM '../../../../doc/generated/variables.mod'> +%variables-mod; +]> + +<sconsdoc xmlns="http://www.scons.org/dbxsd/v1.0" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0/scons.xsd scons.xsd"> + <tool name="gettext"> <summary> +<para> This is actually a toolset, which supports internationalization and localization of sofware being constructed with SCons. The toolset loads following tools: +</para> +<para> <itemizedlist mark='opencircle'> <listitem><para> &t-link-xgettext; - to extract internationalized messages from source code to @@ -27,30 +49,38 @@ following tools: installable <literal>MO</literal> file. </para></listitem> </itemizedlist> +</para> +<para> When you enable &t-gettext;, it internally loads all abovementioned tools, so you're encouraged to see their individual documentation. +</para> +<para> 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 <emphasis>top-level</emphasis> builder &b-Translate; described few paragraphs later. +</para> +<para> To use &t-gettext; tools add <literal>'gettext'</literal> tool to your environment: -<example> +</para> +<example_commands> env = Environment( tools = ['default', 'gettext'] ) -</example> +</example_commands> </summary> <sets> </sets> <uses> -<!-- PLATFORM --> +<item><!-- PLATFORM --></item> </uses> </tool> <builder name="Translate"> <summary> +<para> This pseudo-builder belongs to &t-link-gettext; toolset. The builder extracts internationalized messages from source files, updates <literal>POT</literal> template (if necessary) and then updates <literal>PO</literal> translations (if @@ -59,42 +89,48 @@ 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. +</para> +<para> <emphasis>Example 1</emphasis>. The simplest way is to specify input files and output languages inline in a SCons script when invoking &b-Translate; -<example> +</para> +<example_commands> # SConscript in 'po/' directory env = Environment( tools = ["default", "gettext"] ) env['POAUTOINIT'] = 1 env.Translate(['en','pl'], ['../a.cpp','../b.cpp']) -</example> +</example_commands> +<para> <emphasis>Example 2</emphasis>. If you wish, you may also stick to conventional style known from <productname>autotools</productname>, i.e. using <filename>POTFILES.in</filename> and <filename>LINGUAS</filename> files -<example> +</para> +<example_commands> # LINGUAS en pl #end -</example> +</example_commands> -<example> +<example_commands> # POTFILES.in a.cpp b.cpp # end -</example> +</example_commands> -<example> +<example_commands> # SConscript env = Environment( tools = ["default", "gettext"] ) env['POAUTOINIT'] = 1 env['XGETTEXTPATH'] = ['../'] env.Translate(LINGUAS_FILE = 1, XGETTEXTFROM = 'POTFILES.in') -</example> +</example_commands> +<para> 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 @@ -109,10 +145,13 @@ directory (and not in variant directories). Additionaly, the file listing of <filename>po/</filename> directory contains <filename>LINGUAS</filename> file, so the source tree looks familiar to translators, and they may work with the project in their usual way. +</para> +<para> <emphasis>Example 3</emphasis>. Let's prepare a development tree as below -<example> +</para> +<example_commands> project/ + SConstruct + build/ @@ -122,29 +161,36 @@ Let's prepare a development tree as below + SConscript.i18n + POTFILES.in + LINGUAS -</example> +</example_commands> +<para> with <filename>build</filename> being variant directory. Write the top-level <filename>SConstruct</filename> script as follows -<example> +</para> +<example_commands> # 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') -</example> +</example_commands> +<para> the <filename>src/po/SConscript.i18n</filename> as -<example> +</para> +<example_commands> # src/po/SConscript.i18n Import('env') env.Translate(LINGUAS_FILE=1, XGETTEXTFROM='POTFILES.in', XGETTEXTPATH=['../']) -</example> +</example_commands> +<para> and the <filename>src/po/SConscript</filename> -<example> +</para> +<example_commands> # src/po/SConscript Import('env') env.MOFiles(LINGUAS_FILE = 1) -</example> +</example_commands> +<para> Such setup produces <literal>POT</literal> and <literal>PO</literal> files under source tree in <filename>src/po/</filename> and binary <literal>MO</literal> files under variant tree in @@ -152,18 +198,22 @@ under source tree in <filename>src/po/</filename> and binary <literal>PO</literal> files are separated from other output files, which must not be committed back to source repositories (e.g. <literal>MO</literal> files). +</para> +<para> <note><para>In above example, the <literal>PO</literal> files are not updated, nor created automatically when you issue <command>scons '.'</command> command. The files must be updated (created) by hand via <command>scons po-update</command> and then <literal>MO</literal> files can be compiled by running <command>scons '.'</command>.</para></note> +</para> </summary> </builder> <cvar name="POTDOMAIN"> <summary> +<para> The &cv-POTDOMAIN; defines default domain, used to generate <literal>POT</literal> filename as <filename>&cv-POTDOMAIN;.pot</filename> when no <literal>POT</literal> file name is provided by the user. This applies to @@ -171,22 +221,26 @@ no <literal>POT</literal> file name is provided by the user. This applies to builders, that use them, e.g. &b-Translate;). Normally (if &cv-POTDOMAIN; is not defined), the builders use <filename>messages.pot</filename> as default <literal>POT</literal> file name. +</para> </summary> </cvar> <cvar name="POAUTOINIT"> <summary> +<para> The &cv-POAUTOINIT; variable, if set to <literal>True</literal> (on non-zero numeric value), let the &t-link-msginit; tool to automatically initialize <emphasis>missing</emphasis> <literal>PO</literal> files with <command>msginit(1)</command>. This applies to both, &b-link-POInit; and &b-link-POUpdate; builders (and others that use any of them). +</para> </summary> </cvar> <cvar name="LINGUAS_FILE"> <summary> +<para> 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 @@ -195,6 +249,9 @@ list of file names as well. If &cv-LINGUAS_FILE; is set to <literal>True</literal> (or non-zero numeric value), the list will be read from default file named <filename>LINGUAS</filename>. +</para> </summary> </cvar> + +</sconsdoc>
\ No newline at end of file |