~intltool/intltool/trunk

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).