# 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 `*.appdata.xml*` or `*.metainfo.xml*` file at a sane place, and the l10n-script will translate the file in-place automatically.

## Translating using Intltool

If you ship an `.xml.in` file rather than an `.xml` file, you can use Intltool to translate the data.

Each translatable element in the `.xml.in` file needs to be prefixed with an underscore (`_`) to be marked as translatable. Apart from that, the same specifications apply to this file as for any other AppStream metadata.

TODO: Fill in some generic examples how Intltool can be used.

### Integrating with Autotools (the AppStream way)

The generic way to add translation to your AppStream metadata in case you use Autotools is by using the following code snippet:

    appstreamdir = $(datadir)/appdata/
    appstream_in_files = gedit.appdata.xml.in
    appstream_DATA = $(appstream_in_files:.xml.in=.xml)
    @INTLTOOL_XML_RULE@
    EXTRA_DIST = $(appdata_in_files)
    CLEANFILES = $(appstream_DATA)

The code assumes you are using the Intltool Automake code.

### Integrating with Autotools (the AppStream-GLib way)

In case you want to use the macro provided by the AppStream-GLib library, you can use this code snippet:

    @APPSTREAM_XML_RULES@
    appstream_in_files = gedit.appdata.xml.in
    appstream_XML = $(appstream_in_files:.xml.in=.xml)
    @INTLTOOL_XML_RULE@
    EXTRA_DIST = $(appdata_in_files)
    CLEANFILES = $(appstream_XML)

Make sure you have the additional AppStream macro installed.

## Translating using Itstool

You can also use Itstool for translation. In order to translate an XML file with it, you need an `.its` file with translation definitions. An appropriate file for AppStream upstream metadata of any kind can be found here:

    <its:rules
      xmlns:its="http://www.w3.org/2005/11/its"
      version="1.0">
      <its:translateRule translate="no" selector="/component"/>
      <its:translateRule translate="yes"
        selector="/component/name | /component/summary |
        /component/description | /component/screenshots/screenshot/caption | /component/developer_name"/>
    </its:rules>

Save this file as `as-metainfo.its` for example.

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

    itstool -i as-metainfo.its -o $podir/foo_metadata.pot data/foo.appdata.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 -i as-metainfo.its -j data/foo.appdata.xml -o output/foo.appdata.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.