intltool (README)
=======================

The intltool collection will do this steps:

 o Extract translatable strings from various source files (.xml.in,
   .glade, .desktop.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.

intltool has a script xml-i18n-toolize which copies the various
scripts and does the other magic to your module, so users building
from tarballs don't need xml-i18n-tools, 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 xml-i18n-toolize"
	xml-i18n-toolize --copy --force --automake

 o Add this line to configure.in near the top

	AC_PROG_XML_I18N_TOOLS([minimum required version],[ G2 | <blank> ])

 o Add xml-i18n-extract.in, xml-i18n-merge.in and xml-i18n-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.  xml-i18n-update will take
   over their funtionallity.

At this point, translatable strings will be automatically extracted to
the .po files, if you'll make use of the following special
recommendations.

xml-i18n-prepare will help you to prepare the package.  This script will
try to extract translations from existing .desktop files which will
become obsolete after xml-i18n-toolization has taken place.

Examples are listed in the USED file.

Details of the AC_PROG_XML_I18N_TOOLS macro
-------------------------------------------

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

Versions 0.9 and older can be detected through the following line:
    XML_I18N_TOOLS_NEWER_THAN_0_9 || AC_MSG_ERROR(unsatisfied dependency)

The second parameter is either [G2] (without brackets), or blank. If
left blank, this indicates that compatible behavior is required. Some
file types can be generated either as UTF-8 or mixed encoding;
without [G2], this can be controlled through Makefile.am variables. If
[G2] is specified, all files will be generated as UTF-8 files, with no
need for explicit variable settings.


Extra Steps for DESKTOP Files
..............................

This step also applies for similar files (.directory, .soundlist).

 o Try to run xml-i18n-prepare.

 o Make sure xml-i18n-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)
        @XML_I18N_MERGE_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 OAFINFO Files
.............................

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

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

 o Make sure you have at least one .po file in the "po" directory.

 o Add the .oaf.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)
 
	@XML_I18N_MERGE_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 Make sure you have at least one .po file in the "po" directory.

 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)

        XML_I18N_XML_KIND=--utf8
        @XML_I18N_MERGE_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 xml-i18n-tools 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 asked for by setting
XML_I18N_XML_KIND=--pass-through in the above snippet.

Setting the XML_I18N_XML_KIND has no effect if the string [G2] has
been given as the second parameter of the AC_PROG_XML_I18N_TOOLS
macro. In that case, --utf8 is always assumed.

---

XXX: add section for KEYS files. Works almost like XML files .
The XML_UTF8_KEYS_KIND Makefile.am variable controls the kind of files
output (--pass-through for GNOME1, --utf8 for GNOME2), and is
overriden as --utf8 if [G2] has been specified.
