README.translators

   1 Notes for translators
   2 =====================
   3
   4 This book and its translations are managed with Publican [1]. It also uses
   5 a custom publican brand available in the Debian package publican-debian.
   6
   7 $ sudo apt-get install publican publican-debian
   8
   9 [1] https://fedorahosted.org/publican/
  10
  11 Coordination mailing list
  12 -------------------------
  13 Please subscribe to this mailing list:
  14 http://lists.alioth.debian.org/mailman/listinfo/debian-handbook-translators
  15
  16 It will be relatively low-volume and will be used to send important
  17 information about the book updates to the current translators.
  18
  19 Different translation workflows
  20 -------------------------------
  21 There are two ways to manage the translations:
  22 - using the weblate web application at
  23   http://debian.weblate.org/projects/debian-handbook/
  24 - using the Git repository to grab and commit PO files
  25
  26 Translation with weblate
  27 ------------------------
  28
  29 If you decide to use weblate, you don't have to learn Git usage.
  30 Get in touch with us on the above mailing list so that we can setup
  31 the initial translation files for you, and once they appear
  32 on weblate, you can start working! You should communicate us
  33 the ISO code of your translation (see "How to start a new translation" for
  34 more information on possible ISO codes).
  35
  36 Note however that you can't translate pictures with weblate so someone
  37 must still commit those on the Git repository for you. If Git is too
  38 complicated for you, feel free to send the files to the mailing list and
  39 ask someone else to commit them for you.
  40
  41 Translation without weblate
  42 ---------------------------
  43
  44 If you're not using weblate, you'll have to interact with the Git
  45 repository. So read README.git first. Really. And then please respect the
  46 guidelines below.
  47
  48 Please do not multiply commits uselessly. If you made several commits
  49 which only complete PO files, please squash them together before pushing
  50 (see man git-rebase for an explanation of how to squash commits together
  51 with interactive rebase).
  52
  53 Write meaningful commit messages. Always start with the language
  54 code of the affected translations. Some examples of good commit
  55 messages:
  56 * it-IT: Add initial README file
  57 * es-ES: Complete translation of chapter 4
  58 * zh-CN: Review of chapter 3
  59
  60 Take care to work on the most appropriate branch too. Currently
  61 it's "squeeze/master" since that's the stable maintenance branch
  62 for the current release of the book. If you already have downloaded the
  63 repository, use "git checkout squeeze/master" to change the current
  64 branch. Otherwise you can use one of those commands to clone the
  65 repository and start on the correct branch:
  66
  67 Read-only anonymous access:
  68 $ git clone git://anonscm.debian.org/debian-handbook/debian-handbook.git -b squeeze/master
  69 SSH access for contributors with Write access:
  70 $ git clone git+ssh://git.debian.org/git/debian-handbook/debian-handbook.git -b squeeze/master
  71
  72 How to start a new translation
  73 ------------------------------
  74
  75 First you must find out the ISO code of your translation (it looks like
  76 "pt-BR" or "fr-FR"). See here for the list supported by Publican:
  77 http://jfearn.fedorapeople.org/en-US/Publican/2.7/html/Users_Guide/appe-Users_Guide-Language_codes.html
  78
  79 (I'll use "pt-BR" as example in the rest of this section)
  80
  81 Then if this Git repository doesn't have any directory of this name,
  82 you need to create the initial translation files:
  83 $ publican update_po --langs=pt-BR
  84
  85 Now you have lots of PO files in pt-BR/*.po that you can translate.
  86 You should probably commit the empty PO files before going further.
  87
  88 $ git add pt-BR/*.po
  89 $ git commit -m "pt-BR: Start new translation"
  90
  91 Then add a pt-BR/README file where you put:
  92 - the name and email of the (current) translation coordinator
  93 - the name and email of the volunteers who contributed to the
  94   translation
  95 - explanations (for new contributors) about the workflow that you use to
  96   coordinate the work
  97 - translation choices that you made about the style to use, the
  98   vocabulary, etc.
  99
 100 $ vim pt-BR/README
 101 $ git add pt-BR/README
 102 $ git commit -m "pt-BR: Add initial README file"
 103
 104 You can certainly write that README file in your native language if you
 105 want but it's highly recommended to also have an English translation of
 106 the instructions so that everybody else can see how a given team is
 107 organized.
 108
 109 Translating PO files
 110 --------------------
 111
 112 You're free to use the tool of your choice to complete the PO files. Once
 113 you have done enough, you can commit your updated PO files:
 114 $ git add pt-BR/*.po
 115 $ git commit -m "pt-BR: Updated translation"
 116
 117 Depending on the workflow used by your translation team, you can either
 118 push your work directly or make it available to your translation
 119 coordinator that will integrate it for you.
 120
 121 Translating pictures and schemas
 122 --------------------------------
 123
 124 Some schemas contain texts that need to be translated. In those case,
 125 you should copy the relevant .dia files from en-US/images/ into the images
 126 directory within your own translations directory (eg. pt-BR/images/),
 127 update the dia file, and regenerate the corresponding PNG files (with the
 128 help of the "make foo.png" Makefile target).
 129
 130 Some screenshots need to be remade to use a locale that matches your
 131 language. Do the screenshot and put them in the images directory of
 132 your translation (eg pt-BR/images/).
 133
 134 Note: there's currently no automatic way to verify whether your translated
 135 schemas/pictures are up-to-date.
 136
 137 Questions?
 138 ----------
 139
 140 Just ask on debian-handbook-translators@lists.alioth.debian.org.