1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
|
<?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>
|
