← Back to branch summary

~ubuntu-branches/ubuntu/vivid/installation-guide/vivid-proposed

« back to all changes in this revision

Viewing changes to translations_po.txt

  • Committer: Bazaar Package Importer
  • Author(s): Frans Pop
  • Date: 2005-10-25 17:37:25 UTC
  • Revision ID: james.westby@ubuntu.com-20051025173725-aq0bm11be7bfd7rw
Tags: 20051025
http://bugs.debian.org/334925
* Mention in copyright that full GPL is included in the manual.
  Closes: #334925
* Register installed documents with doc-base.
* Minor updates in English text and translations.

Show diffs side-by-side

added added

removed removed

Lines of Context:
translations_po.txt
 
1
Debian Installation Manual - notes for translation
 
2
--------------------------------------------------
 
3
 
 
4
This file explains how to translate the manual using .po files.
 
5
This is now officially supported.
 
6
 
 
7
!!! For general information on translating the manual, please see the
 
8
!!! translations.txt file.
 
9
 
 
10
Note: if you happen to modify this file, please don't forget to
 
11
      update the trailing changelog
 
12
 
 
13
Background information
 
14
======================
 
15
There are currently two toolsets that support translating XML files using .po
 
16
files: KDE's poxml and po4a. We have chosen poxml as that gives better context
 
17
(it does not split paragraphs) for translation.
 
18
The downside of the poxml tools is that they require the .xml files to be
 
19
"proper" XML. Because some of the individual files in the English
 
20
original are not proper XML, we've had to "integrate" the files per chapter.
 
21
 
 
22
This means that instead of translating about 160 small files, you will be
 
23
translating about 15 large files.
 
24
 
 
25
Current limitations
 
26
===================
 
27
Building from PO files is currently not supported in the Sarge branch of d-i's
 
28
SVN repository. This is however not a real problem as the XML files created
 
29
from the PO files are used to synchronise the Sarge branch from trunk.
 
30
Therefore translators should not worry about this.
 
31
 
 
32
Requirements
 
33
============
 
34
The following packages need to be installed on your system:
 
35
- gettext
 
36
- poxml
 
37
- gawk
 
38
 
 
39
Available tools
 
40
===============
 
41
You will not be using poxml itself, but rather some scripts that call the
 
42
poxml tools.
 
43
 
 
44
- ./scripts/merge_xml  : merges the small .xml files into larger files
 
45
- ./scripts/update_pot : creates (new) .pot templates based on integrated
 
46
                         English .xml files
 
47
- ./scripts/revert_pot : used to revert changes in POT files to avoid
 
48
                         accidental commits
 
49
- ./scripts/update_po  : updates your .po files when there are changes in the
 
50
                         English text (the .pot templates)
 
51
- ./scripts/create_xml : creates translated .xml files from the merged English
 
52
                         .xml files and the translated .po files
 
53
- ./scripts/create_po  : used to convert an existing .xml translation to
 
54
                         using .po files
 
55
- ./scripts/set_untranslated : used for the conversion of existing translations
 
56
 
 
57
All scripts should be run from the ./manual directory and take the language as
 
58
parameter.
 
59
 
 
60
 
 
61
Starting a new translation
 
62
==========================
 
63
This procedure should only be used if there is no existing translation using
 
64
XML files for your language! See the section on conversion below if you want
 
65
to switch from translating XML files to using PO files.
 
66
 
 
67
The template files for the manual are available in ./po/pot, so all you need
 
68
to do is create a new directory for your language (using the official ISO
 
69
code for your language) and copy the .pot file you want to translate to a
 
70
.po file in that directory.
 
71
 
 
72
Example for a Dutch translation:
 
73
  - mkdir ./po/nl
 
74
  - cp ./po/pot/bookinfo.pot ./po/nl/bookinfo.po
 
75
  - <po editor> ./po/nl/bookinfo.po
 
76
 
 
77
Use your favorite PO file editor (like kbabel) to translate the .po file.
 
78
You don't need to copy all POT files straight away, just copy each one as you
 
79
start translating them.
 
80
 
 
81
  
 
82
Committing your translation
 
83
===========================
 
84
The translation can be committed to d-i's SVN repository using:
 
