trunk/manual/translations_po.txt

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

This file explains how to translate the manual using .po files.
This is not yet officially supported, but the necessary tools are already
available and some languages are already using this method.

!!! 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
===================
The use of .po files for translating the manual is not yet officially
supported. This means that some things that will eventually be automated,
will now have to be done manually.
You are also not yet allowed to check in your .po files into d-i's SVN
repository. Instead, you have to check in the integrated translated .xml files
that can be created from the .po files.

If there is more than one person working on the translation, this means you
will have to find some other way to give everybody access to the .po files.

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/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.

Run the following commandsi to start a new translation:
  1. ./scripts/merge_xml en
  2. ./scripts/update_pot

The first command will create a directory ./integrated and in that the
integrated XML files for English.
The second command creates a directory ./po and in that the .pot template
files.

You can now start translating! Just copy a .pot file to a .<lang>.po file and
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.

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

Committing your translation
===========================
Run the following command:
  1. ./scripts/create_xml <your language>

This command will create translated XML files for your language in a
new directory named './<your language>.new'.

You next have to copy these files to their regular location and commit them
to the repository:
  2. cp -r ./<your language>.new/* ./<your language>/
  3. svn ci <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.

NOTE
You should *not* run 'svn up' between the moment you last updated the .pot
templates and your .po files and the moment you create the .xml files for your
translation!

Updating your translation
=========================
When there are changes in the original English files, you will need to update
your .po files. Changed strings will be marked 'fuzzy' and new strings will be
untranslated.

Run the following commands:
  1. svn up
  2. ./scripts/merge_xml en
  3. ./scripts/update_pot
  4. ./scripts/update_po <your language>

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.

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-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	25596	This is not yet officially supported, but the necessary tools are already
6	fjpop-guest	25593	available and some languages are already using this method.
7
8			!!! For general information on translating the manual, please see the
9			!!! translations.txt file.
10
11			Note: if you happen to modify this file, please don't forget to
12			update the trailing changelog
13
14			Background information
15			======================
16			There are currently two toolsets that support translating XML files using .po
17			files: KDE's poxml and po4a. We have chosen poxml as that gives better context
18			(it does not split paragraphs) for translation.
19			The downside of the poxml tools is that they require the .xml files to be
20			"proper" XML. Because some of the individual files in the English
21			original are not proper XML, we've had to "integrate" the files per chapter.
22
23	fjpop-guest	25596	This means that instead of translating about 160 small files, you will be
24	fjpop-guest	25593	translating about 15 large files.
25
26			Current limitations
27			===================
28			The use of .po files for translating the manual is not yet officially
29			supported. This means that some things that will eventually be automated,
30			will now have to be done manually.
31			You are also not yet allowed to check in your .po files into d-i's SVN
32	fjpop-guest	25596	repository. Instead, you have to check in the integrated translated .xml files
33	fjpop-guest	25593	that can be created from the .po files.
34
35			If there is more than one person working on the translation, this means you
36			will have to find some other way to give everybody access to the .po files.
37
38			Requirements
39			============
40	fjpop-guest	25596	The following packages need to be installed on your system:
41	fjpop-guest	25593	- gettext
42			- poxml
43			- gawk
44
45			Available tools
46			===============
47			You will not be using poxml itself, but rather some scripts that call the
48			poxml tools.
49
50			- ./scripts/merge_xml : merges the small .xml files into larger files
51			- ./scripts/update_pot : creates (new) .pot templates based on integrated
52			English .xml files
53			- ./scripts/update_po : updates your .po files when there are changes in the
54			English text (the .pot templates)
55			- ./scripts/create_xml : creates translated .xml files from the merged English
56			.xml files and the translated .po files
57			- ./scripts/create_po : used to convert an existing .xml translation to
58			using .po files
59	fjpop-guest	25631	- ./scripts/set_untranslated : used for the conversion of existing translations
60	fjpop-guest	25593
61			All scripts should be run from the ./manual directory and take the language as
62			parameter.
63
64			Starting a new translation
65			==========================
66	fjpop-guest	25631	This procedure should only be used if there is no existing translation using
67			XML files for your language! See the section on conversion below if you want
68			to switch from translating XML files to using .po files.
69
70			Run the following commandsi to start a new translation:
71	fjpop-guest	25593	1. ./scripts/merge_xml en
72	fjpop-guest	25631	2. ./scripts/update_pot
73	fjpop-guest	25593
74			The first command will create a directory ./integrated and in that the
75			integrated XML files for English.
76			The second command creates a directory ./po and in that the .pot template
77			files.
78
79			You can now start translating! Just copy a .pot file to a .<lang>.po file and
80			use your favorite .po file editor (like kbabel) to translate the .po file.
81	fjpop-guest	25596	You don't need to copy all .pot files straight away, just copy each one as you
82	fjpop-guest	25593	start translating them.
83
84			Example for a Dutch translation:
85			- cp ./po/bookinfo.pot ./po/bookinfo.nl.po
86			- <po editor> ./po/bookinfo.nl.po
87
88			Committing your translation
89			===========================
90			Run the following command:
91			1. ./scripts/create_xml <your language>
92
93	fjpop-guest	25674	This command will create translated XML files for your language in a
94			new directory named './<your language>.new'.
95
96	fjpop-guest	25593	You next have to copy these files to their regular location and commit them
97			to the repository:
98	fjpop-guest	25674	2. cp -r ./<your language>.new/* ./<your language>/
99	fjpop-guest	25593	3. svn ci <your language> -m "<some comment describing the changes>"
100
101	fjpop-guest	25596	If this is the first time you commit the translation of a file, you will need
102	fjpop-guest	25593	to run the 'svn add' command on the new files before you do 'svn ci'.
103			Tip: use the commands 'svn st ' and 'svn diff' before you commit your changes
104			to check what you are committing before you run the 'svn ci' command.
105
106			NOTE
107			You should not run 'svn up' between the moment you last updated the .pot
108			templates and your .po files and the moment you create the .xml files for your
109			translation!
110
111			Updating your translation
112			=========================
113			When there are changes in the original English files, you will need to update
114			your .po files. Changed strings will be marked 'fuzzy' and new strings will be
115			untranslated.
116
117			Run the following commands:
118			1. svn up
119			2. ./scripts/merge_xml en
120	fjpop-guest	25631	3. ./scripts/update_pot
121	fjpop-guest	25593	4. ./scripts/update_po <your language>
122
123			After this your .po files in the ./po directory should be updated and you can
124	fjpop-guest	25596	update the translation with your favorite .po file editor. To commit the
125	fjpop-guest	25593	changes, follow again the procedure described in the previous section.
126
127			Converting an existing translation from .xml files to .po files
128			===============================================================
129	fjpop-guest	25596	It is possible to convert an existing translation of the manual (where the
130			individual XML files have been translated) to using .po files.
131	fjpop-guest	25593	There are two important conditions:
132			- the translation must be up-to-date with the English XML files;
133			- the translation must have same structure as the English XML files (i.e.
134			the translation must have the same chapters, sections, paragraphs, tables,
135			examples, etc; you can have no 'extra' paragraphs in your translation).
136
137			The first condition does not mean that everything needs to be translated!
138
139			The conversion is fairly difficult and some checks need to be done after some
140			of the steps.
141			If you would like to switch, please contact Frans Pop <aragorn@tiscali.nl>.
142	fjpop-guest	25595
143			--------------------------------------------------------------------------
144
145			If you find any errors in this file, please fix them.
146
147			--------------------------------------------------------------------------
148			Changelog:
149
150	fjpop-guest	25674	2005-02-15 Frans Pop
151			- Corrected the location where generated XML files are written
152
153	fjpop-guest	25631	2005-02-14 Frans Pop
154			- Corrected an error in the name of one script
155			- Clarified the difference between starting a new translation and
156			converting an existing one
157
158	fjpop-guest	25595	2005-02-12 Frans Pop
159			- First version