← Back to branch summary

~qbalazs/installation-guide/lp1030336

« back to all changes in this revision

Viewing changes to translations.txt

  • Committer: joeyh
  • Date: 2005-10-07 19:51:38 UTC
  • Revision ID: vcs-imports@canonical.com-20051007195138-c3d57b2617a79a4f
move manual to top-level directory, split out of debian-installer package

Show diffs side-by-side

added added

removed removed

Lines of Context:
translations.txt
 
1
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
The manual is kept in a Subversion repository on svn.debian.org
 
11
as part of the Debian Installer (d-i) project.
 
12
 
 
13
The manual and its translations can be found in ./installer/doc/manual.
 
14
 
 
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
repository really is not practical. See the section on getting SVN access below;
 
31
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
  complete and can be build. A text that has not be translated yet, will be
 
38
  included in English.
 
39
  - change directory to: installer/doc/manual/
 
40
  - 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
  2. Convert revision comments
 
46
  ----------------------------
 
47
  This enables you to track changes is the original English documents.
 
48
  see 'Keeping your translation up to date' below for an explanation.
 
49
  - change directory to: installer/doc/manual/
 
50
  - ./scripts/rev-update <lang>
 
51
 
 
52
  3. Commit the changes to SVN
 
53
  ----------------------------
 
54
  - change directory to: installer/doc/manual/
 
55
  - svn add <lang>
 
56
  - svn ci -m "Manual: creating new translation for <lang>"
 
57
 
 
58
One more change is needed to get your translation build automatically:
 
59
<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 &egrave;) 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
- ./preface.xml, ./bookinfo.xml
 
89
- ./welcome/*.xml
 
90
- ./using-d-i/*.xml
 
91
- ./using-d-i/modules/*.xml
 
92
- ./boot-new/*.xml
 
93
- ./boot-new/modules/*.xml
 
94
 
 
95
Note that currently (may 10, 2004) it look like there will be a fairly major
 
96
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
the date and time the last revision was committed, the user that committed
 
111
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
  - change directory to: installer/doc/manual/
 
140
  - 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
  - ./scripts/rev-update <lang>
 
147
  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
  - ./scripts/doc-check <lang>
 
154
  If changes are listed for documents that are marked 'untranslated', you
 
155
  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
  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
  - ./scripts/doc-check -d <lang>
 
162
  
 
163
  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
  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
  
 
172
  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
the maintainers of the English original, but is you spot inconsistencies,
 
192
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
  You need to install subversion on your system. For Debian unstable users,
 
221
  just do "apt-get install svn".
 
222
  
 
223
  Others may use backports from www.backports.org. Please add this entry to
 
224
  your /etc/apt/sources.list file:
 
225
    deb http://www.backports.org/debian stable subversion
 
226
  Or use Adam Conrad's backports:
 
227
    deb http://people.debian.org/~adconrad woody subversion
 
228
 
 
229
  2) Getting write access to the subversion repository
 
230
  ----------------------------------------------------
 
231
 
 
232
  If you are not a Debian Developer, you first need to create a guest account
 
233
  on http://alioth.debian.org/, than ask on debian-boot@lists.debian.org
 
234
  for somebody to add your guest account to the debian-installer project.
 
235
 
 
236
  3) Using subversion to get files
 
237
  --------------------------------
 
238
 
 
239
  Once your account is allowed to write to the project, you can retrieve the
 
240
  full project using this:
 
241
    svn co svn+ssh://<username>@svn.d-i.alioth.debian.org/svn/d-i/trunk debian-installer
 
242
  If you only want to work on the manual, you can retrieve the relevant part
 
243
  of the repository using:
 
244
    svn co svn+ssh://<username>@svn.d-i.alioth.debian.org/svn/d-i/trunk/installer/doc
 
245
 
 
246
  4) Commit your changed translation files to SVN
 
247
  -----------------------------------------------
 
248
 
 
249
  After you have finished editing your translation, use
 
250
    svn commit -m "Your comment about this commit"
 
251
  to commit your changes to the SVN repository.
 
252
 
 
253
  Note: it's possible, to do an anonymous checkout from the svn
 
254
        (use svn co svn://svn.d-i.alioth.debian.org/d-i/trunk/installer/doc/manual).
 
255
        However, from this local copy you aren't able to commit, it's readonly.
 
256
        Use the commands listed under 3), if you plan to do commits in the future.
 
257
 
 
258
 
 
259
You can find a good manual for SVN at http://svnbook.red-bean.com/.
 
260
 
 
261
How to get help
 
262
===============
 
263
 
 
264
If you need further assistance, feel free to ask for help on
 
265
debian-boot (for debian-installer related stuff) or debian-i18n (for
 
266
l10n related questions) Debian mailing lists.
 
267
 
 
268
--------------------------------------------------------------------------
 
269
 
 
270
This guide is supposed to be be a first start for translators.  There
 
271
are probably errors.  Please fix it if you find errors.
 
272
 
 
273
--------------------------------------------------------------------------
 
274
Changelog:
 
275
 
 
276
2005-02-12 Frans Pop
 
277
 - Minor corrections
 
278
 
 
279
2004-12-27 Frans Pop
 
280
 - Updated svn checkout info to refer to new server (costa)
 
281
 
 
282
2004/10/26 Holger Wansing
 
283
 - Added a chapter about how to commit + fixed the Link to the svnbook.
 
284
 
 
285
2004/09/27 Frans Pop
 
286
 - Update in line with changes in SVN (moved files/directories)
 
287
 
 
288
2004/09/04 Guillem Jover
 
289
 - Refer to Adam Conrad's subversion backport instead.
 
290
 
 
291
2004/06/04 Frans Pop
 
292
 - Added paragraph on updating translations
 
293
 
 
294
2004/05/10 Frans Pop
 
295
 - file creation
 
296
 
 
297
2005/07/28 Cristian Rigamonti
 
298
 - Added cp-untrans, fixed svn command and some typos