manual/doc/translations_po.txt

Debian Installation Manual - notes for translation
--------------------------------------------------

This file explains how to translate the manual using .po files.
This is now officially supported.

!!! For general information on translating the manual, please see the
!!! translations.txt file.

Note: if you happen to modify this file, please don't forget to
      update the trailing changelog

Background information
======================
There are currently two toolsets that support translating XML files using .po
files: KDE's poxml and po4a. We have chosen poxml as that gives better context
(it does not split paragraphs) for translation.
The downside of the poxml tools is that they require the .xml files to be
"proper" XML. Because some of the individual files in the English
original are not proper XML, we've had to "integrate" the files per chapter.

This means that instead of translating about 160 small files, you will be
translating about 15 large files.

Current limitations
===================
Building from PO files is currently not supported in the Sarge branch of d-i's
SVN repository. This is however not a real problem as the XML files created
from the PO files are used to synchronise the Sarge branch from trunk.
Therefore translators should not worry about this.

Requirements
============
The following packages need to be installed on your system:
- gettext
- poxml
- gawk

Available tools
===============
You will not be using poxml itself, but rather some scripts that call the
poxml tools.

- ./scripts/merge_xml  : merges the small .xml files into larger files
- ./scripts/update_pot : creates (new) .pot templates based on integrated
                         English .xml files
- ./scripts/revert_pot : used to revert changes in POT files to avoid
                         accidental commits
- ./scripts/update_po  : updates your .po files when there are changes in the
                         English text (the .pot templates)
- ./scripts/create_xml : creates translated .xml files from the merged English
                         .xml files and the translated .po files
- ./scripts/create_po  : used to convert an existing .xml translation to
                         using .po files
- ./scripts/set_untranslated : used for the conversion of existing translations

All scripts should be run from the ./manual directory and take the language as
parameter.


Starting a new translation
==========================
This procedure should only be used if there is no existing translation using
XML files for your language! See the section on conversion below if you want
to switch from translating XML files to using PO files.

The template files for the manual are available in ./po/pot, so all you need
to do is create a new directory for your language (using the official ISO
code for your language) and copy the .pot file you want to translate to a
.po file in that directory.

Example for a Dutch translation:
  - mkdir ./po/nl
  - cp ./po/pot/bookinfo.pot ./po/nl/bookinfo.po
  - <po editor> ./po/nl/bookinfo.po

Use your favorite PO file editor (like kbabel) to translate the .po file.
You don't need to copy all POT files straight away, just copy each one as you
start translating them.

  
Committing your translation
===========================
The translation can be committed to d-i's SVN repository using:
  1. svn ci ./po/<your language> -m "<some comment describing the changes>"

If this is the first time you commit the translation of a file, you will need
to run the 'svn add' command on the new files before you do 'svn ci'.
Tip: use the commands 'svn st ' and 'svn diff' before you commit your changes
to check what you are committing before you run the 'svn ci' command.


Updating your translation
=========================
The PO files for your language and the templates for the manual are updated
regularly when there are changes in the original English XML files.
This is done during the "daily" builds (currently done by Frans Pop); you
should not have to update your PO files yourself.
Changed strings will be marked 'fuzzy' and new strings will be untranslated.

After this your PO files in the ./po directory should be updated and you can
update the translation with your favorite PO file editor. To commit the
changes, follow again the procedure described in the previous section.

To update the POT and PO files manually, use the following commands:
  1. svn up
  2. ./scripts/merge_xml en
  3. ./scripts/update_pot
  4. ./scripts/update_po <your language>

NOTE
Doing this manually may result in SVN conflicts when you next 'svn up' with
the repository. The preferred method is to just wait until your PO files are
updated for you.


Building the manual yourself
============================
If you want to build a HTML version (or other format) of the manual yourself,
you will have to generate the XML for your language before you can run the
buildone.sh script. This can be useful, for example to debug build errors.

Use the following commands:
  1. ./scripts/merge_xml en
  2. ./scripts/update_pot
  3. ./scripts/update_po <your language>
  4. ./scripts/revert_pot
  5. ./scripts/create_xml <your language>

Steps 2 and 3 are necessary because the English XML files may have been
updated since the last daily build of the manual, so the POT files and your
PO files may be out-of-date. Step 4 makes sure you do not accidentally
update the POT files in the repository. They are not needed to create the
XML files or build the manual.

