Notes for translators ===================== This book and its translations are managed with Publican [1]. It also uses a custom publican brand available in the Debian package publican-debian. $ sudo apt-get install publican publican-debian [1] https://sourceware.org/publican/ Coordination mailing list ------------------------- Please subscribe to this mailing list: http://lists.alioth.debian.org/mailman/listinfo/debian-handbook-translators It will be relatively low-volume and will be used to send important information about the book updates to the current translators. Different translation workflows ------------------------------- There are two ways to manage the translations: - using the Weblate web application at https://hosted.weblate.org/projects/debian-handbook/ - using the Git repository to grab and commit PO files Translation with Weblate ------------------------ If you decide to use Weblate, you don't have to learn Git usage. Get in touch with us on the above mailing list so that we can setup the initial translation files for you, and once they appear on Weblate, you can start working! You should communicate us the ISO code of your translation (see "How to start a new translation" for more information on possible ISO codes). Note, however, that you can't translate pictures with Weblate, so someone must still commit those on the Git repository for you. If Git is too complicated for you, feel free to send the files to the mailing list and ask someone else to commit them for you. If you want to retrieve the content of Weblate via git you can use this git repository as remote: $ git remote add weblate https://hosted.weblate.org/git/debian-handbook/12_advanced-administration Translation without Weblate --------------------------- If you're not using Weblate, you'll have to interact with the Git repository. So read README.git first. Really. And then please respect the guidelines below. Please do not multiply commits uselessly. If you made several commits which only complete PO files, please squash them together before pushing (see man git-rebase for an explanation of how to squash commits together with interactive rebase). Write meaningful commit messages. Always start with the language code of the affected translations. Some examples of good commit messages: * it-IT: Add initial README file * es-ES: Complete translation of chapter 4 * zh-CN: Review of chapter 3 Take care to work on the most appropriate branch too. Currently it's "buster/master" since that's the stable maintenance branch for the current release of the book. If you already have downloaded the repository, use "git checkout buster/master" to change the current branch. Otherwise you can use one of the following commands to clone the repository and start on the correct branch: How to start a new translation ------------------------------ First, you must find out the ISO code of your translation (it looks like "pt-BR" or "fr-FR"). See here for the list supported by Publican: https://jfearn.fedorapeople.org/en-US/Publican/4.2/html/Users_Guide/appe-Publican-Users_Guide-Language_codes.html (I'll use "pt-BR" as example in the rest of this section) Then you need to tell publican who you are by creating a ~/.publican.cfg file (change the values with your own name and email): $ cat >~/.publican.cfg </dev/null Translating pictures and schemas -------------------------------- Some schemas contain texts that need to be translated. In those cases, you should copy the relevant .dia files from en-US/images/ into the images directory within your own translations directory (e.g. pt-BR/images/), update the dia file, and regenerate the corresponding PNG files (with the help of the "make foo.png" Makefile target). Some screenshots need to be remade to use a locale that matches your language. Do the screenshot and put them in the images directory of your translation (eg pt-BR/images/). Note: there's currently no automatic way to verify whether your translated schemas/pictures are up-to-date. Questions? ---------- Just ask on debian-handbook-translators@lists.alioth.debian.org.