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
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
|
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
<section id="gettext-xml-files">
<title>Internationalizing XML data files using gettext</title>
<para>
Strings to be shown to the user which are found in the <acronym>XML</acronym>
data files supported by libaccounts-glib can be localized to the user's
language. For this purpose, a
<sgmltag class="element" role="xml">translations</sgmltag> 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.
</para>
<section id="intltool-xml-files">
<title>
Using <application>intltool</application> to extract translatable strings
</title>
<para>
<command>intltool</command> 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.
</para>
<procedure>
<step>
<para>
Ensure that each XML data file has a
<sgmltag class="element">translations</sgmltag> element, containing the
gettext tranlslation domain for the application. This will generally be the
name of the package, and is often set in <filename>configure.ac</filename>
with:
</para>
<informalexample>
<programlisting>AC_SUBST([GETTEXT_PACKAGE], [$PACKAGE_TARNAME])</programlisting>
</informalexample>
</step>
<step>
<para>
Add a <filename class="extension">.in</filename> to the end of the name of
the XML data file. For example, rename
<filename><replaceable>my-application</replaceable>.application</filename>
to
<filename><replaceable>my-application</replaceable>.application.in</filename>.
</para>
</step>
<step>
<para>
Translatable elements in an XML file must be marked for translation by
adding an underscore at the beginning of the element name. For example,
<literal><description></literal> would change to
<literal><_description></literal>. An underscore prefix must also be
added to the corresponding closing element.
</para>
</step>
<step>
<para>
The strings that are marked for translation must be extracted by intltool.
This simply creates a corresponding XML data file, without the
<filename class="extension">.in</filename> extension, and places the
marked strings in the intltool cache. The following
<application>automake</application> snippet will extract the marked strings
and distribute and install the resulting provider file:
</para>
<informalexample>
<programlisting># 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)</programlisting>
</informalexample>
</step>
<step>
<para>
Add the <filename class="extension">.in</filename> to
<filename>po/POTFILES.in</filename>, being sure to list the file type
alongside it. For example, with a service file
<filename><replaceable>my-service</replaceable>.service.in</filename> in
the <filename class="directory">data</filename> directory in the source
tree, the <filename>POTFILES.in</filename> addition would be:
</para>
<informalexample>
<programlisting>[type: gettext/xml]data/my-service.service.in</programlisting>
</informalexample>
</step>
</procedure>
</section>
<section id="gettext-xml-files-applications">
<title>
Using <application>gettext</application> to localize translatable strings
</title>
<para>
<application>gettext</application> 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:
</para>
<informalexample>
<programlisting>bindtextdomain (GETTEXT_PACKAGE, PACKAGE_LOCALEDIR);</programlisting>
</informalexample>
<para>
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
<function>dgettext</function> function can be used for this purpose. As an
example, for a hypothetical service <varname>foo_service</varname> calling
dgettext could be done as follows:
</para>
<informalexample>
<programlisting>dgettext (ag_service_get_i18n_domain (foo_service),
ag_service_get_description (foo_service));</programlisting>
</informalexample>
<para>
This returns the translated string, which can then be shown to the user.
</para>
</section>
</section>
|
