| 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 alioth.debian.org
|
| 11 |
as part of the Debian Installer (d-i) project.
|
| 12 |
|
| 13 |
The manual and it's 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 realy 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. Create the install.<lang.xml file
|
| 46 |
------------------------------------
|
| 47 |
This file contains the basic information used to build the manual.
|
| 48 |
- change directory to: installer/doc/manual/build/
|
| 49 |
- cp install.en.xml install.<lang>.xml
|
| 50 |
- edit this new file changing the line '<book>' to '<book lang="<lang>">'
|
| 51 |
(again replacing <lang> by the ISO code for your language)
|
| 52 |
|
| 53 |
3. Convert revision comments
|
| 54 |
----------------------------
|
| 55 |
This enables you to track changes is the original English documents.
|
| 56 |
see 'Keeping your translation up to date' below for an explanation.
|
| 57 |
- change directory to: installer/doc/manual/
|
| 58 |
- ./rev-update <lang>
|
| 59 |
|
| 60 |
4. Commit the changes to SVN
|
| 61 |
----------------------------
|
| 62 |
- change directory to: installer/doc/manual/
|
| 63 |
- svn add <lang>
|
| 64 |
- svn add build/install.<lang>.xml
|
| 65 |
- svn ci -m "Manual: creating new translation for <lang>"
|
| 66 |
|
| 67 |
One more change is needed to get your translation build automatically:
|
| 68 |
<lang> needs to be added to the 'languages' variable in build/build.sh.
|
| 69 |
However, this is only usefull after you have translated your first couple
|
| 70 |
of chapters. Please send a request to the debian-boot mail list for your
|
| 71 |
language to be added.
|
| 72 |
|
| 73 |
Encoding
|
| 74 |
========
|
| 75 |
|
| 76 |
The default encoding for all .xml files is UTF-8. If you want to keep your
|
| 77 |
translation in UTF-8 encoding, you should use an editor that supports UTF-8
|
| 78 |
and make sure that UTF-8 encoding is selected when you open a .xml document.
|
| 79 |
|
| 80 |
If it is easier for you to work using another encoding, you will have to
|
| 81 |
specify which encoding you use in the first line of each translated document.
|
| 82 |
For example, to use ISO-8859-1 encoding (for most Western European languages),
|
| 83 |
add the following line at the top of each .xml file:
|
| 84 |
<?xml version="1.0" encoding="ISO-8859-1"?>
|
| 85 |
|
| 86 |
The use of HTML codes (like è) is possible but not advised.
|
| 87 |
|
| 88 |
Note: If you do not specify the correct encoding, your translation will fail
|
| 89 |
to build.
|
| 90 |
Note: You should _not_ change the encoding of the following documents:
|
| 91 |
- administrativa/contributors.xml
|
| 92 |
|
| 93 |
Translation order
|
| 94 |
=================
|
| 95 |
|
| 96 |
Suggested translation order:
|
| 97 |
- ./preface.xml
|
| 98 |
- ./welcome/*.xml
|
| 99 |
- ./using-d-i/*.xml
|
| 100 |
- ./boot-new/*.xml
|
| 101 |
- ./boot-new/modules/*.xml
|
| 102 |
- ./module/*.xml
|
| 103 |
|
| 104 |
Note that currently (may 10, 2004) it look like there will be a fairly major
|
| 105 |
reorganization of parts of the manual in the next month(s).
|
| 106 |
|
| 107 |
Keeping your translation up to date
|
| 108 |
===================================
|
| 109 |
|
| 110 |
There are two perl scripts to help you keep track of changes in the original
|
| 111 |
English text of the manual. These scripts make use of special revision
|
| 112 |
comments that should be included in each file.
|
| 113 |
|
| 114 |
An original English file contains something like:
|
| 115 |
<!-- retain these comments for translator revision tracking -->
|
| 116 |
<!-- $Id: preface.xml 12756 2004-04-06 22:23:56Z some-user $ -->
|
| 117 |
|
| 118 |
The second line is important. It contains the filename, the revision number,
|
| 119 |
the date and time the last revision was committed, the user that committed
|
| 120 |
the last revision. The string '$Id:' is necessary for SVN to automatically
|
| 121 |
update this line each time the file is committed.
|
| 122 |
|
| 123 |
A document in a directory containing a translation should contain either:
|
| 124 |
<!-- original version: 12756 -->
|
| 125 |
or
|
| 126 |
<!-- original version: 12756 untranslated -->
|
| 127 |
|
| 128 |
When you translate a document, you should of course remove the word
|
| 129 |
'untranslated' from this comment.
|
| 130 |
|
| 131 |
The scripts will do several things:
|
| 132 |
- show which translated files have a different revision number from the
|
| 133 |
original English files
|
| 134 |
- show what changes have been made in the original English file
|
| 135 |
- help you update revision comments
|
| 136 |
- help you keep track of which files have not yet been translated
|
| 137 |
You can find both scripts in the root directory for the manual. Both
|
| 138 |
scripts should be run from this directory.
|
| 139 |
|
| 140 |
The procedure below can be used for relatively simple changes. If there
|
| 141 |
have been major reorganizations in the English documents, you may have to
|
| 142 |
do additional checks to find out exactly what changes have been made.
|
| 143 |
Use 'svn st -u' before you start this procedure to check the status of
|
| 144 |
your working copy.
|
| 145 |
|
| 146 |
1. Update your local working copy from SVN
|
| 147 |
------------------------------------------
|
| 148 |
- change directory to: installer/doc/manual/
|
| 149 |
- svn up
|
| 150 |
|
| 151 |
2. Copy new files (if any)
|
| 152 |
--------------------------
|
| 153 |
If there are any new files (marked 'A' in the output from 'svn up'),
|
| 154 |
copy them to the directory for your translation and then:
|
| 155 |
- ./rev-update <lang>
|
| 156 |
This will change the revision comment in the copied file to:
|
| 157 |
<!-- original version: ##### untranslated -->
|
| 158 |
You will also have to run 'svn add' for the new documents.
|
| 159 |
|
| 160 |
3. Check for other changes
|
| 161 |
--------------------------
|
| 162 |
- ./doc-check <lang>
|
| 163 |
If changes are listed for documents that are marked 'untranslated', you
|
| 164 |
can just copy the new English version to the directory for your translation
|
| 165 |
and again use rev-update to change the revision comments.
|
| 166 |
If changes are listed for documents that are not marked 'untranslated',
|
| 167 |
you can create a diff to find out what the changes are by running:
|
| 168 |
- ./doc-check -d <lang>
|
| 169 |
|
| 170 |
4. Update your translations
|
| 171 |
---------------------------
|
| 172 |
Edit your translations to reflect the changes in the English documents.
|
| 173 |
!! Don't forget to also update the revision number in the revision comment
|
| 174 |
after you updated a translation. The revision number should be the same
|
| 175 |
as the revision number in the new version of the English document.
|
| 176 |
You should run './doc-check <lang>' again after you finish all updates and
|
| 177 |
before you commit your changes to SVN; there should be no output.
|
| 178 |
|
| 179 |
Other uses of the scripts
|
| 180 |
-------------------------
|
| 181 |
- doc-check -s <lang>: show which documents are marked untranslated
|
| 182 |
- rev-update -u <lang>: automatically update revision numbers in the directory
|
| 183 |
containing your translation to the revision numbers in the original English
|
| 184 |
documents (use only after you have made sure there are no changes in content)
|
| 185 |
|
| 186 |
How to remain consistent with the installer
|
| 187 |
===========================================
|
| 188 |
|
| 189 |
It is important that your translation of the manual remains consistent with
|
| 190 |
the translation of Debian Installer and packages for your languages.
|
| 191 |
|
| 192 |
Probably the best way to do this, is to run the installer in 'expert' mode,
|
| 193 |
both in English and your own language.
|
| 194 |
|
| 195 |
As strings and their translations in the installer may change, you may have
|
| 196 |
to perform an installation once in a while to check if there have been
|
| 197 |
important changes (the main burden to check for changes in strings falls on
|
| 198 |
the maintainers of the English original, but is you spot inconsistencies,
|
| 199 |
please report them to the debian-boot list).
|
| 200 |
|
| 201 |
You can also use the xx(_XX).po files for packages (including d-i) to see
|
| 202 |
how strings have been translated. For more information on these files,
|
| 203 |
please refer to the translations.txt file in the parent directory of the
|
| 204 |
directory where this file is.
|
| 205 |
|
| 206 |
You can also try contacting the translator for a package or the maillist
|
| 207 |
for your language (debian-l10n-<language>@lists.debian.org) to try to clear
|
| 208 |
questions about translations.
|
| 209 |
|
| 210 |
How to test your work
|
| 211 |
=====================
|
| 212 |
|
| 213 |
When you have finished your translation, always re-read your file at
|
| 214 |
least once to correct all meaning-, spelling-, grammar-, typo-, etc-
|
| 215 |
mistakes.
|
| 216 |
|
| 217 |
You can also try to build the manual (create HTML pages) for a specific
|
| 218 |
architecture for your language.
|
| 219 |
See ./build/README for more information on building the manual.
|
| 220 |
|
| 221 |
How to get write access to the SVN repository
|
| 222 |
=============================================
|
| 223 |
|
| 224 |
1) Installing subversion
|
| 225 |
------------------------
|
| 226 |
|
| 227 |
You need to install subversion on your system. For Debian unstable users,
|
| 228 |
just do "apt-get install svn".
|
| 229 |
|
| 230 |
Others may use backports from www.backports.org. Please add this entry to
|
| 231 |
your /etc/apt/sources.list file:
|
| 232 |
deb http://www.backports.org/debian stable subversion
|
| 233 |
Or use Adam Conrad's backports:
|
| 234 |
deb http://people.debian.org/~adconrad woody subversion
|
| 235 |
|
| 236 |
2) Getting write access to the subversion repository
|
| 237 |
----------------------------------------------------
|
| 238 |
|
| 239 |
If you are not a Debian Developper, you first need to create a guest account
|
| 240 |
on http://alioth.debian.org/, than ask on debian-boot@lists.debian.org
|
| 241 |
for somebody to add your guest account to the debian-installer project.
|
| 242 |
|
| 243 |
3) Using subversion to get files
|
| 244 |
--------------------------------
|
| 245 |
|
| 246 |
Once your account is allowed to write to the project, you can retreive the
|
| 247 |
full project using this:
|
| 248 |
svn co svn+ssh://<username>@svn.debian.org/svn/d-i/trunk debian-installer
|
| 249 |
If you only want to work on the manual, you can retrieve the relevant part
|
| 250 |
of the repository using:
|
| 251 |
svn co svn+ssh://<username>@svn.debian.org/svn/d-i/trunk debian-installer/installer/doc
|
| 252 |
|
| 253 |
You can find a good manual for SVN at http://svnbook.red-bean.com/svnbook.
|
| 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 |
2004/09/04 Guillem Jover
|
| 271 |
- Refer to Adam Conrad's subversion backport instead.
|
| 272 |
|
| 273 |
2004/06/04 Frans Pop
|
| 274 |
- Added paragraph on updating translations
|
| 275 |
|
| 276 |
2004/05/10 Frans Pop
|
| 277 |
- file creation
|
Parent Directory
| 
Revision Log