intltool README
=======================

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 modeled on gettextize.)


How to Use
----------

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

	AC_PROG_INTLTOOL([minimum required version])

 o Add intltool-extract.in, intltool-merge.in and intltool-update.in
   to EXTRA_DIST in your top-level Makefile.am and also to the
   top-level .cvsignore. Also add the non-.in versions to .cvsignore

 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 listed in the USED file.

Details of the AC_PROG_INTLTOOL macro
-------------------------------------------

The parameter indicates the minimum required version. The
configure script will halt if the version is older than
the parameter.

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

 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.png
        Terminal=0
        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 .oafinfo or .oaf)
.............................

To get server translation extraction and merging requires a few more steps:

 o Rename your .oafinfo (or .oaf) files to .oaf.in or .server.in and put an
   underscore before every value property for string attributes that should
   be localized.

 o Add the new .oaf.in or .server.in files to POTFILES.in.

 o Put lines like these in every Makefile.am that installs oaf files:
 
	--- start ----
 
	oafdir = $(datadir)/oaf
 
	oaf_in_files = My_OAF_info_file.oaf.in
	oaf_DATA = $(oaf_in_files:.oaf.in=.oaf)
 
	@INTLTOOL_OAF_RULE@
 
	EXTRA_DIST=$(oaf_in_files) $(oaf_DATA)
 
	--- end ----

At this point, your oaf translations will be extracted and
merged. Also, so long as you are renaming the .oafinfo files to
.oaf.in, you should take the opportunity to rename them to the new base
naming convention, with namespacing, for example:

	foo.oafinfo --> GNOME_Foo.oaf.in
	foo-baa.oafinfo --> GNOME_Foo_baa.oaf.in


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 .