manual/doc/translations.txt

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

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

Where is the manual kept?
=========================

The manual is kept in a Subversion repository on svn.debian.org
as part of the Debian Installer (d-i) project.

The manual and its translations can be found in ./manual.

How to join the translation effort for an existing translation
==============================================================

Try to find out who is working on the translation and contact them.
Alternatively you can send a mail to the mailing list for your language
(debian-l10n-<language>@lists.debian.org), if one exists or to the mailing
list for the debian installer project: debian-boot@lists.debian.org.

You should also coordinate with current translators on which parts to
translate and how to submit your translations.

How to start a new translation
==============================

Starting a translation for a new language without write access to the d-i SVN
repository really is not practical. See the section on getting SVN access below;
you will also have to get a local working copy of the manual as described there.

  1. Create a new directory structure for your translation
  --------------------------------------------------------
  Use the following commands to create a copy of the English documents as a
  base for your translation. This also ensures that your translation will be
  complete and can be built. A text that has not been translated yet, will be
  included in English.
  - change directory to: ./manual/
  - cp -R en/ <lang>
    (where <lang> is the ISO code for your language: xx or xx_XX)
  - find <lang> -name .svn | xargs rm -Rf
    (this removes all .svn subdirectories)

  2. Convert revision comments
  ----------------------------
  This enables you to track changes in the original English documents.
  see 'Keeping your translation up to date' below for an explanation.
  - change directory to: ./manual/
  - ./scripts/rev-update <lang>

  3. Commit the changes to SVN
  ----------------------------
  - change directory to: ./manual/
  - svn add <lang>
  - svn ci -m "Manual: creating new translation for <lang>"

One more change is needed to get your translation building automatically:
<lang> needs to be added to the 'languages' variable in build/build.sh.
However, this is only usefull after you have translated your first couple
of chapters. Please send a request to the debian-boot mail list for your
language to be added.

Encoding
========

The default encoding for all .xml files is UTF-8. If you want to keep your
translation in UTF-8 encoding, you should use an editor that supports UTF-8
and make sure that UTF-8 encoding is selected when you open a .xml document.

If it is easier for you to work using another encoding, you will have to
specify which encoding you use in the first line of each translated document.
For example, to use ISO-8859-1 encoding (for most Western European languages),
add the following line at the top of each .xml file:
<?xml version="1.0" encoding="ISO-8859-1"?>

The use of HTML codes (like &egrave;) is possible but not advised.

Note: If you do not specify the correct encoding, your translation will fail
      to build.
Note: You should _not_ change the encoding of the following documents:
      - administrativa/contributors.xml

Translation order
=================