85
  1. svn ci ./po/<your language> -m "<some comment describing the changes>"
 
86
 
 
87
If this is the first time you commit the translation of a file, you will need
 
88
to run the 'svn add' command on the new files before you do 'svn ci'.
 
89
Tip: use the commands 'svn st ' and 'svn diff' before you commit your changes
 
90
to check what you are committing before you run the 'svn ci' command.
 
91
 
 
92
 
 
93
Updating your translation
 
94
=========================
 
95
The PO files for your language and the templates for the manual are updated
 
96
regularly when there are changes in the original English XML files.
 
97
This is done during the "daily" builds (currently done by Frans Pop); you
 
98
should not have to update your PO files yourself.
 
99
Changed strings will be marked 'fuzzy' and new strings will be untranslated.
 
100
 
 
101
After this your PO files in the ./po directory should be updated and you can
 
102
update the translation with your favorite PO file editor. To commit the
 
103
changes, follow again the procedure described in the previous section.
 
104
 
 
105
To update the POT and PO files manually, use the following commands:
 
106
  1. svn up
 
107
  2. ./scripts/merge_xml en
 
108
  3. ./scripts/update_pot
 
109
  4. ./scripts/update_po <your language>
 
110
 
 
111
NOTE
 
112
Doing this manually may result in SVN conflicts when you next 'svn up' with
 
113
the repository. The preferred method is to just wait until your PO files are
 
114
updated for you.
 
115
 
 
116
 
 
117
Building the manual yourself
 
118
============================
 
119
If you want to build a HTML version (or other format) of the manual yourself,
 
120
you will have to generate the XML for your language before you can run the
 
121
buildone.sh script. This can be useful, for example to debug build errors.
 
122
 
 
123
Use the following commands:
 
124
  1. ./scripts/merge_xml en
 
125
  2. ./scripts/update_pot
 
126
  3. ./scripts/update_po <your language>
 
127
  4. ./scripts/revert_pot
 
128
  5. ./scripts/create_xml <your language>
 
129
 
 
130
Steps 2 and 3 are necessary because the English XML files may have been
 
131
updated since the last daily build of the manual, so the POT files and your
 
132
PO files may be out-of-date. Step 4 makes sure you do not accidentally
 
133
update the POT files in the repository. They are not needed to create the
 
134
XML files or build the manual.
 
135
 
 
136
After that you can run the buildone.sh script as documented in the README in
 
137
the ./build directory. If you run buildone.sh without first generating the
 
138
XML files, you will either get an error message "unknown language" or build
 
139
from an outdated version of the XML files.
 
140
 
 
141
 
 
142
Converting an existing translation from .xml files to .po files
 
143
===============================================================
 
144
It is possible to convert an existing translation of the manual (where the
 
145
individual XML files have been translated) to using PO files.
 
146
There are two important conditions:
 
147
- the translation must be up-to-date with the English XML files;
 
148
- the translation must have same structure as the English XML files (i.e.
 
149
  the translation must have the same chapters, sections, paragraphs, tables,
 
150
  examples, etc; you can have no 'extra' paragraphs in your translation).
 
151
 
 
152
The first condition does not mean that everything needs to be translated!
 
153
 
 
154
The conversion is fairly difficult and some checks need to be done after some
 
155
of the steps.
 
156
If you would like to switch, please contact Frans Pop <aragorn@tiscali.nl>.
 
157
 
 
158
--------------------------------------------------------------------------
 
159
 
 
160
If you find any errors in this file, please fix them.
 
161
 
 
162
--------------------------------------------------------------------------
 
163
Changelog:
 
164
 
 
165
2005-04-19 Frans Pop
 
166
 - Finally rewrite this file following official implementation of PO file
 
167
   translation over a month ago...
 
168
 - Reflect the changed file structure in the ./po directory
 
169
 
 
170
2005-02-15 Frans Pop
 
171
 - Corrected the location where generated XML files are written
 
172
 
 
173
2005-02-14 Frans Pop
 
174
 - Corrected an error in the name of one script
 
175
 - Clarified the difference between starting a new translation and
 
176
   converting an existing one
 
177
 
 
178
2005-02-12 Frans Pop
 
179
 - First version