# Translating Metadata

## Introduction

Most AppStream metadata can be translated, This page contains some practical instructions how to translate the metadata.

For KDE developers

If you are a KDE developer and using the KDE infrastructure with it's localization support, you need to do nothing to get translated metadata. Just place your `*.metainfo.xml*` (or `*.appdata.xml*` file) at a sane place, and the l10n-script will translate the file in-place automatically.

## Selecting strings for translation

By default, all strings in a MetaInfo file that are in translatable elements will be marked for translation. If you are using `xgettext`, `itstool` or any other tool that uses ITS rules for translation, and have AppStream or AppStream's ITS rules installed, you can exclude any element from being translated by adding a `translate="no"` attribute to it.

One special case is the `description` block in MetaInfo files and release metadata. In MetaInfo files, each individual paragraph of a description (or enumerated entry) is translated individually, however you can only exclude the complete block from being translated by adding `translate="no"` to the `description` element. It is generally discouraged to not translate component descriptions, so please use this with care!

## Translating using Itstool

One good way to translate MetaInfo files besides using plain Gettext is using Itstool for translation. In order to translate an XML file with it, you need an `.its` file with translation definitions. This file is installed with Gettext, but a more recent version is also shipped by AppStream, so make sure `appstream` itself is installed to get more complete translations.

To extract a GNU Gettext `.pot` file from your XML file, run itstool with the follwing arguments (replacing "foo" with your project name):

    itstool -o $podir/foo_metadata.pot data/foo.metainfo.xml

You can then translate the `.pot` file using the standard methods for translating files like these. You obtain `.po` files, which you can convert into `.mo` files (using msgfmt) like you would do with any other localization. Then, you need to call `itstool` again, to create a translated version of the original XML file:

    itstool -j data/foo.metainfo.xml -o output/foo.metainfo.xml $modir/*.mo

Please ensure that the `.mo` files in `$modir` are named with their language codes.

You can find more information about Itstool on their homepage.

### Integrating with Meson

First add your MetaInfo file to your `POTFILES.in` file and use Gettext for extraction of translatable elements:

    i18n = import('i18n')

    i18n_result = i18n.gettext(gettext_domain,
        preset : 'glib',
    )

To then apply the translated data to the MetaInfo XML file, you can use the built-in `itstool_join` function:

    metainfo_dir = join_paths(get_option ('datadir'), 'metainfo')

    metainfo_i18n = i18n.itstool_join(
        input:  'org.example.myapp.metainfo.xml',
        output: 'org.example.myapp.metainfo.xml',
        mo_targets: i18n_result[0],
        install: true,
        install_dir: metainfo_dir,
    )