Internationalizing XML data files using gettext: libaccounts-glib Reference Manual

## Internationalizing XML data files using gettext

Strings to be shown to the user which are found in the XML data files supported by libaccounts-glib can be localized to the user's language. For this purpose, a `translations` element is present to identify the gettext translation domain, which can then be used by applications which consume those strings in order to request gettext to localize the text. Thus, the burden of localization is split between the author of the data file and the application developer. The following sections will give brief explanations of how to simplify both tasks.

### Using intltool to extract translatable strings

intltool is a helper tool to make internationalization easier for application developers. Using intltool, a developer can extract the translatable strings from XML data files with ease. There are several steps that must be taken to integrate intltool to extract translatable strings, as described below.

1. Ensure that each XML data file has a `translations` element, containing the gettext tranlslation domain for the application. This will generally be the name of the package, and is often set in `configure.ac` with:

       1
       AC_SUBST([GETTEXT_PACKAGE], [$PACKAGE_TARNAME])

2. Add a `.in` to the end of the name of the XML data file. For example, rename ``my-application`.application` to ``my-application`.application.in`.

3. Translatable elements in an XML file must be marked for translation by adding an underscore at the beginning of the element name. For example, `<description>` would change to `<_description>`. An underscore prefix must also be added to the corresponding closing element.

4. The strings that are marked for translation must be extracted by intltool. This simply creates a corresponding XML data file, without the `.in` extension, and places the marked strings in the intltool cache. The following automake snippet will extract the marked strings and distribute and install the resulting provider file:

       1
       2
       3
       4
       5
       6
       7
       8
       9
       10
       11
       12
       13
       14
       15
       16
       # Extract transatable strings from .provider file
       my-provider.provider: my-provider.provider.in $(INTLTOOL_MERGE)
           $(INTLTOOL_V_MERGE) LC_ALL=C $(INTLTOOL_MERGE) $(INTLTOOL_MERGE_V_OPTIONS) --no-translations -x -u $< $@

       provider_in_file = \
           my-provider.provider.in

       providerdir = $(datadir)/accounts/providers
       provider_DATA = \
           $(providers_in_file:.provider.in=.provider)

       dist_noinst_DATA = \
           $(provider_in_file)

       CLEANFILES = \
           $(provider_DATA)

5. Add the `.in` to `po/POTFILES.in`, being sure to list the file type alongside it. For example, with a service file ``my-service`.service.in` in the `data` directory in the source tree, the `POTFILES.in` addition would be:

       1
       [type: gettext/xml]data/my-service.service.in

### Using gettext to localize translatable strings

gettext is used to show the localized versions of translatable strings that have been extracted and translated. As most use of gettext in a client application involves translatable strings only from that application, it is common practice to bind the translataion domain of the application as the default, which is normally done as follows:

    1
    bindtextdomain (GETTEXT_PACKAGE, PACKAGE_LOCALEDIR);

If the translation domain is bound in this way, then when requesting translation of text from another project, such as the XML data files used by libaccounts-glib, the domain must be specified explicitly. The `dgettext` function can be used for this purpose. As an example, for a hypothetical service `foo_service` calling dgettext could be done as follows:

    1
    2
    dgettext (ag_service_get_i18n_domain (foo_service),
              ag_service_get_description (foo_service));

This returns the translated string, which can then be shown to the user.