| 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://sourceware.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 |
https://hosted.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 |
If you want to retrieve the content of Weblate via git you can use |
| 42 |
this git repository as remote: |
| 43 |
$ git remote add weblate https://hosted.weblate.org/git/debian-handbook/12_advanced-administration |
| 44 |
|
| 45 |
Translation without Weblate |
| 46 |
--------------------------- |
| 47 |
|
| 48 |
If you're not using Weblate, you'll have to interact with the Git |
| 49 |
repository. So read README.git first. Really. And then please respect the |
| 50 |
guidelines below. |
| 51 |
|
| 52 |
Please do not multiply commits uselessly. If you made several commits |
| 53 |
which only complete PO files, please squash them together before pushing |
| 54 |
(see man git-rebase for an explanation of how to squash commits together |
| 55 |
with interactive rebase). |
| 56 |
|
| 57 |
Write meaningful commit messages. Always start with the language |
| 58 |
code of the affected translations. Some examples of good commit |
| 59 |
messages: |
| 60 |
* it-IT: Add initial README file |
| 61 |
* es-ES: Complete translation of chapter 4 |
| 62 |
* zh-CN: Review of chapter 3 |
| 63 |
|
| 64 |
Take care to work on the most appropriate branch too. Currently |
| 65 |
it's "buster/master" since that's the stable maintenance branch |
| 66 |
for the current release of the book. If you already have downloaded the |
| 67 |
repository, use "git checkout buster/master" to change the current |
| 68 |
branch. Otherwise you can use one of the following commands to clone the |
| 69 |
repository and start on the correct branch: |
| 70 |
|
| 71 |
How to start a new translation |
| 72 |
------------------------------ |
| 73 |
|
| 74 |
First, you must find out the ISO code of your translation (it looks like |
| 75 |
"pt-BR" or "fr-FR"). See here for the list supported by Publican: |
| 76 |
https://jfearn.fedorapeople.org/en-US/Publican/4.2/html/Users_Guide/appe-Publican-Users_Guide-Language_codes.html |
| 77 |
|
| 78 |
(I'll use "pt-BR" as example in the rest of this section) |
| 79 |
|
| 80 |
Then you need to tell publican who you are by creating a ~/.publican.cfg |
| 81 |
file (change the values with your own name and email): |
| 82 |
$ cat >~/.publican.cfg <<END |
| 83 |
firstname=Raphael |
| 84 |
surname=Hertzog |
| 85 |
[email protected] |
| 86 |
END |
| 87 |
|
| 88 |
Then if this Git repository doesn't have any directory of this name, |
| 89 |
you need to create the initial translation files: |
| 90 |
$ publican update_po --langs=pt-BR |
| 91 |
|
| 92 |
Now you have lots of PO files in pt-BR/*.po that you can translate. |
| 93 |
You should probably commit the empty PO files before going further. |
| 94 |
|
| 95 |
$ git add pt-BR/*.po |
| 96 |
$ git commit -m "pt-BR: Start new translation" |
| 97 |
|
| 98 |
Then add a pt-BR/README file where you put: |
| 99 |
- the name and email of the (current) translation coordinator |
| 100 |
- the name and email of the volunteers who contributed to the |
| 101 |
translation |
| 102 |
- explanations (for new contributors) about the workflow that you use to |
| 103 |
coordinate the work |
| 104 |
- translation choices that you made about the style to use, the |
| 105 |
vocabulary, etc. |
| 106 |
|
| 107 |
$ vim pt-BR/README |
| 108 |
$ git add pt-BR/README |
| 109 |
$ git commit -m "pt-BR: Add initial README file" |
| 110 |
|
| 111 |
You can certainly write that README file in your native language if you |
| 112 |
want, but it's highly recommended to also have an English translation of |
| 113 |
the instructions so that everybody else can see how a given team is |
| 114 |
organized. |
| 115 |
|
| 116 |
Translating PO files |
| 117 |
-------------------- |
| 118 |
|
| 119 |
You're free to use the tool of your choice to complete the PO files. Once |
| 120 |
you have done enough, you can commit your updated PO files: |
| 121 |
$ git add pt-BR/*.po |
| 122 |
$ git commit -m "pt-BR: Updated translation" |
| 123 |
|
| 124 |
Depending on the workflow used by your translation team, you can either |
| 125 |
push your work directly or make it available to your translation |
| 126 |
coordinator that will integrate it for you. |
| 127 |
|
| 128 |
If you use a plain text editor, please double check that you haven't |
| 129 |
broken the PO files. Here is an example checking |
| 130 |
pt-BR/01_the-debian-project.po where some issues are detected: |
| 131 |
|
| 132 |
$ msgfmt -c -o /dev/null --statistics pt-BR/01_the-debian-project.po |
| 133 |
pt-BR/01_the-debian-project.po:1432: 'msgid' and 'msgstr' entries do not both end with '\n' |
| 134 |
msgfmt: found 1 fatal error |
| 135 |
348 translated messages, 100 fuzzy translations, 9 untranslated messages. |
| 136 |
$ msgcat pt-BR/01_the-debian-project.po >/dev/null |
| 137 |
|
| 138 |
Translating pictures and schemas |
| 139 |
-------------------------------- |
| 140 |
|
| 141 |
Some schemas contain texts that need to be translated. In those cases, |
| 142 |
you should copy the relevant .dia files from en-US/images/ into the images |
| 143 |
directory within your own translations directory (e.g. pt-BR/images/), |
| 144 |
update the dia file, and regenerate the corresponding PNG files (with the |
| 145 |
help of the "make foo.png" Makefile target). |
| 146 |
|
| 147 |
Some screenshots need to be remade to use a locale that matches your |
| 148 |
language. Do the screenshot and put them in the images directory of |
| 149 |
your translation (eg pt-BR/images/). |
| 150 |
|
| 151 |
Note: there's currently no automatic way to verify whether your translated |
| 152 |
schemas/pictures are up-to-date. |
| 153 |
|
| 154 |
Questions? |
| 155 |
---------- |
| 156 |
|
| 157 |
Just ask on [email protected]. |