<?xml version='1.0' encoding='utf-8' ?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % BOOK_ENTITIES SYSTEM "AppStream.ent">
%BOOK_ENTITIES;
]>

<section id="sect-Quickstart-Translation">
	<title>Translating Metadata</title>

	<section id="qsr-l10n-introduction">
		<title>Introduction</title>
		<para>
			Most AppStream metadata can be translated, This page contains some practical instructions how to translate the
			metadata.
		</para>

		<note>
			<title>For KDE developers</title>
			<para>
				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 <filename>*.metainfo.xml*</filename> (or <filename>*.appdata.xml*</filename> file)
				at a sane place, and the l10n-script will translate the file in-place automatically.
			</para>
		</note>
	</section>

	<section id="qsr-l10n-selection">
		<title>Selecting strings for translation</title>

		<para>
			By default, all strings in a MetaInfo file that are in translatable elements will be marked for translation.
			If you are using <literal>xgettext</literal>, <literal>itstool</literal> 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 <code>translate="no"</code> attribute to it.
		</para>
		<para>
			One special case is the <code>description</code> 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 <code>translate="no"</code> to the <code>description</code>
			element. It is generally discouraged to not translate component descriptions, so please use this with care!
		</para>
	</section>

	<section id="qsr-l10n-itstool">
		<title>Translating using Itstool</title>

		<para>
			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 <filename>.its</filename> file with translation definitions.
			This file is installed with Gettext, but a more recent version is also shipped by AppStream, so make sure <literal>appstream</literal>
			itself is installed to get more complete translations.
		</para>

		<para>
			To extract a GNU Gettext <filename>.pot</filename> file from your XML file, run itstool with the follwing arguments (replacing "foo" with
			your project name):
		</para>
		<programlisting language="Bash"><![CDATA[itstool -o $podir/foo_metadata.pot data/foo.metainfo.xml]]></programlisting>

		<para>
			You can then translate the <filename>.pot</filename> file using the standard methods for translating files like these. You obtain
			<filename>.po</filename> files, which you can convert into <filename>.mo</filename> files (using msgfmt) like you would do with any
			other localization. Then, you need to call <command>itstool</command> again, to create a translated version of the original XML file:
		</para>
		<programlisting language="Bash"><![CDATA[itstool -j data/foo.metainfo.xml -o output/foo.metainfo.xml $modir/*.mo]]></programlisting>

		<para>
			Please ensure that the <filename>.mo</filename> files in <filename>$modir</filename> are named with their language codes.
		</para>

		<note>
			<para>
				You can find more information about Itstool <ulink url="http://itstool.org/">on their homepage</ulink>.
			</para>
		</note>

		<section id="qsr-l10n-itstool-meson">
			<title>Integrating with Meson</title>
			<para>
				First add your MetaInfo file to your <filename>POTFILES.in</filename> file and use Gettext for extraction
				of translatable elements:
			</para>
			<programlisting language="Meson"><![CDATA[i18n = import('i18n')

i18n_result = i18n.gettext(gettext_domain,
    preset : 'glib',
)]]></programlisting>
			<para>
				To then apply the translated data to the MetaInfo XML file, you can use the built-in <code>itstool_join</code> function:
			</para>
			<programlisting language="Meson"><![CDATA[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,
)]]></programlisting>

		</section>

	</section>
</section>
