diff options
Diffstat (limited to 'doc/user/gettext.xml')
| -rw-r--r-- | doc/user/gettext.xml | 353 |
1 files changed, 197 insertions, 156 deletions
diff --git a/doc/user/gettext.xml b/doc/user/gettext.xml index 706febe..c9cbcdb 100644 --- a/doc/user/gettext.xml +++ b/doc/user/gettext.xml @@ -1,6 +1,28 @@ +<?xml version='1.0'?> +<!DOCTYPE sconsdoc [ + <!ENTITY % scons SYSTEM "../scons.mod"> + %scons; + + <!ENTITY % builders-mod SYSTEM "../generated/builders.mod"> + %builders-mod; + <!ENTITY % functions-mod SYSTEM "../generated/functions.mod"> + %functions-mod; + <!ENTITY % tools-mod SYSTEM "../generated/tools.mod"> + %tools-mod; + <!ENTITY % variables-mod SYSTEM "../generated/variables.mod"> + %variables-mod; + +]> + +<chapter id="chap-gettext" + 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"> +<title>Internationalization and localization with gettext</title> + <!-- - 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 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -40,12 +62,14 @@ </para> <para> - Ensure, that you have <ulink url="http://www.gnu.org/software/gettext/manual/gettext.html">GNU gettext + Ensure, that you have <ulink + url="http://www.gnu.org/software/gettext/manual/gettext.html">GNU gettext utilities</ulink> installed on your system. </para> <para> - To edit translation files you may wish to install <ulink url="http://www.poedit.net/">poedit</ulink> editor. + To edit translation files you may wish to install <ulink + url="http://www.poedit.net/">poedit</ulink> editor. </para> </section> @@ -54,30 +78,36 @@ <para> Let's start with a very simple project, the "Hello world" program for example - <programlisting> - /* hello.c */ - #include <stdio.h> - int main(int argc, char* argv[]) - { - printf("Hello world\n"); - return 0; - } - </programlisting> + <scons_example name="gettext_ex1"> + <file name="hello.c" printme="1"> +/* hello.c */ +#include <stdio.h> +int main(int argc, char* argv[]) +{ + printf("Hello world\n"); + return 0; +} + </file> + </scons_example> Prepare a <filename>SConstruct</filename> to compile the program as usual. - <programlisting> - # SConstruct - env = Environment() - hello = Program(["hello.c"]) - </programlisting> + <scons_example name="gettext_ex2"> + <file name="SConstruct" printme="1"> +# SConstruct +env = Environment() +hello = Program(["hello.c"]) + </file> + </scons_example> </para> <para> Now we'll convert the project to a multi-lingual one. If you don't - already have <ulink url="http://www.gnu.org/software/gettext/manual/gettext.html">GNU gettext + already have <ulink + url="http://www.gnu.org/software/gettext/manual/gettext.html">GNU gettext utilities</ulink> installed, install them from your preffered - package repository, or download from <ulink url="http://ftp.gnu.org/gnu/gettext/"> + package repository, or download from <ulink + url="http://ftp.gnu.org/gnu/gettext/"> http://ftp.gnu.org/gnu/gettext/</ulink>. For the purpose of this example, you should have following three locales installed on your system: <literal>en_US</literal>, <literal>de_DE</literal> and @@ -88,22 +118,25 @@ <para> First prepare the <filename>hello.c</filename> program for internationalization. Change the previous code so it reads as follows: - <programlisting> - /* hello.c */ - #include <stdio.h> - #include <libintl.h> - #include <locale.h> - int main(int argc, char* argv[]) - { - bindtextdomain("hello", "locale"); - setlocale(LC_ALL, ""); - textdomain("hello"); - printf(gettext("Hello world\n")); - return 0; - } - </programlisting> + <scons_example name="gettext_ex3"> + <file name="hello.c" printme="1"> +/* hello.c */ +#include <stdio.h> +#include <libintl.h> +#include <locale.h> +int main(int argc, char* argv[]) +{ + bindtextdomain("hello", "locale"); + setlocale(LC_ALL, ""); + textdomain("hello"); + printf(gettext("Hello world\n")); + return 0; +} + </file> + </scons_example> Detailed recipes for such conversion can - be found at <ulink url="http://www.gnu.org/software/gettext/manual/gettext.html#Sources"> + be found at <ulink + url="http://www.gnu.org/software/gettext/manual/gettext.html#Sources"> http://www.gnu.org/software/gettext/manual/gettext.html#Sources</ulink>. The <function>gettext("...")</function> has two purposes. First, it marks messages for the <command>xgettext(1)</command> program, which @@ -127,48 +160,50 @@ <para> The completed <filename>SConstruct</filename> is as follows: - <programlisting> - # SConstruct - env = Environment( tools = ['default', 'gettext'] ) - hello = env.Program(["hello.c"]) - env['XGETTEXTFLAGS'] = [ - '--package-name=%s' % 'hello', - '--package-version=%s' % '1.0', - ] - po = env.Translate(["pl","en", "de"], ["hello.c"], POAUTOINIT = 1) - mo = env.MOFiles(po) - InstallAs(["locale/en/LC_MESSAGES/hello.mo"], ["en.mo"]) - InstallAs(["locale/pl/LC_MESSAGES/hello.mo"], ["pl.mo"]) - InstallAs(["locale/de/LC_MESSAGES/hello.mo"], ["de.mo"]) - </programlisting> + <scons_example name="gettext_ex4"> + <file name="SConstruct" printme="1"> +# SConstruct +env = Environment( tools = ['default', 'gettext'] ) +hello = env.Program(["hello.c"]) +env['XGETTEXTFLAGS'] = [ + '--package-name=%s' % 'hello', + '--package-version=%s' % '1.0', +] +po = env.Translate(["pl","en", "de"], ["hello.c"], POAUTOINIT = 1) +mo = env.MOFiles(po) +InstallAs(["locale/en/LC_MESSAGES/hello.mo"], ["en.mo"]) +InstallAs(["locale/pl/LC_MESSAGES/hello.mo"], ["pl.mo"]) +InstallAs(["locale/de/LC_MESSAGES/hello.mo"], ["de.mo"]) + </file> + </scons_example> </para> <para> Generate the translation files with <command>scons po-update</command>. You should see the output from SCons simillar to this: <screen> - user@host:$ scons po-update - scons: Reading SConscript files ... - scons: done reading SConscript files. - scons: Building targets ... - Entering '/home/ptomulik/projects/tmp' - xgettext --package-name=hello --package-version=1.0 -o - hello.c - Leaving '/home/ptomulik/projects/tmp' - Writting 'messages.pot' (new file) - msginit --no-translator -l pl -i messages.pot -o pl.po - Created pl.po. - msginit --no-translator -l en -i messages.pot -o en.po - Created en.po. - msginit --no-translator -l de -i messages.pot -o de.po - Created de.po. - scons: done building targets. +user@host:$ scons po-update +scons: Reading SConscript files ... +scons: done reading SConscript files. +scons: Building targets ... +Entering '/home/ptomulik/projects/tmp' +xgettext --package-name=hello --package-version=1.0 -o - hello.c +Leaving '/home/ptomulik/projects/tmp' +Writting 'messages.pot' (new file) +msginit --no-translator -l pl -i messages.pot -o pl.po +Created pl.po. +msginit --no-translator -l en -i messages.pot -o en.po +Created en.po. +msginit --no-translator -l de -i messages.pot -o de.po +Created de.po. +scons: done building targets. </screen> </para> <para> If everything is right, you should see following new files. <screen> - user@host:$ ls *.po* - de.po en.po messages.pot pl.po +user@host:$ ls *.po* +de.po en.po messages.pot pl.po </screen> </para> @@ -193,19 +228,19 @@ Now compile the project by executing <command>scons</command>. The output should be similar to this: <screen> - user@host:$ scons - scons: Reading SConscript files ... - scons: done reading SConscript files. - scons: Building targets ... - msgfmt -c -o de.mo de.po - msgfmt -c -o en.mo en.po - gcc -o hello.o -c hello.c - gcc -o hello hello.o - Install file: "de.mo" as "locale/de/LC_MESSAGES/hello.mo" - Install file: "en.mo" as "locale/en/LC_MESSAGES/hello.mo" - msgfmt -c -o pl.mo pl.po - Install file: "pl.mo" as "locale/pl/LC_MESSAGES/hello.mo" - scons: done building targets. +user@host:$ scons +scons: Reading SConscript files ... +scons: done reading SConscript files. +scons: Building targets ... +msgfmt -c -o de.mo de.po +msgfmt -c -o en.mo en.po +gcc -o hello.o -c hello.c +gcc -o hello hello.o +Install file: "de.mo" as "locale/de/LC_MESSAGES/hello.mo" +Install file: "en.mo" as "locale/en/LC_MESSAGES/hello.mo" +msgfmt -c -o pl.mo pl.po +Install file: "pl.mo" as "locale/pl/LC_MESSAGES/hello.mo" +scons: done building targets. </screen> SCons automatically compiled the <literal>PO</literal> files to binary format <literal>MO</literal>, and the <literal>InstallAs</literal> lines installed @@ -214,16 +249,16 @@ <para> Your program should be now ready. You may try it as follows (linux): <screen> - user@host:$ LANG=en_US.UTF-8 ./hello - Welcome to beautiful world +user@host:$ LANG=en_US.UTF-8 ./hello +Welcome to beautiful world </screen> <screen> - user@host:$ LANG=de_DE.UTF-8 ./hello - Hallo Welt +user@host:$ LANG=de_DE.UTF-8 ./hello +Hallo Welt </screen> <screen> - user@host:$ LANG=pl_PL.UTF-8 ./hello - Witaj swiecie +user@host:$ LANG=pl_PL.UTF-8 ./hello +Witaj swiecie </screen> </para> <para> @@ -232,62 +267,64 @@ swiecie\n"</literal>. Run <command>scons</command> to see how scons reacts to this <screen> - user@host:$scons - scons: Reading SConscript files ... - scons: done reading SConscript files. - scons: Building targets ... - msgfmt -c -o pl.mo pl.po - Install file: "pl.mo" as "locale/pl/LC_MESSAGES/hello.mo" - scons: done building targets. +user@host:$scons +scons: Reading SConscript files ... +scons: done reading SConscript files. +scons: Building targets ... +msgfmt -c -o pl.mo pl.po +Install file: "pl.mo" as "locale/pl/LC_MESSAGES/hello.mo" +scons: done building targets. </screen> </para> <para> Now, open <filename>hello.c</filename> and add another one <literal>printf</literal> line with new message. - <programlisting> - /* hello.c */ - #include <stdio.h> - #include <libintl.h> - #include <locale.h> - int main(int argc, char* argv[]) - { - bindtextdomain("hello", "locale"); - setlocale(LC_ALL, ""); - textdomain("hello"); - printf(gettext("Hello world\n")); - printf(gettext("and good bye\n")); - return 0; - } - </programlisting> + <scons_example name="gettext_ex5"> + <file name="hello.c" printme="1"> +/* hello.c */ +#include <stdio.h> +#include <libintl.h> +#include <locale.h> +int main(int argc, char* argv[]) +{ + bindtextdomain("hello", "locale"); + setlocale(LC_ALL, ""); + textdomain("hello"); + printf(gettext("Hello world\n")); + printf(gettext("and good bye\n")); + return 0; +} + </file> + </scons_example> </para> <para> Compile project with <command>scons</command>. This time, the <command>msgmerge(1)</command> program is used by SCons to update <literal>PO</literal> file. The output from compilation is like: <screen> - user@host:$scons - scons: Reading SConscript files ... - scons: done reading SConscript files. - scons: Building targets ... - Entering '/home/ptomulik/projects/tmp' - xgettext --package-name=hello --package-version=1.0 -o - hello.c - Leaving '/home/ptomulik/projects/tmp' - Writting 'messages.pot' (messages in file were outdated) - msgmerge --update de.po messages.pot - ... done. - msgfmt -c -o de.mo de.po - msgmerge --update en.po messages.pot - ... done. - msgfmt -c -o en.mo en.po - gcc -o hello.o -c hello.c - gcc -o hello hello.o - Install file: "de.mo" as "locale/de/LC_MESSAGES/hello.mo" - Install file: "en.mo" as "locale/en/LC_MESSAGES/hello.mo" - msgmerge --update pl.po messages.pot - ... done. - msgfmt -c -o pl.mo pl.po - Install file: "pl.mo" as "locale/pl/LC_MESSAGES/hello.mo" - scons: done building targets. +user@host:$scons +scons: Reading SConscript files ... +scons: done reading SConscript files. +scons: Building targets ... +Entering '/home/ptomulik/projects/tmp' +xgettext --package-name=hello --package-version=1.0 -o - hello.c +Leaving '/home/ptomulik/projects/tmp' +Writting 'messages.pot' (messages in file were outdated) +msgmerge --update de.po messages.pot +... done. +msgfmt -c -o de.mo de.po +msgmerge --update en.po messages.pot +... done. +msgfmt -c -o en.mo en.po +gcc -o hello.o -c hello.c +gcc -o hello hello.o +Install file: "de.mo" as "locale/de/LC_MESSAGES/hello.mo" +Install file: "en.mo" as "locale/en/LC_MESSAGES/hello.mo" +msgmerge --update pl.po messages.pot +... done. +msgfmt -c -o pl.mo pl.po +Install file: "pl.mo" as "locale/pl/LC_MESSAGES/hello.mo" +scons: done building targets. </screen> </para> <para> @@ -297,38 +334,42 @@ <literal>PO</literal>) are touched (i.e. no content changes, no creation/modification time changed and so on). Let's append another line to the program (after the last printf), so its code becomes: - <programlisting> - /* hello.c */ - #include <stdio.h> - #include <libintl.h> - #include <locale.h> - int main(int argc, char* argv[]) - { - bindtextdomain("hello", "locale"); - setlocale(LC_ALL, ""); - textdomain("hello"); - printf(gettext("Hello world\n")); - printf(gettext("and good bye\n")); - printf("----------------\n"); - return a; - } - </programlisting> + <scons_example name="gettext_ex6"> + <file name="hello.c" printme="1"> +/* hello.c */ +#include <stdio.h> +#include <libintl.h> +#include <locale.h> +int main(int argc, char* argv[]) +{ + bindtextdomain("hello", "locale"); + setlocale(LC_ALL, ""); + textdomain("hello"); + printf(gettext("Hello world\n")); + printf(gettext("and good bye\n")); + printf("----------------\n"); + return a; +} + </file> + </scons_example> Compile the project. You'll see on your screen <screen> - user@host:$scons - scons: Reading SConscript files ... - scons: done reading SConscript files. - scons: Building targets ... - Entering '/home/ptomulik/projects/tmp' - xgettext --package-name=hello --package-version=1.0 -o - hello.c - Leaving '/home/ptomulik/projects/tmp' - Not writting 'messages.pot' (messages in file found to be up-to-date) - gcc -o hello.o -c hello.c - gcc -o hello hello.o - scons: done building targets. +user@host:$scons +scons: Reading SConscript files ... +scons: done reading SConscript files. +scons: Building targets ... +Entering '/home/ptomulik/projects/tmp' +xgettext --package-name=hello --package-version=1.0 -o - hello.c +Leaving '/home/ptomulik/projects/tmp' +Not writting 'messages.pot' (messages in file found to be up-to-date) +gcc -o hello.o -c hello.c +gcc -o hello hello.o +scons: done building targets. </screen> As you see, the internationalized messages ditn't change, so the <literal>POT</literal> and the rest of translation files have not even been touched. </para> </section> + +</chapter> |