/[d-i]/trunk/manual/doc/translations.txt
ViewVC logotype

Contents of /trunk/manual/doc/translations.txt

Parent Directory Parent Directory | Revision Log Revision Log


Revision 63046 - (show annotations) (download)
Sat May 1 09:32:29 2010 UTC (3 years, 11 months ago) by tale
File MIME type: text/plain
File size: 11815 byte(s)
Typo fixes
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 ./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 built. A text that has not been translated yet, will be
38 included in English.
39 - change directory to: ./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 in the original English documents.
48 see 'Keeping your translation up to date' below for an explanation.
49 - change directory to: ./manual/
50 - ./scripts/rev-update <lang>
51
52 3. Commit the changes to SVN
53 ----------------------------
54 - change directory to: ./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 building 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 looks 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 and 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: ./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 if 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. Just do
221 apt-get install subversion
222
223 2) Getting write access to the subversion repository
224 ----------------------------------------------------
225
226 If you are not a Debian Developer, you first need to create a guest account
227 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 Once your account is allowed to write to the project, you can retrieve the
234 full project using this:
235 svn co svn+ssh://<username>@svn.debian.org/svn/d-i/trunk
236 If you only want to work on the manual, you can retrieve the relevant part
237 of the repository using:
238 svn co svn+ssh://<username>@svn.debian.org/svn/d-i/trunk/manual
239
240 4) Commit your changed translation files to SVN
241 -----------------------------------------------
242
243 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 Note: it's possible to do an anonymous checkout from the svn
248 (use svn co svn://svn.debian.org/d-i/trunk/manual).
249 However, from this local copy you aren't able to commit, it's readonly.
250 Use the commands listed under 3) if you plan to do commits in the future.
251
252
253 You can find a good manual for SVN at http://svnbook.red-bean.com/.
254
255 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 2010-05-01 Tapio Lehtonen
271 - Typo fixes
272
273 2006-07-14 Frans Pop
274 - Correct and update information on subversion checkout
275
276 2005-10-07 Frans Pop
277 - Location of manual changed in the d-i SVN repository
278
279 2005-02-12 Frans Pop
280 - Minor corrections
281
282 2004-12-27 Frans Pop
283 - Updated svn checkout info to refer to new server (costa)
284
285 2004/10/26 Holger Wansing
286 - Added a chapter about how to commit + fixed the Link to the svnbook
287
288 2004/09/27 Frans Pop
289 - Update in line with changes in SVN (moved files/directories)
290
291 2004/09/04 Guillem Jover
292 - Refer to Adam Conrad's subversion backport instead
293
294 2004/06/04 Frans Pop
295 - Added paragraph on updating translations
296
297 2004/05/10 Frans Pop
298 - file creation
299
300 2005/07/28 Cristian Rigamonti
301 - Added cp-untrans, fixed svn command and some typos

  ViewVC Help
Powered by ViewVC 1.1.5