git-gui: Improve directions regarding POT update in po/README
[git/git.git] / po / README
1 Localizing git-gui for your language
2 ====================================
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.
10 1. Getting started.
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.
21 You would then need to clone the git-gui internationalization project
22 repository, so that you can work on it:
24 $ git clone
25 $ cd git-gui-i18n
26 $ git checkout --track -b mob origin/mob
27 $ git config remote.origin.push mob
29 The "git checkout" command creates a 'mob' branch from upstream's
30 corresponding branch and makes it your current branch. You will be
31 working on this branch.
33 The "git config" command records in your repository configuration file
34 that you would push "mob" branch to the upstream when you say "git
35 push".
38 2. Starting a new language.
40 In the git-gui-i18n directory is a po/ subdirectory. It has a
41 handful files whose names end with ".po". Is there a file that has
42 messages in your language?
44 If you do not know what your language should be named, you need to find
45 it. This currently follows ISO 639-1 two letter codes:
49 For example, if you are preparing a translation for Afrikaans, the
50 language code is "af". If there already is a translation for your
51 language, you do not have to perform any step in this section, but keep
52 reading, because we are covering the basics.
54 If you did not find your language, you would need to start one yourself.
55 Copy po/git-gui.pot file to po/af.po (replace "af" with the code for
56 your language). Edit the first several lines to match existing *.po
57 files to make it clear this is a translation table for git-gui project,
58 and you are the primary translator. The result of your editing would
59 look something like this:
61 # Translation of git-gui to Afrikaans
62 # Copyright (C) 2007 Shawn Pearce
63 # This file is distributed under the same license as the git-gui package.
65 #
66 #, fuzzy
67 msgid ""
68 msgstr ""
69 "Project-Id-Version: git-gui\n"
70 "Report-Msgid-Bugs-To: \n"
71 "POT-Creation-Date: 2007-07-24 22:19+0300\n"
72 "PO-Revision-Date: 2007-07-25 18:00+0900\n"
73 "Last-Translator: YOUR NAME <YOUR@E-MAIL.ADDRESS>\n"
74 "Language-Team: Afrikaans\n"
75 "MIME-Version: 1.0\n"
76 "Content-Type: text/plain; charset=UTF-8\n"
77 "Content-Transfer-Encoding: 8bit\n"
79 You will find many pairs of a "msgid" line followed by a "msgstr" line.
80 These pairs define how messages in git-gui application are translated to
81 your language. Your primarily job is to fill in the empty double quote
82 pairs on msgstr lines with the translation of the strings on their
83 matching msgid lines. A few tips:
85 - Control characters, such as newlines, are written in backslash
86 sequence similar to string literals in the C programming language.
87 When the string given on a msgid line has such a backslash sequence,
88 you would typically want to have corresponding ones in the string on
89 your msgstr line.
91 - Some messages contain an optional context indicator at the end,
92 for example "@@noun" or "@@verb". This indicator allows the
93 software to select the correct translation depending upon the use.
94 The indicator is not actually part of the message and will not
95 be shown to the end-user.
97 If your language does not require a different translation you
98 will still need to translate both messages.
100 - Often the messages being translated are format strings given to
101 "printf()"-like functions. Make sure "%s", "%d", and "%%" in your
102 translated messages match the original.
104 When you have to change the order of words, you can add "<number>\$"
105 between '%' and the conversion ('s', 'd', etc.) to say "<number>-th
106 parameter to the format string is used at this point". For example,
107 if the original message is like this:
109 "Length is %d, Weight is %d"
111 and if for whatever reason your translation needs to say weight first
112 and then length, you can say something like:
114 "WEIGHT IS %2\$d, LENGTH IS %1\$d"
116 The reason you need a backslash before dollar sign is because
117 this is a double quoted string in Tcl language, and without
118 it the letter introduces a variable interpolation, which you
119 do not want here.
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:
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 ""
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:
139 $ make install
140 $ LANG=af git-gui
142 There is a trick to test your translation without first installing:
144 $ make
145 $ LANG=af ./
147 When you are satisfied with your translation, commit your changes, and
148 push it back to the 'mob' branch:
150 $ edit po/af.po
151 ... be sure to update Last-Translator: and
152 ... PO-Revision-Date: lines.
153 $ git add po/af.po
154 $ git commit -m 'Started Afrikaans translation.'
155 $ git push
158 3. Updating your translation.
160 There may already be a translation for your language, and you may want
161 to contribute an update. This may be because you would want to improve
162 the translation of existing messages, or because the git-gui software
163 itself was updated and there are new messages that need translation.
165 In any case, make sure you are up-to-date before starting your work:
167 $ git pull
169 In the former case, you will edit po/af.po (again, replace "af" with
170 your language code), and after testing and updating the Last-Translator:
171 and PO-Revision-Date: lines, "add/commit/push" as in the previous
172 section.
174 By comparing "POT-Creation-Date:" line in po/git-gui.pot file and
175 po/af.po file, you can tell if there are new messages that need to be
176 translated. You would need the GNU gettext package to perform this
177 step.
179 $ msgmerge -U po/af.po po/git-gui.pot
181 This updates po/af.po (again, replace "af" with your language
182 code) so that it contains msgid lines (i.e. the original) that
183 your translation did not have before. There are a few things to
184 watch out for:
186 - The original text in English of an older message you already
187 translated might have been changed. You will notice a comment line
188 that begins with "#, fuzzy" in front of such a message. msgmerge
189 tool made its best effort to match your old translation with the
190 message from the updated software, but you may find cases that it
191 matched your old translated message to a new msgid and the pairing
192 does not make any sense -- you would need to fix them, and then
193 remove the "#, fuzzy" line from the message (your fixed translation
194 of the message will not be used before you remove the marker).
196 - New messages added to the software will have msgstr lines with empty
197 strings. You would need to translate them.
199 The po/git-gui.pot file is updated by the internationalization
200 coordinator from time to time. You _could_ update it yourself, but
201 translators are discouraged from doing so because we would want all
202 language teams to be working off of the same version of git-gui.pot.
204 ****************************************************************
206 This section is a note to the internationalization coordinator, and
207 translators do not have to worry about it too much.
209 The message template file po/git-gui.pot needs to be kept up to date
210 relative to the software the translations apply to, and it is the
211 responsibility of the internationalization coordinator.
213 When updating po/git-gui.pot file, however, _never_ run "msgmerge -U
214 po/xx.po" for individual language translations, unless you are absolutely
215 sure that there is no outstanding work on translation for language xx.
216 Doing so will create unnecessary merge conflicts and force needless
217 re-translation on translators. The translator however may not have access
218 to the msgmerge tool, in which case the coordinator may run it for the
219 translator as a service.
221 But mistakes do happen. Suppose a translation was based on an older
222 version X, the POT file was updated at version Y and then msgmerge was run
223 at version Z for the language, and the translator sent in a patch based on
224 version X:
226 ? translated
227 /
228 ---X---Y---Z (master)
230 The coordinator could recover from such a mistake by first applying the
231 patch to X, replace the translated file in Z, and then running msgmerge
232 again based on the updated POT file and commit the result. The sequence
233 would look like this:
235 $ git checkout X
236 $ git am -s xx.patch
237 $ git checkout master
238 $ git checkout HEAD@{1} po/xx.po
239 $ msgmerge -U po/xx.po po/git-gui.pot
240 $ git commit -c HEAD@{1} po/xx.po
242 State in the message that the translated messages are based on a slightly
243 older version, and msgmerge was run to incorporate changes to message
244 templates from the updated POT file. The result needs to be further
245 translated, but at least the messages that were updated by the patch that
246 were not changed by the POT update will survive the process and do not
247 need to be re-translated.