After that you can run the buildone.sh script as documented in the README in
the ./build directory. If you run buildone.sh without first generating the
XML files, you will either get an error message "unknown language" or build
from an outdated version of the XML files.


Converting an existing translation from .xml files to .po files
===============================================================
It is possible to convert an existing translation of the manual (where the
individual XML files have been translated) to using PO files.
There are two important conditions:
- the translation must be up-to-date with the English XML files;
- the translation must have same structure as the English XML files (i.e.
  the translation must have the same chapters, sections, paragraphs, tables,
  examples, etc; you can have no 'extra' paragraphs in your translation).

The first condition does not mean that everything needs to be translated!

The conversion is fairly difficult and some checks need to be done after some
of the steps.
If you would like to switch, please contact Frans Pop <aragorn@tiscali.nl>.

--------------------------------------------------------------------------

If you find any errors in this file, please fix them.

--------------------------------------------------------------------------
Changelog:

2005-04-19 Frans Pop
 - Finally rewrite this file following official implementation of PO file
   translation over a month ago...
 - Reflect the changed file structure in the ./po directory

2005-02-15 Frans Pop
 - Corrected the location where generated XML files are written

2005-02-14 Frans Pop
 - Corrected an error in the name of one script
 - Clarified the difference between starting a new translation and
   converting an existing one

2005-02-12 Frans Pop
 - First version
1	fjpop-guest	25593	Debian Installation Manual - notes for translation
2			--------------------------------------------------
3
4			This file explains how to translate the manual using .po files.
5	fjpop-guest	26864	This is now officially supported.
6	fjpop-guest	25593
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	fjpop-guest	25596	This means that instead of translating about 160 small files, you will be
23	fjpop-guest	25593	translating about 15 large files.
24
25			Current limitations
26			===================
27	fjpop-guest	26864	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	fjpop-guest	25593
32			Requirements
33			============
34	fjpop-guest	25596	The following packages need to be installed on your system:
35	fjpop-guest	25593	- 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	fjpop-guest	26864	- ./scripts/revert_pot : used to revert changes in POT files to avoid
48			accidental commits
49	fjpop-guest	25593	- ./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	fjpop-guest	25631	- ./scripts/set_untranslated : used for the conversion of existing translations
56	fjpop-guest	25593
57			All scripts should be run from the ./manual directory and take the language as
58			parameter.
59
60	fjpop-guest	26864
61	fjpop-guest	25593	Starting a new translation
62			==========================
63	fjpop-guest	25631	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	fjpop-guest	26864	to switch from translating XML files to using PO files.
66	fjpop-guest	25631
67	fjpop-guest	26864	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	fjpop-guest	25593
72	fjpop-guest	26864	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	fjpop-guest	25593
77	fjpop-guest	26864	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	fjpop-guest	25593	start translating them.
80
81	fjpop-guest	26864
82	fjpop-guest	25593	Committing your translation
83			===========================
84	fjpop-guest	26864	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	fjpop-guest	25593
87	fjpop-guest	25596	If this is the first time you commit the translation of a file, you will need
88	fjpop-guest	25593	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	fjpop-guest	26864	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	fjpop-guest	25593
101	fjpop-guest	26864	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	fjpop-guest	25593	1. svn up
107			2. ./scripts/merge_xml en
108	fjpop-guest	25631	3. ./scripts/update_pot
109	fjpop-guest	25593	4. ./scripts/update_po <your language>
110
111	fjpop-guest	26864	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	fjpop-guest	25593
116	fjpop-guest	26864
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	fjpop-guest	25593	Converting an existing translation from .xml files to .po files
143			===============================================================
144	fjpop-guest	25596	It is possible to convert an existing translation of the manual (where the
145	fjpop-guest	26864	individual XML files have been translated) to using PO files.
146	fjpop-guest	25593	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	fjpop-guest	25595
158			--------------------------------------------------------------------------
159
160			If you find any errors in this file, please fix them.
161
162			--------------------------------------------------------------------------
163			Changelog:
164
165	fjpop-guest	26864	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	fjpop-guest	25674	2005-02-15 Frans Pop
171			- Corrected the location where generated XML files are written
172
173	fjpop-guest	25631	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	fjpop-guest	25595	2005-02-12 Frans Pop
179			- First version