Debian Installation Guide - notes for translation -------------------------------------------------- !!! Please note, that this file mostly documents xml-based !!! translations. But you can also translate this manual via po !!! files, if you want. This is documented in the file !!! translations_po.txt in this directory. !!! And: using the po format is strongly recommended, using the !!! xml format is deprecated! !!! Additional note: this file is outdated to some degree, because of the !!! migration of the repository from subversion to git! !!! Thus, some of the scripts mentioned below no longer work as expected! !!! Take this as one more encouragement on using po files (see !!! translations_po.txt). 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 git repository on salsa.debian.org as part of the Debian Installer (d-i) project. The manual and its translations can be found in ./installation-guide. 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 git repository really is not practical. See the section on getting GIT 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 built. A text that has not been translated yet, will be included in English. - change directory to: ./installation-guide/ - cp -R en/ (where is the ISO code for your language: xx or xx_XX) - find -name .git | xargs rm -Rf (this removes all .git subdirectories) 2. Convert revision comments ---------------------------- This enables you to track changes in the original English documents. see 'Keeping your translation up to date' below for an explanation. - change directory to: ./installation-guide/ - ./scripts/rev-update 3. Commit the changes to git ---------------------------- - change directory to: ./installation-guide/ - git add /* - git commit -m "installation-guide: creating new translation for " One more change is needed to get your translation building automatically: needs to be added to the 'languages' variable in build/build.sh. However, this is only useful 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 looks 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 and 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 'git status' before you start this procedure to check the status of your working copy. 1. Update your local working copy from GIT ------------------------------------------ - change directory to: ./manual/ - git pull 2. Copy new files (if any) -------------------------- If there are any new files (appearing with "create mode" in the output from 'git pull'), 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 'git 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 GIT; 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 if 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 git repository ============================================= 1) Installing git ------------------------ You need to install subversion on your system. Just do apt install git 2) Getting write access to the git repository ---------------------------------------------------- If you are not a Debian Developer, you first need to create a guest account on https://salsa.debian.org/, than ask on debian-boot@lists.debian.org for somebody to add your guest account to the debian-installer project. 3) Using git to get files -------------------------------- Once your account is allowed to write to the project, you can retrieve the installation-guide using this: git clone git@salsa.debian.org:installer-team/installation-guide.git 4) Commit your changed translation files to git ----------------------------------------------- After you have finished editing your translation, use git add path-to-file(s) git commit -m "Your comment about this commit" git push to commit your changes to the git repository. 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: 2018-06-03 Samuel Thibault - migrate to git 2010-05-01 Tapio Lehtonen - Typo fixes 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 2017/04/12 Holger Wansing - Add hint on translations_po.txt 2018/06/03 Holger Wansing - Updating (most) content on git migration