Suggested translation order:
- ./preface.xml, ./bookinfo.xml
- ./welcome/*.xml
- ./using-d-i/*.xml
- ./using-d-i/modules/*.xml
- ./boot-new/*.xml
- ./boot-new/modules/*.xml

Note that currently (may 10, 2004) it looks like there will be a fairly major
reorganization of parts of the manual in the next month(s).

Keeping your translation up to date
===================================

There are two perl scripts to help you keep track of changes in the original
English text of the manual. These scripts make use of special revision
comments that should be included in each file.

An original English file contains something like:
  <!-- retain these comments for translator revision tracking -->
  <!-- $Id: preface.xml 12756 2004-04-06 22:23:56Z some-user $ -->

The second line is important. It contains the filename, the revision number,
the date and time the last revision was committed and the user that committed
the last revision. The string '$Id:' is necessary for SVN to automatically
update this line each time the file is committed.

A document in a directory containing a translation should contain either:
  <!-- original version: 12756 -->
or
  <!-- original version: 12756 untranslated -->

When you translate a document, you should of course remove the word
'untranslated' from this comment.

The scripts will do several things:
- show which translated files have a different revision number from the
  original English files
- show what changes have been made in the original English file
- help you update revision comments
- help you keep track of which files have not yet been translated
You can find both scripts in the root directory for the manual. Both
scripts should be run from this directory.

The procedure below can be used for relatively simple changes. If there
have been major reorganizations in the English documents, you may have to
do additional checks to find out exactly what changes have been made.
Use 'svn st -u' before you start this procedure to check the status of
your working copy.

  1. Update your local working copy from SVN
  ------------------------------------------
  - change directory to: ./manual/
  - svn up

  2. Copy new files (if any)
  --------------------------
  If there are any new files (marked 'A' in the output from 'svn up'),
  copy them to the directory for your translation and then:
  - ./scripts/rev-update <lang>
  This will change the revision comment in the copied file to:
  <!-- original version: ##### untranslated -->
  You will also have to run 'svn add' for the new documents.

  3. Check for other changes
  --------------------------
  - ./scripts/doc-check <lang>
  If changes are listed for documents that are marked 'untranslated', you
  can copy the new English version to the directory for your translation
  by running:
  - ./scripts/cp-untrans <lang>
  (this script also runs rev-update automatically).
  If changes are listed for documents that are not marked 'untranslated',
  you can create a diff to find out what the changes are by running:
  - ./scripts/doc-check -d <lang>
  
  4. Update your translations
  ---------------------------
  Edit your translations to reflect the changes in the English documents.
  !! Don't forget to also update the revision number in the revision comment
     after you updated a translation. The revision number should be the same
     as the revision number in the new version of the English document.
  You should run './scripts/doc-check <lang>' again after you finish all updates
  and before you commit your changes to SVN; there should be no output.
  
  Other uses of the scripts
  -------------------------
  - doc-check -s <lang>: show which documents are marked untranslated
  - rev-update -u <lang>: automatically update revision numbers in the directory
    containing your translation to the revision numbers in the original English
    documents (use only after you have made sure there are no changes in content)

How to remain consistent with the installer
===========================================

It is important that your translation of the manual remains consistent with
the translation of Debian Installer and packages for your languages.

Probably the best way to do this, is to run the installer in 'expert' mode,
both in English and your own language.

As strings and their translations in the installer may change, you may have
to perform an installation once in a while to check if there have been
important changes (the main burden to check for changes in strings falls on
the maintainers of the English original, but if you spot inconsistencies,
please report them to the debian-boot list).

You can also use the xx(_XX).po files for packages (including d-i) to see
how strings have been translated. For more information on these files,
please refer to the translations.txt file in the parent directory of the
directory where this file is.

You can also try contacting the translator for a package or the maillist
for your language (debian-l10n-<language>@lists.debian.org) to try to clear
questions about translations.

How to test your work
=====================

When you have finished your translation, always re-read your file at
least once to correct all meaning-, spelling-, grammar-, typo-, etc-
mistakes.

You can also try to build the manual (create HTML pages) for a specific
architecture for your language.
See ./build/README for more information on building the manual.

How to get write access to the SVN repository
=============================================

  1) Installing subversion
  ------------------------

  You need to install subversion on your system. Just do
     apt-get install subversion
  
  2) Getting write access to the subversion repository
  ----------------------------------------------------

  If you are not a Debian Developer, you first need to create a guest account
  on http://alioth.debian.org/, than ask on debian-boot@lists.debian.org
  for somebody to add your guest account to the debian-installer project.
 
  3) Using subversion to get files
  --------------------------------

  Once your account is allowed to write to the project, you can retrieve the
  full project using this:
    svn co svn+ssh://<username>@svn.debian.org/svn/d-i/trunk
  If you only want to work on the manual, you can retrieve the relevant part
  of the repository using:
    svn co svn+ssh://<username>@svn.debian.org/svn/d-i/trunk/manual

  4) Commit your changed translation files to SVN
  -----------------------------------------------

  After you have finished editing your translation, use
    svn commit -m "Your comment about this commit"
  to commit your changes to the SVN repository.

  Note: it's possible to do an anonymous checkout from the svn
        (use svn co svn://svn.debian.org/d-i/trunk/manual).
        However, from this local copy you aren't able to commit, it's readonly.
        Use the commands listed under 3) if you plan to do commits in the future.


You can find a good manual for SVN at http://svnbook.red-bean.com/.

How to get help
===============

If you need further assistance, feel free to ask for help on
debian-boot (for debian-installer related stuff) or debian-i18n (for
l10n related questions) Debian mailing lists.

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

This guide is supposed to be be a first start for translators.  There
are probably errors.  Please fix it if you find errors.

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

2010-05-01 Tapio Lehtonen
 - Typo fixes

2006-07-14 Frans Pop
 - Correct and update information on subversion checkout

2005-10-07 Frans Pop
 - Location of manual changed in the d-i SVN repository

2005-02-12 Frans Pop
 - Minor corrections

2004-12-27 Frans Pop
 - Updated svn checkout info to refer to new server (costa)

2004/10/26 Holger Wansing
 - Added a chapter about how to commit + fixed the Link to the svnbook

2004/09/27 Frans Pop
 - Update in line with changes in SVN (moved files/directories)

2004/09/04 Guillem Jover
 - Refer to Adam Conrad's subversion backport instead

2004/06/04 Frans Pop
 - Added paragraph on updating translations

2004/05/10 Frans Pop
 - file creation

2005/07/28 Cristian Rigamonti
 - Added cp-untrans, fixed svn command and some typos
1	fjpop-guest	15141	Debian Installation Manual - notes for translation
2			--------------------------------------------------
3
4			Note: if you happen to modify this file, please don't forget to
5			update the trailing changelog
6
7			Where is the manual kept?
8			=========================
9
10	fjpop-guest	25592	The manual is kept in a Subversion repository on svn.debian.org
11	fjpop-guest	15141	as part of the Debian Installer (d-i) project.
12
13	fjp	31243	The manual and its translations can be found in ./manual.
14	fjpop-guest	15141
15			How to join the translation effort for an existing translation
16			==============================================================
17
18			Try to find out who is working on the translation and contact them.
19			Alternatively you can send a mail to the mailing list for your language
20			(debian-l10n-<language>@lists.debian.org), if one exists or to the mailing
21			list for the debian installer project: debian-boot@lists.debian.org.
22
23			You should also coordinate with current translators on which parts to
24			translate and how to submit your translations.
25
26			How to start a new translation
27			==============================
28
29			Starting a translation for a new language without write access to the d-i SVN
30	fjp	29560	repository really is not practical. See the section on getting SVN access below;
31	fjpop-guest	15141	you will also have to get a local working copy of the manual as described there.
32
33			1. Create a new directory structure for your translation
34			--------------------------------------------------------
35			Use the following commands to create a copy of the English documents as a
36			base for your translation. This also ensures that your translation will be
37	tale	63046	complete and can be built. A text that has not been translated yet, will be
38	fjpop-guest	15141	included in English.
39	fjp	31243	- change directory to: ./manual/
40	fjpop-guest	15141	- cp -R en/ <lang>
41			(where <lang> is the ISO code for your language: xx or xx_XX)
42			- find <lang> -name .svn \| xargs rm -Rf
43			(this removes all .svn subdirectories)
44
45	fjpop-guest	25117	2. Convert revision comments
46	fjpop-guest	15141	----------------------------
47	tale	63046	This enables you to track changes in the original English documents.
48	fjpop-guest	15141	see 'Keeping your translation up to date' below for an explanation.
49	fjp	31243	- change directory to: ./manual/
50	fjpop-guest	22129	- ./scripts/rev-update <lang>
51	fjpop-guest	15141
52	fjpop-guest	25117	3. Commit the changes to SVN
53	fjpop-guest	15141	----------------------------
54	fjp	31243	- change directory to: ./manual/
55	fjpop-guest	15141	- svn add <lang>
56			- svn ci -m "Manual: creating new translation for <lang>"
57
58	tale	63046	One more change is needed to get your translation building automatically:
59	fjpop-guest	15141	<lang> needs to be added to the 'languages' variable in build/build.sh.
60			However, this is only usefull after you have translated your first couple
61			of chapters. Please send a request to the debian-boot mail list for your
62			language to be added.
63
64			Encoding
65			========
66
67			The default encoding for all .xml files is UTF-8. If you want to keep your
68			translation in UTF-8 encoding, you should use an editor that supports UTF-8
69			and make sure that UTF-8 encoding is selected when you open a .xml document.
70
71			If it is easier for you to work using another encoding, you will have to
72			specify which encoding you use in the first line of each translated document.
73			For example, to use ISO-8859-1 encoding (for most Western European languages),
74			add the following line at the top of each .xml file:
75			<?xml version="1.0" encoding="ISO-8859-1"?>
76
77			The use of HTML codes (like è) is possible but not advised.
78
79			Note: If you do not specify the correct encoding, your translation will fail
80			to build.
81			Note: You should _not_ change the encoding of the following documents:
82			- administrativa/contributors.xml
83
84			Translation order
85			=================
86
87			Suggested translation order:
88	fjpop-guest	22129	- ./preface.xml, ./bookinfo.xml
89	fjpop-guest	15141	- ./welcome/*.xml
90			- ./using-d-i/*.xml
91	fjpop-guest	22129	- ./using-d-i/modules/*.xml
92	fjpop-guest	15141	- ./boot-new/*.xml
93			- ./boot-new/modules/*.xml
94
95	tale	63046	Note that currently (may 10, 2004) it looks like there will be a fairly major
96	fjpop-guest	15141	reorganization of parts of the manual in the next month(s).
97
98			Keeping your translation up to date
99			===================================
100
101			There are two perl scripts to help you keep track of changes in the original
102			English text of the manual. These scripts make use of special revision
103			comments that should be included in each file.
104
105			An original English file contains something like:
106			<!-- retain these comments for translator revision tracking -->
107			<!-- $Id: preface.xml 12756 2004-04-06 22:23:56Z some-user $ -->
108
109			The second line is important. It contains the filename, the revision number,
110	tale	63046	the date and time the last revision was committed and the user that committed
111	fjpop-guest	15141	the last revision. The string '$Id:' is necessary for SVN to automatically
112			update this line each time the file is committed.
113
114			A document in a directory containing a translation should contain either:
115			<!-- original version: 12756 -->
116			or
117			<!-- original version: 12756 untranslated -->
118
119			When you translate a document, you should of course remove the word
120			'untranslated' from this comment.
121
122			The scripts will do several things:
123			- show which translated files have a different revision number from the
124			original English files
125			- show what changes have been made in the original English file
126			- help you update revision comments
127			- help you keep track of which files have not yet been translated
128			You can find both scripts in the root directory for the manual. Both
129			scripts should be run from this directory.
130
131			The procedure below can be used for relatively simple changes. If there
132			have been major reorganizations in the English documents, you may have to
133			do additional checks to find out exactly what changes have been made.
134			Use 'svn st -u' before you start this procedure to check the status of
135			your working copy.
136
137			1. Update your local working copy from SVN
138			------------------------------------------
139	fjp	31243	- change directory to: ./manual/
140	fjpop-guest	15141	- svn up
141
142			2. Copy new files (if any)
143			--------------------------
144			If there are any new files (marked 'A' in the output from 'svn up'),
145			copy them to the directory for your translation and then:
146	fjpop-guest	22129	- ./scripts/rev-update <lang>
147	fjpop-guest	15141	This will change the revision comment in the copied file to:
148			<!-- original version: ##### untranslated -->
149			You will also have to run 'svn add' for the new documents.
150
151			3. Check for other changes
152			--------------------------
153	fjpop-guest	22129	- ./scripts/doc-check <lang>
154	fjpop-guest	15141	If changes are listed for documents that are marked 'untranslated', you
155	fjp	29560	can copy the new English version to the directory for your translation
156			by running:
157			- ./scripts/cp-untrans <lang>
158			(this script also runs rev-update automatically).
159	fjpop-guest	15141	If changes are listed for documents that are not marked 'untranslated',
160			you can create a diff to find out what the changes are by running:
161	fjpop-guest	22129	- ./scripts/doc-check -d <lang>
162	fjpop-guest	15141
163	fjpop-guest	16621	4. Update your translations
164			---------------------------
165			Edit your translations to reflect the changes in the English documents.
166			!! Don't forget to also update the revision number in the revision comment
167			after you updated a translation. The revision number should be the same
168			as the revision number in the new version of the English document.
169	fjpop-guest	22129	You should run './scripts/doc-check <lang>' again after you finish all updates
170			and before you commit your changes to SVN; there should be no output.
171	fjpop-guest	16621
172	fjpop-guest	15141	Other uses of the scripts
173			-------------------------
174			- doc-check -s <lang>: show which documents are marked untranslated
175			- rev-update -u <lang>: automatically update revision numbers in the directory
176			containing your translation to the revision numbers in the original English
177			documents (use only after you have made sure there are no changes in content)
178
179			How to remain consistent with the installer
180			===========================================
181
182			It is important that your translation of the manual remains consistent with
183			the translation of Debian Installer and packages for your languages.
184
185			Probably the best way to do this, is to run the installer in 'expert' mode,
186			both in English and your own language.
187
188			As strings and their translations in the installer may change, you may have
189			to perform an installation once in a while to check if there have been
190			important changes (the main burden to check for changes in strings falls on
191	tale	63046	the maintainers of the English original, but if you spot inconsistencies,
192	fjpop-guest	15141	please report them to the debian-boot list).
193
194			You can also use the xx(_XX).po files for packages (including d-i) to see
195			how strings have been translated. For more information on these files,
196			please refer to the translations.txt file in the parent directory of the
197			directory where this file is.
198
199			You can also try contacting the translator for a package or the maillist
200			for your language (debian-l10n-<language>@lists.debian.org) to try to clear
201			questions about translations.
202
203			How to test your work
204			=====================
205
206			When you have finished your translation, always re-read your file at
207			least once to correct all meaning-, spelling-, grammar-, typo-, etc-
208			mistakes.
209
210			You can also try to build the manual (create HTML pages) for a specific
211			architecture for your language.
212			See ./build/README for more information on building the manual.
213
214			How to get write access to the SVN repository
215			=============================================
216
217			1) Installing subversion
218			------------------------
219
220	fjp	39044	You need to install subversion on your system. Just do
221			apt-get install subversion
222	fjpop-guest	15141
223			2) Getting write access to the subversion repository
224			----------------------------------------------------
225
226	fjpop-guest	25592	If you are not a Debian Developer, you first need to create a guest account
227	fjpop-guest	15141	on http://alioth.debian.org/, than ask on debian-boot@lists.debian.org
228			for somebody to add your guest account to the debian-installer project.
229
230			3) Using subversion to get files
231			--------------------------------
232
233	fjpop-guest	25592	Once your account is allowed to write to the project, you can retrieve the
234	fjpop-guest	15141	full project using this:
235	fjp	39044	svn co svn+ssh://<username>@svn.debian.org/svn/d-i/trunk
236	fjpop-guest	15141	If you only want to work on the manual, you can retrieve the relevant part
237			of the repository using:
238	fjp	39044	svn co svn+ssh://<username>@svn.debian.org/svn/d-i/trunk/manual
239	fjpop-guest	15141
240	holger-guest	23495	4) Commit your changed translation files to SVN
241			-----------------------------------------------
242	fjpop-guest	15141
243	holger-guest	23495	After you have finished editing your translation, use
244			svn commit -m "Your comment about this commit"
245			to commit your changes to the SVN repository.
246
247	tale	63046	Note: it's possible to do an anonymous checkout from the svn
248	fjp	39044	(use svn co svn://svn.debian.org/d-i/trunk/manual).
249	holger-guest	23495	However, from this local copy you aren't able to commit, it's readonly.
250	tale	63046	Use the commands listed under 3) if you plan to do commits in the future.
251	holger-guest	23495
252
253			You can find a good manual for SVN at http://svnbook.red-bean.com/.
254
255	fjpop-guest	15141	How to get help
256			===============
257
258			If you need further assistance, feel free to ask for help on
259			debian-boot (for debian-installer related stuff) or debian-i18n (for
260			l10n related questions) Debian mailing lists.
261
262			--------------------------------------------------------------------------
263
264			This guide is supposed to be be a first start for translators. There
265			are probably errors. Please fix it if you find errors.
266
267			--------------------------------------------------------------------------
268			Changelog:
269
270	tale	63046	2010-05-01 Tapio Lehtonen
271			- Typo fixes
272
273	fjp	39044	2006-07-14 Frans Pop
274			- Correct and update information on subversion checkout
275
276	fjp	31243	2005-10-07 Frans Pop
277			- Location of manual changed in the d-i SVN repository
278
279	fjpop-guest	25592	2005-02-12 Frans Pop
280			- Minor corrections
281
282	fjpop-guest	24583	2004-12-27 Frans Pop
283			- Updated svn checkout info to refer to new server (costa)
284
285	holger-guest	23495	2004/10/26 Holger Wansing
286	fjp	39044	- Added a chapter about how to commit + fixed the Link to the svnbook
287	holger-guest	23495
288	fjpop-guest	22129	2004/09/27 Frans Pop
289			- Update in line with changes in SVN (moved files/directories)
290
291	guillem	20762	2004/09/04 Guillem Jover
292	fjp	39044	- Refer to Adam Conrad's subversion backport instead
293	guillem	20762
294	fjpop-guest	16621	2004/06/04 Frans Pop
295			- Added paragraph on updating translations
296
297	fjpop-guest	15141	2004/05/10 Frans Pop
298			- file creation
299	fjp	29560
300			2005/07/28 Cristian Rigamonti
301			- Added cp-untrans, fixed svn command and some typos