diff options
Diffstat (limited to 'doc/translations.txt')
| -rw-r--r-- | doc/translations.txt | 298 |
1 files changed, 298 insertions, 0 deletions
diff --git a/doc/translations.txt b/doc/translations.txt new file mode 100644 index 000000000..f6d32e862 --- /dev/null +++ b/doc/translations.txt @@ -0,0 +1,298 @@ +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 build. A text that has not be 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 is 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 build 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 è) 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 look 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, 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 is 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: + +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 |