intltool README =============== If you have problems understanding this README file, then please report these at http://bugs.launchpad.net/intltool on Launchpad. Patches are also very welcome. See HACKING for more information on submitting patches. The intltool collection can be used to do these things: o Extract translatable strings from various source files (.xml.in, .glade, .desktop.in, .server.in, .oaf.in). o Collect the extracted strings together with messages from traditional source files (.c, .h) in po/$(PACKAGE).pot. o Merge back the translations from .po files into .xml, .desktop and .oaf files. This merge step will happen at build resp. installation time. The intltool package has a script, intltoolize, which copies the various scripts and does the other magic to your module. So users building from tarballs don't need intltool, only folks building from cvs. (This is modelled on gettextize.) How to Use with autoconf/automake --------------------------------- (There is a section for non-auto* configurations below) To use intltool in your module, do the following: o Install intltool, and make sure that the macro it installs is in aclocal's path, or do: export ACLOCAL_FLAGS='-I /usr/local/share/aclocal' o Add these lines to autogen.sh, after the call to gettextize: echo "Running intltoolize" intltoolize --copy --force --automake o Add this line to configure.in near the top IT_PROG_INTLTOOL([minimum required version], [no-xml]) o Add intltool-extract, intltool-merge, and intltool-update to DISTCLEANFILES in your top-level Makefile.am. o Remove po/desk.pl and po/update.* scripts. intltool-update will take over their functionality. At this point, translatable strings will be automatically extracted to the .po files, if you make use of the following recommendations. The intltool-prepare script will help you to prepare the package. It will try to extract translations from existing .desktop files which will become obsolete after intltoolization has taken place. Examples of packages that use intltool are many of the GNOME components: find them at http://git.gnome.org/. Details of the IT_PROG_INTLTOOL macro ------------------------------------------- The first parameter indicates the minimum required version. The configure script will halt if the version is older than the first parameter. The second parameter is to tell intltool that we don't need the extended xml parsing abilities provided by the XML::Parser perl module. If it is not provided, or is any value other than "no-xml", then XML::Parser will be checked for by the configure script. This feature is only available in intltool 0.31 or newer. Extra Steps for DESKTOP Files .............................. This step also applies for similar files (.directory, .soundlist). o Try to run intltool-prepare. o Make sure intltool-prepare did find existing translations in the old .desktop files and did correctly merge them into the various po/*.po files. Don't forget to commit the changed .po files; otherwise exiting translations will get lost! o Remove old .desktop files and add new .desktop.in files. o Adjust .cvsignore, .gitignore, .bzrignore or similar. o Adjust Makefile.am, e.g.: --- start ---- utilsdir = $(datadir)/gnome/apps/Utilities utils_in_files = bug-buddy.desktop.in utils_DATA = $(utils_in_files:.desktop.in=.desktop) @INTLTOOL_DESKTOP_RULE@ --- end ---- o Add .desktop.in files to po/POTFILES.in Here's a .desktop.in example: --- start ---- [Desktop Entry] _Name=Bug Report Tool _Comment=Report a bug in GNOME Exec=bug-buddy Icon=bug-buddy Terminal=false Type=Application --- end ---- Extra Steps for GLADE Files ........................... o Add the .glade files you want translated to POTFILES.in o Remove the intermediate *-glade.h or strings-glade.c files and drop them from POTFILES.in Extra Steps for SERVER Files (formerly .server) ............................. To get server translation extraction and merging requires a few more steps: o Rename your .server files to .server.in and put an underscore before every value property for string attributes that should be localized. o Add the new .server.in or .server.in files to POTFILES.in. o Put lines like these in every Makefile.am that installs oaf files: --- start ---- serverdir = $(libdir)/bonobo/servers server_in_files = My_Server_file.server.in server_DATA = $(server_in_files:.server.in=.server) @INTLTOOL_SERVER_RULE@ EXTRA_DIST=$(server_in_files) $(server_DATA) --- end ---- At this point, your server translations will be extracted and merged. Extra Steps for XML Files (Files with .xml Extension) ..................................................... To get xml (files with .xml extension) translation extraction and merging requires these steps: o Rename your .xml files to .xml.in and put an underscore before every element that should be localized. o Add the .xml.in files to POTFILES.in. o Put lines like these in every Makefile.am that installs xml files: --- start ---- xmldir = $(datadir)/xml xml_in_files = My_xml_file.xml.in xml_DATA = $(xml_in_files:.xml.in=.xml) @INTLTOOL_XML_RULE@ EXTRA_DIST=$(xml_in_files) $(xml_DATA) --- end ---- At this point, your xml translations will be extracted and merged. All .po files will be converted on the fly to UTF-8, and the resulting XML file will have a UTF-8 effective encoding (you should make sure that the encoding="..." declaration in the .xml.in file is either absent or actually specifies UTF-8). Previous versions of intltool generated XML files whose contents were made of the contents of the .po files, without paying attention to the encodings used. A single "XML" file could thus have strings in different encodings. This broken behavior can be requested only by using the old xml-i18n-tools API instead of the intltool one. See old versions of xml-i18n-tools for documentation on how the old API worked. --- XXX: add section for KEYS files. Works almost like XML files . How to use without autoconf/automake ------------------------------------ intltool can also be used without the auto* tools. For instance in order to translate a somename.desktop.in file, you can do the following. o Create a po/ dir. o Add a po/POTFILES.in file, including the path to the somename.desktop.in file Then to create the somename.desktop file all you do is: $ intltool-merge po/ -d -u -c po/.intltool-merge-cache somename.desktop.in somename.desktop You can also type intltool-merge --help for a bit more info. To specify parameters for intltool-update (such as keywords or gettext domain), you can use Makevars syntax as used in recent GNU gettext, by putting something like the following in po/Makevars file: DOMAIN = mydomain XGETTEXT_OPTIONS = --keyword --keyword=blah This will make "intltool-update -p" produce mydomain.pot, passing parameters "--keyword --keyword=blah" to xgettext when extracting strings. Passing special parameters to xgettext via environment ...................................................... If you need to add parameters passed to xgettext on a case-by-case basis, you can do so using environment variable XGETTEXT_ARGS. If you would run it as follows: XGETTEXT_ARGS=--no-location intltool-update -p You would create a PO Template file without lines which indicate location of messages in the source code. Changing keywords used in xgettext invocation ............................................. If you need to change default keywords used to extract messages from source code, you need to add variable XGETTEXT_KEYWORDS to Makefile.in.in file inside directory where intltool-update is run from, eg. --- start ---- XGETTEXT_KEYWORDS = --keyword --keyword=P_ --- end ---- Default keywords xgettext looks for if no XGETTEXT_KEYWORDS is defined are _, N_ and U_. Translators' comments in XML and .schemas files ............................................... To provide comments to translators in free-form XML or .schema files, you need to precede the string to be translated with the plain XML comment. In .schemas files, comments need to be inside <default>, <short> or <long> elements (i.e. they cannot be before the opening tag).
