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-@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/ (where is the ISO code for your language: xx or xx_XX) - find -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 3. Commit the changes to SVN ---------------------------- - change directory to: ./manual/ - svn add - svn ci -m "Manual: creating new translation for " One more change is needed to get your translation build automatically: 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: 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: 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: or 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 This will change the revision comment in the copied file to: You will also have to run 'svn add' for the new documents. 3. Check for other changes -------------------------- - ./scripts/doc-check 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 (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 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 ' 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 : show which documents are marked untranslated - rev-update -u : 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-@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://@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://@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