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