]>
Commit | Line | Data |
---|---|---|
2631a81b JH |
1 | Localizing git-gui for your language |
2 | ==================================== | |
3 | ||
4 | This short note is to help you, who reads and writes English and your | |
5 | own language, help us getting git-gui localized for more languages. It | |
6 | does not try to be a comprehensive manual of GNU gettext, which is the | |
7 | i18n framework we use, but tries to help you get started by covering the | |
8 | basics and how it is used in this project. | |
9 | ||
10 | 1. Getting started. | |
11 | ||
12 | You would first need to have a working "git". Your distribution may | |
13 | have it as "git-core" package (do not get "GNU Interactive Tools" -- | |
14 | that is a different "git"). You would also need GNU gettext toolchain | |
15 | to test the resulting translation out. Although you can work on message | |
16 | translation files with a regular text editor, it is a good idea to have | |
17 | specialized so-called "po file editors" (e.g. emacs po-mode, KBabel, | |
18 | poedit, GTranslator --- any of them would work well). Please install | |
19 | them. | |
20 | ||
8c0bf683 PT |
21 | You would then need to clone the git-gui project repository and create |
22 | a feature branch to begin working: | |
2631a81b | 23 | |
8c0bf683 PT |
24 | $ git clone git://repo.or.cz/git-gui.git |
25 | $ cd git-gui.git | |
26 | $ git checkout -b my-translation | |
2631a81b | 27 | |
8c0bf683 PT |
28 | The "git checkout" command creates a new branch to keep your work |
29 | isolated and to make it simple to post your patch series when | |
30 | completed. You will be working on this branch. | |
2631a81b JH |
31 | |
32 | ||
33 | 2. Starting a new language. | |
34 | ||
8c0bf683 PT |
35 | In the git-gui directory is a po/ subdirectory. It has a handful of |
36 | files whose names end with ".po". Is there a file that has messages | |
37 | in your language? | |
2631a81b JH |
38 | |
39 | If you do not know what your language should be named, you need to find | |
40 | it. This currently follows ISO 639-1 two letter codes: | |
41 | ||
42 | http://www.loc.gov/standards/iso639-2/php/code_list.php | |
43 | ||
44 | For example, if you are preparing a translation for Afrikaans, the | |
45 | language code is "af". If there already is a translation for your | |
46 | language, you do not have to perform any step in this section, but keep | |
47 | reading, because we are covering the basics. | |
48 | ||
49 | If you did not find your language, you would need to start one yourself. | |
50 | Copy po/git-gui.pot file to po/af.po (replace "af" with the code for | |
51 | your language). Edit the first several lines to match existing *.po | |
52 | files to make it clear this is a translation table for git-gui project, | |
53 | and you are the primary translator. The result of your editing would | |
54 | look something like this: | |
55 | ||
56 | # Translation of git-gui to Afrikaans | |
57 | # Copyright (C) 2007 Shawn Pearce | |
58 | # This file is distributed under the same license as the git-gui package. | |
59 | # YOUR NAME <YOUR@E-MAIL.ADDRESS>, 2007. | |
60 | # | |
61 | #, fuzzy | |
62 | msgid "" | |
63 | msgstr "" | |
64 | "Project-Id-Version: git-gui\n" | |
65 | "Report-Msgid-Bugs-To: \n" | |
66 | "POT-Creation-Date: 2007-07-24 22:19+0300\n" | |
67 | "PO-Revision-Date: 2007-07-25 18:00+0900\n" | |
68 | "Last-Translator: YOUR NAME <YOUR@E-MAIL.ADDRESS>\n" | |
69 | "Language-Team: Afrikaans\n" | |
70 | "MIME-Version: 1.0\n" | |
71 | "Content-Type: text/plain; charset=UTF-8\n" | |
72 | "Content-Transfer-Encoding: 8bit\n" | |
73 | ||
74 | You will find many pairs of a "msgid" line followed by a "msgstr" line. | |
75 | These pairs define how messages in git-gui application are translated to | |
76 | your language. Your primarily job is to fill in the empty double quote | |
77 | pairs on msgstr lines with the translation of the strings on their | |
78 | matching msgid lines. A few tips: | |
79 | ||
80 | - Control characters, such as newlines, are written in backslash | |
81 | sequence similar to string literals in the C programming language. | |
82 | When the string given on a msgid line has such a backslash sequence, | |
83 | you would typically want to have corresponding ones in the string on | |
84 | your msgstr line. | |
85 | ||
262360f3 SP |
86 | - Some messages contain an optional context indicator at the end, |
87 | for example "@@noun" or "@@verb". This indicator allows the | |
88 | software to select the correct translation depending upon the use. | |
89 | The indicator is not actually part of the message and will not | |
90 | be shown to the end-user. | |
91 | ||
92 | If your language does not require a different translation you | |
93 | will still need to translate both messages. | |
94 | ||
2631a81b JH |
95 | - Often the messages being translated are format strings given to |
96 | "printf()"-like functions. Make sure "%s", "%d", and "%%" in your | |
97 | translated messages match the original. | |
98 | ||
fbbdaa5f | 99 | When you have to change the order of words, you can add "<number>$" |
2631a81b JH |
100 | between '%' and the conversion ('s', 'd', etc.) to say "<number>-th |
101 | parameter to the format string is used at this point". For example, | |
102 | if the original message is like this: | |
103 | ||
104 | "Length is %d, Weight is %d" | |
105 | ||
106 | and if for whatever reason your translation needs to say weight first | |
107 | and then length, you can say something like: | |
108 | ||
fbbdaa5f | 109 | "WEIGHT IS %2$d, LENGTH IS %1$d" |
2631a81b | 110 | |
fbbdaa5f MB |
111 | A format specification with a '*' (asterisk) refers to *two* arguments |
112 | instead of one, hence the succeeding argument number is two higher | |
113 | instead of one. So, a message like this | |
114 | ||
115 | "%s ... %*i of %*i %s (%3i%%)" | |
116 | ||
117 | is equivalent to | |
118 | ||
119 | "%1$s ... %2$*i of %4$*i %6$s (%7$3i%%)" | |
2631a81b JH |
120 | |
121 | - A long message can be split across multiple lines by ending the | |
122 | string with a double quote, and starting another string on the next | |
123 | line with another double quote. They will be concatenated in the | |
124 | result. For example: | |
125 | ||
126 | #: lib/remote_branch_delete.tcl:189 | |
127 | #, tcl-format | |
128 | msgid "" | |
129 | "One or more of the merge tests failed because you have not fetched the " | |
130 | "necessary commits. Try fetching from %s first." | |
131 | msgstr "" | |
132 | "HERE YOU WILL WRITE YOUR TRANSLATION OF THE ABOVE LONG " | |
133 | "MESSAGE IN YOUR LANGUAGE." | |
134 | ||
135 | You can test your translation by running "make install", which would | |
136 | create po/af.msg file and installs the result, and then running the | |
137 | resulting git-gui under your locale: | |
138 | ||
139 | $ make install | |
140 | $ LANG=af git-gui | |
141 | ||
2ea22555 | 142 | There is a trick to test your translation without first installing: |
2631a81b JH |
143 | |
144 | $ make | |
145 | $ LANG=af ./git-gui.sh | |
146 | ||
8c0bf683 PT |
147 | When you are satisfied with your translation, commit your changes then submit |
148 | your patch series to the maintainer and the Git mailing list: | |
2631a81b JH |
149 | |
150 | $ edit po/af.po | |
151 | ... be sure to update Last-Translator: and | |
152 | ... PO-Revision-Date: lines. | |
153 | $ git add po/af.po | |
8c0bf683 PT |
154 | $ git commit -s -m 'git-gui: added Afrikaans translation.' |
155 | $ git send-email --to 'git@vger.kernel.org' \ | |
156 | --cc 'Pat Thoyts <patthoyts@users.sourceforge.net>' \ | |
157 | --subject 'git-gui: Afrikaans translation' \ | |
158 | master.. | |
2631a81b JH |
159 | |
160 | ||
161 | 3. Updating your translation. | |
162 | ||
163 | There may already be a translation for your language, and you may want | |
164 | to contribute an update. This may be because you would want to improve | |
165 | the translation of existing messages, or because the git-gui software | |
166 | itself was updated and there are new messages that need translation. | |
167 | ||
7560f547 | 168 | In any case, make sure you are up to date before starting your work: |
2631a81b | 169 | |
8c0bf683 | 170 | $ git checkout master |
2631a81b JH |
171 | $ git pull |
172 | ||
173 | In the former case, you will edit po/af.po (again, replace "af" with | |
174 | your language code), and after testing and updating the Last-Translator: | |
175 | and PO-Revision-Date: lines, "add/commit/push" as in the previous | |
176 | section. | |
177 | ||
178 | By comparing "POT-Creation-Date:" line in po/git-gui.pot file and | |
179 | po/af.po file, you can tell if there are new messages that need to be | |
180 | translated. You would need the GNU gettext package to perform this | |
181 | step. | |
182 | ||
183 | $ msgmerge -U po/af.po po/git-gui.pot | |
184 | ||
2631a81b JH |
185 | This updates po/af.po (again, replace "af" with your language |
186 | code) so that it contains msgid lines (i.e. the original) that | |
187 | your translation did not have before. There are a few things to | |
188 | watch out for: | |
189 | ||
190 | - The original text in English of an older message you already | |
191 | translated might have been changed. You will notice a comment line | |
192 | that begins with "#, fuzzy" in front of such a message. msgmerge | |
193 | tool made its best effort to match your old translation with the | |
194 | message from the updated software, but you may find cases that it | |
195 | matched your old translated message to a new msgid and the pairing | |
196 | does not make any sense -- you would need to fix them, and then | |
197 | remove the "#, fuzzy" line from the message (your fixed translation | |
198 | of the message will not be used before you remove the marker). | |
199 | ||
200 | - New messages added to the software will have msgstr lines with empty | |
201 | strings. You would need to translate them. | |
739a6d49 JH |
202 | |
203 | The po/git-gui.pot file is updated by the internationalization | |
204 | coordinator from time to time. You _could_ update it yourself, but | |
205 | translators are discouraged from doing so because we would want all | |
206 | language teams to be working off of the same version of git-gui.pot. | |
207 | ||
208 | **************************************************************** | |
209 | ||
210 | This section is a note to the internationalization coordinator, and | |
211 | translators do not have to worry about it too much. | |
212 | ||
213 | The message template file po/git-gui.pot needs to be kept up to date | |
214 | relative to the software the translations apply to, and it is the | |
215 | responsibility of the internationalization coordinator. | |
216 | ||
217 | When updating po/git-gui.pot file, however, _never_ run "msgmerge -U | |
218 | po/xx.po" for individual language translations, unless you are absolutely | |
219 | sure that there is no outstanding work on translation for language xx. | |
220 | Doing so will create unnecessary merge conflicts and force needless | |
221 | re-translation on translators. The translator however may not have access | |
222 | to the msgmerge tool, in which case the coordinator may run it for the | |
223 | translator as a service. | |
224 | ||
225 | But mistakes do happen. Suppose a translation was based on an older | |
226 | version X, the POT file was updated at version Y and then msgmerge was run | |
227 | at version Z for the language, and the translator sent in a patch based on | |
228 | version X: | |
229 | ||
230 | ? translated | |
231 | / | |
232 | ---X---Y---Z (master) | |
233 | ||
234 | The coordinator could recover from such a mistake by first applying the | |
235 | patch to X, replace the translated file in Z, and then running msgmerge | |
236 | again based on the updated POT file and commit the result. The sequence | |
237 | would look like this: | |
238 | ||
239 | $ git checkout X | |
240 | $ git am -s xx.patch | |
241 | $ git checkout master | |
242 | $ git checkout HEAD@{1} po/xx.po | |
243 | $ msgmerge -U po/xx.po po/git-gui.pot | |
244 | $ git commit -c HEAD@{1} po/xx.po | |
245 | ||
246 | State in the message that the translated messages are based on a slightly | |
247 | older version, and msgmerge was run to incorporate changes to message | |
248 | templates from the updated POT file. The result needs to be further | |
249 | translated, but at least the messages that were updated by the patch that | |
250 | were not changed by the POT update will survive the process and do not | |
251 | need to be re-translated. |