SCons/Tool/gettext.xml

   1 <?xml version="1.0"?>
   2 <!--
   3 SPDX-FileCopyrightText: Copyright The SCons Foundation (https://scons.org)
   4 SPDX-License-Identifier: MIT
   5 SPDX-FileType: DOCUMENTATION
   6
   7 This file is processed by the bin/SConsDoc.py module.
   8 -->
   9
  10 <!DOCTYPE sconsdoc [
  11 <!ENTITY % scons SYSTEM '../../doc/scons.mod'>
  12 %scons;
  13 <!ENTITY % builders-mod SYSTEM '../../doc/generated/builders.mod'>
  14 %builders-mod;
  15 <!ENTITY % functions-mod SYSTEM '../../doc/generated/functions.mod'>
  16 %functions-mod;
  17 <!ENTITY % tools-mod SYSTEM '../../doc/generated/tools.mod'>
  18 %tools-mod;
  19 <!ENTITY % variables-mod SYSTEM '../../doc/generated/variables.mod'>
  20 %variables-mod;
  21 ]>
  22
  23 <sconsdoc xmlns="http://www.scons.org/dbxsd/v1.0"
  24           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  25           xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0 http://www.scons.org/dbxsd/v1.0/scons.xsd">
  26
  27 <tool name="gettext">
  28 <summary>
  29 <para>
  30 A toolset supporting internationalization and
  31 localization of software being constructed with &SCons;.
  32 The toolset loads the following tools:
  33 </para>
  34
  35 <para>
  36 <itemizedlist mark='opencircle'>
  37   <listitem><para>
  38     &t-link-xgettext; - extract internationalized messages from source code to
  39     <literal>POT</literal> file(s).
  40   </para></listitem>
  41   <listitem><para>
  42     &t-link-msginit; - initialize <literal>PO</literal>
  43     files during initial translation of a project.
  44   </para></listitem>
  45   <listitem><para>
  46     &t-link-msgmerge; - update <literal>PO</literal> files that already contain
  47     translated messages,</para></listitem>
  48   <listitem><para>
  49     &t-link-msgfmt; - compile textual <literal>PO</literal> files to binary
  50     installable <literal>MO</literal> files.
  51   </para></listitem>
  52 </itemizedlist>
  53 </para>
  54
  55 <para>
  56 When you enable &t-gettext;, it internally loads all the above-mentioned tools,
  57 so you're encouraged to see their individual documentation.
  58 </para>
  59
  60 <para>
  61 Each of the above tools provides its own builder(s) which may be used to
  62 perform particular activities related to software internationalization. You
  63 may be however interested in <emphasis>top-level</emphasis>
  64 &b-link-Translate; builder.
  65 </para>
  66
  67 <para>
  68 To use the &t-gettext; tools, add the <literal>'gettext'</literal> tool to your
  69 &consenv;:
  70 </para>
  71 <programlisting language="python">
  72 env = Environment(tools=['default', 'gettext'])
  73 </programlisting>
  74 </summary>
  75 <sets>
  76 </sets>
  77 <uses>
  78 <item><!-- PLATFORM --></item>
  79 </uses>
  80 </tool>
  81
  82 <builder name="Translate">
  83 <summary>
  84 <para>
  85 This pseudo-Builder is part of the &t-link-gettext; toolset.
  86 The builder extracts internationalized messages from source files,
  87 updates the <literal>POT</literal> template (if necessary)
  88 and then updates <literal>PO</literal> translations (if necessary).
  89 If &cv-link-POAUTOINIT; is set, missing <literal>PO</literal> files
  90 will be automatically created (i.e. without translator person intervention).
  91 The variables &cv-link-LINGUAS_FILE; and &cv-link-POTDOMAIN; are taken into
  92 account too. All other construction variables used by &b-link-POTUpdate;, and
  93 &b-link-POUpdate; work here too.
  94 </para>
  95
  96 <para>
  97 <emphasis>Example 1</emphasis>.
  98 The simplest way is to specify input files and output languages inline in
  99 a SCons script when invoking &b-Translate;:
 100 </para>
 101 <programlisting language="python">
 102 # SConscript in 'po/' directory
 103 env = Environment(tools=["default", "gettext"])
 104 env['POAUTOINIT'] = True
 105 env.Translate(['en', 'pl'], ['../a.cpp', '../b.cpp'])
 106 </programlisting>
 107
 108 <para>
 109 <emphasis>Example 2</emphasis>.
 110 If you wish, you may also stick to the conventional style known from
 111 <productname>autotools</productname>, i.e. using
 112 <filename>POTFILES.in</filename> and <filename>LINGUAS</filename> files
 113 to specify the targets and sources:
 114 </para>
 115 <programlisting language="python">
 116 # LINGUAS
 117 en pl
 118 # end
 119 </programlisting>
 120
 121 <programlisting>
 122 # POTFILES.in
 123 a.cpp
 124 b.cpp
 125 # end
 126 </programlisting>
 127
 128 <programlisting language="python">
 129 # SConscript
 130 env = Environment(tools=["default", "gettext"])
 131 env['POAUTOINIT'] = True
 132 env['XGETTEXTPATH'] = ['../']
 133 env.Translate(LINGUAS_FILE=True, XGETTEXTFROM='POTFILES.in')
 134 </programlisting>
 135
 136 <para>
 137 The last approach is perhaps the recommended one. It allows easily split
 138 internationalization/localization onto separate SCons scripts, where a script
 139 in source tree is responsible for translations (from sources to
 140 <literal>PO</literal> files) and script(s) under variant directories are
 141 responsible for compilation of <literal>PO</literal> to <literal>MO</literal>
 142 files to and for installation of <literal>MO</literal> files. The "gluing
 143 factor" synchronizing these two scripts is then the content of
 144 <filename>LINGUAS</filename> file.  Note, that the updated
 145 <literal>POT</literal> and <literal>PO</literal> files are usually going to be
 146 committed back to the repository, so they must be updated within the source
 147 directory (and not in variant directories). Additionally, the file listing of
 148 <filename>po/</filename> directory contains <filename>LINGUAS</filename> file,
 149 so the source tree looks familiar to translators, and they may work with the
 150 project in their usual way.
 151 </para>
 152
 153 <para>
 154 <emphasis>Example 3</emphasis>.
 155 Let's prepare a development tree as below
 156 </para>
 157 <programlisting>
 158  project/
 159   + SConstruct
 160   + build/
 161   + src/
 162       + po/
 163           + SConscript
 164           + SConscript.i18n
 165           + POTFILES.in
 166           + LINGUAS
 167 </programlisting>
 168 <para>
 169 with <filename>build</filename> being the variant directory.
 170 Write the top-level
 171 <filename>SConstruct</filename> script as follows
 172 </para>
 173 <programlisting language="python">
 174 # SConstruct
 175 env = Environment(tools=["default", "gettext"])
 176 VariantDir('build', 'src', duplicate=False)
 177 env['POAUTOINIT'] = True
 178 SConscript('src/po/SConscript.i18n', exports='env')
 179 SConscript('build/po/SConscript', exports='env')
 180 </programlisting>
 181 <para>
 182 the <filename>src/po/SConscript.i18n</filename> as
 183 </para>
 184 <programlisting language="python">
 185 # src/po/SConscript.i18n
 186 Import('env')
 187 env.Translate(LINGUAS_FILE=True, XGETTEXTFROM='POTFILES.in', XGETTEXTPATH=['../'])
 188 </programlisting>
 189 <para>
 190 and the <filename>src/po/SConscript</filename>
 191 </para>
 192 <programlisting language="python">
 193 # src/po/SConscript
 194 Import('env')
 195 env.MOFiles(LINGUAS_FILE=True)
 196 </programlisting>
 197 <para>
 198 Such a setup produces <literal>POT</literal> and <literal>PO</literal> files
 199 under the source tree in <filename>src/po/</filename> and binary
 200 <literal>MO</literal> files under the variant tree in
 201 <filename>build/po/</filename>. This way the <literal>POT</literal> and
 202 <literal>PO</literal> files are separated from other output files, which must
 203 not be committed back to source repositories (e.g. <literal>MO</literal>
 204 files).
 205 </para>
 206
 207 <note><para>In the above example,
 208 the <literal>PO</literal> files are not updated,
 209 nor created automatically when you issue the command
 210 <userinput>scons .</userinput>.
 211 The files must be updated (created) by hand via
 212 <userinput>scons po-update</userinput>
 213 and then <literal>MO</literal> files can be compiled by
 214 running <userinput>scons .</userinput>.
 215 </para></note>
 216
 217 </summary>
 218 </builder>
 219
 220 <cvar name="POTDOMAIN">
 221 <summary>
 222 <para>
 223 The &cv-POTDOMAIN; defines default domain, used to generate
 224 <literal>POT</literal> filename as <filename>&cv-POTDOMAIN;.pot</filename> when
 225 no <literal>POT</literal> file name is provided by the user. This applies to
 226 &b-link-POTUpdate;, &b-link-POInit; and &b-link-POUpdate; builders (and
 227 builders, that use them, e.g. &b-Translate;). Normally (if &cv-POTDOMAIN; is
 228 not defined), the builders use <filename>messages.pot</filename> as default
 229 <literal>POT</literal> file name.
 230 </para>
 231 </summary>
 232 </cvar>
 233
 234 <cvar name="POAUTOINIT">
 235 <summary>
 236 <para>
 237 The &cv-POAUTOINIT; variable, if set to <literal>True</literal> (on non-zero
 238 numeric value), let the &t-link-msginit; tool to automatically initialize
 239 <emphasis>missing</emphasis> <literal>PO</literal> files with
 240 <command>msginit(1)</command>.  This applies to both,
 241 &b-link-POInit; and &b-link-POUpdate; builders (and others that use any of
 242 them).
 243 </para>
 244 </summary>
 245 </cvar>
 246
 247 <cvar name="LINGUAS_FILE">
 248 <summary>
 249 <para>
 250 The &cv-LINGUAS_FILE; defines file(s) containing list of additional linguas
 251 to be processed by &b-link-POInit;, &b-link-POUpdate; or &b-link-MOFiles;
 252 builders. It also affects &b-link-Translate; builder. If the variable contains
 253 a string, it defines the name of the list file. The &cv-LINGUAS_FILE; may be a
 254 list of file names as well. If &cv-LINGUAS_FILE; is set to
 255 a non-string truthy value, the list will be read from
 256 the file named
 257 <filename>LINGUAS</filename>.
 258 </para>
 259
 260 </summary>
 261 </cvar>
 262
 263 </sconsdoc>