xml-i18n-tools (README)
=======================

The xml-i18n-tools 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.

xml-i18n-tools 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 xml-i18n-tools in your module, do the following:

 o Install xml-i18n-tools, 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

	AM_PROG_XML_I18N_TOOLS

 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.


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_MERGE_XML_RULE@

        EXTRA_DIST=$(xml_in_files) $(xml_DATA)

        --- end ----

At this point, your xml translations will be extracted and
merged.

That's it.
