Debian Codegraph @

README.translators

raw
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].