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
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
|
<?xml version='1.0' encoding='utf-8' ?>
<!DOCTYPE section [
<!ENTITY % BOOK_ENTITIES SYSTEM "Users_Guide.ent">
%BOOK_ENTITIES;
<!ENTITY % sgml.features "IGNORE">
<!ENTITY % xml.features "INCLUDE">
<!ENTITY % DOCBOOK_ENTS PUBLIC "-//OASIS//ENTITIES DocBook Character Entities V4.5//EN" "/usr/share/xml/docbook/schema/dtd/4.5/dbcentx.mod">
%DOCBOOK_ENTS;
]>
<section conformance="202" version="5.0" xml:id="sect-Publican-Users_Guide-Preparing_a_document_for_translation" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<info xml:id="info-Publican-Users_Guide-Translating_a_document">
<title>Translating a document</title>
</info>
<para>
Support for localization of documents was a key consideration in the design of <application>Publican</application>. The general translation workflow for documents developed in <application>Publican</application> is as follows:
</para>
<procedure>
<step>
<para>
Complete the XML of a document.
</para>
<para>
The XML for this version of the document should now be considered ‘frozen’. If your document is stored in a version-controlled repository, you should now move this version into a separate directory or branch. This allows writers to begin work on subsequent versions of the document in one branch, while providing a stable base for translation in another branch.
</para>
</step>
<step>
<para>
Optional but recommended: <firstterm>drop</firstterm> the document to translation. Run:
</para>
<screen><prompt>$</prompt> <command>publican trans_drop</command></screen>
<para>
<application>Publican</application> creates a new subdirectory, named <filename>trans_drop/</filename>. The <filename>trans_drop/</filename> subdirectory contains a snapshot of the source files of the document. When the <filename>trans_drop/</filename> directory is present in a documentation project, <application>Publican</application> uses its content as the basis for the commands documented later in this procedure.
</para>
</step>
<step>
<para>
Generate <firstterm>portable object template</firstterm> (POT) files from the XML files:
</para>
<screen><prompt>$</prompt> <command>publican update_pot</command></screen>
<para>
If this is the first time that POT files have been created for this document, <application>Publican</application> creates a new subdirectory, named <filename>pot</filename>. The <filename>pot</filename> subdirectory holds a POT file for each XML file in the document. If <application>Publican</application> has created POT files for this document previously, <application>Publican</application> updates the existing POT files to reflect any changes in the XML since the POT files were last updated.
</para>
<important>
<info xml:id="info-Publican-Users_Guide-Remove_unused_XML_files">
<title>Remove unused XML files</title>
</info>
<para>
<application>Publican</application> generates a POT file for every XML file in the XML directory, whether the XML file is used in the document or not. If you transform unused XML files into POT files, you waste the time and effort of volunteer translators, and waste money if you are paying for translations.
</para>
<para>
Use the <prompt>$</prompt> <command>publican print_unused</command> command to generate a list of XML files that are not used in your document.
</para>
</important>
</step>
<step>
<para>
Generate <firstterm>portable object</firstterm> (PO) files from the POT files to begin translation into a particular language:
</para>
<screen><prompt>$</prompt> <command>publican update_po --langs=<replaceable>language_code</replaceable></command></screen>
<para>
where <replaceable>language_code</replaceable> is the code for the target language. Refer to <xref linkend="appe-Publican-Users_Guide-Language_codes" /> for more information about language codes. You can provide multiple language codes, separated by commas, to generate PO files for more than one language at a time. For example:
</para>
<screen><prompt>$</prompt> <command>publican update_po --langs=hi-IN,pt-BR,ru-RU,zh-CN</command></screen>
<para>
If this is the first time that PO files have been created for a particular language, <application>Publican</application> creates a new subdirectory, named with the language code that you specified with the <option>--langs=</option> option. This subdirectory holds a PO file for each POT file in <filename>pot</filename> subdirectory, plus a <filename>Revision_History.xml</filename> file that tracks the history of this particular translation. When created for the first time, the <filename>Revision_History.xml</filename> file records the date on which the PO files for this translation were created, and the version of the source language XML (taken from the source language's <filename>Revision_History.xml</filename> file) on which this translation is therefore based.
</para>
<para>
If <application>Publican</application> has created PO files for this language previously, <application>Publican</application> updates the existing PO files to reflect any changes in the POT files since the PO files were last updated, and adds a new entry to the translation's <filename>Revision_History.xml</filename> file to record the date on which the PO files for this translation were refreshed, and the version of the source language XML on which the revision is based. You can update existing PO files in every subdirectory with the <option>--langs=all</option> option:
</para>
<screen><prompt>$</prompt> <command>publican update_po --langs=all</command></screen>
<important>
<info xml:id="info-Publican-Users_Guide-Remove_unused_POT_files">
<title>Remove unused POT files</title>
</info>
<para>
<application>Publican</application> generates a PO file for every POT file in the <filename>pot</filename> directory, whether the POT file is based on a corresponding XML file that is used in the document or not, or whether a corresponding XML file even exists. If you transform POT files for unused or deleted XML files into PO files, you waste the time and effort of volunteer translators, and waste money if you are paying for translations.
</para>
<para>
When you generate PO files, <application>Publican</application> presents you with a warning for any POT files that do not have corresponding XML files, but will generate the PO file nevertheless. However, <application>Publican</application> will not warn you if a POT file exists for an XML file that is not used in the document.
</para>
</important>
</step>
<step>
<para>
Translate the <firstterm>strings</firstterm> contained in the PO files.
</para>
</step>
<step>
<para>
If you are updating a previously published translation <emphasis>of this revision in the source language</emphasis>, use <application>Publican</application>'s <command>publican add_revision</command> command to describe your changes or corrections. <application>Publican</application> updates the <filename>Revision_History.xml</filename> file for you.
</para>
<para>
If the document has changed in its original language, use the <command>publican trans_drop</command>, <command>publican update_pot</command>, and <command>publican update_po</command> commands as described earlier in this procedure instead.
</para>
</step>
<step>
<para>
Build the document in the target language, for example:
</para>
<screen><prompt>$</prompt> <command>publican build --formats=html,html-single,pdf --langs=is-IS,nb-NO</command></screen>
<para>
or package it in the target language, for example:
</para>
<screen><prompt>$</prompt> <command>publican package --lang=is-IS</command></screen>
<para>
You can build the document in all languages for which you have translations with the <option>--langs=all</option> option, but note that you must package each language individually. Refer to <xref linkend="sect-Publican-Users_Guide-Building_a_document" /> for more information on building a document, and <xref linkend="sect-Publican-Users_Guide-Packaging_a_document" /> on packaging a document.
</para>
</step>
</procedure>
<section conformance="203" xml:id="sect-Publican-Users_Guide-Preparing_a_document_for_translation-Translation_Author_Group">
<info xml:id="info-Publican-Users_Guide-Translation_Author_Group">
<title>Translation Author Group</title>
</info>
<para>
Translation takes place after a book has been finalized. You do not need to know who will translate your book in order to give them credit. Create <filename>$translation/Author_Group.xml</filename> and add a valid DocBook authorgroup. The translator can add their details to this file and <application>Publican</application> will append it to <filename>$source_lang/Author_Group.xml</filename> when the book is build. This allows authors to finalize the original text without needing to know who will translate the book.
</para>
</section>
<section conformance="250" xml:id="sect-Publican-Users_Guide-Preparing_a_document_for_translation-Translating_Glossaries">
<info xml:id="info-Publican-Users_Guide-Translating_Indexes_and_Glossaries">
<title>Translating Indexes and Glossaries</title>
</info>
<para>
DocBook automatically collates and sorts <tag><glossentry></tag> elements into a book's glossary; and <tag><primary></tag>, <tag><secondary></tag>, and <tag><tertiary></tag> <tag><indexterm></tag> elements into a book's index. Entries are sorted automatically, and although this system works well for languages written with an alphabet, abugida, or syllabic script, languages written with logograms sort less well.
</para>
<para>
To manually adjust the sort order of a glossary entry or index entry, manually add DocBook's <tag>sortas</tag> attribute to the XML element. For example, to ensure that the Japanese word 暗号化 sorts correctly in an index, specify:
</para>
<programlisting>#. Tag: indexterm
#, no-c-format
msgid "<primary>encryption</primary>"
msgstr "<primary sortas="あんごうか">暗号化</primary>"</programlisting>
<para>
Similarly, to ensure that the Japanese word 暗号化 sorts correctly in a glossary, specify:
</para>
<programlisting>#. Tag: glossentry
#, no-c-format
msgid "<glossterm>encryption</glossterm>"
msgstr "<glossterm sortas="あんごうか">暗号化</glossterm>"</programlisting>
</section>
</section>
|
