git-gui po/README: Guide to translators
This short note is to help a translation contributor to help us localizing git-gui message files by covering the basics. Signed-off-by: Junio C Hamano <gitster@pobox.com>
Junio C Hamano committed
Jul 27, 2007 at 16:05 UTC
2631a81b901fc7baa274f98530a0d9cc05cecd17
1 file changed
+205
po/README
new
+205
@@ -0,0 +1,205 @@
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
+
21
+You would then need to clone the git-gui internationalization project
22
+repository, 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
+
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.
32
+
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".
36
+
37
+
38
+2. Starting a new language.
39
+
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?
43
+
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:
46
+
47
+ http://www.loc.gov/standards/iso639-2/php/code_list.php
48
+
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.
53
+
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:
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
+
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:
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
+
91
+ - Often the messages being translated are format strings given to
92
+ "printf()"-like functions. Make sure "%s", "%d", and "%%" in your
93
+ translated messages match the original.
94
+
95
+ When you have to change the order of words, you can add "<number>\$"
96
+ between '%' and the conversion ('s', 'd', etc.) to say "<number>-th
97
+ parameter to the format string is used at this point". For example,
98
+ if the original message is like this:
99
+
100
+ "Length is %d, Weight is %d"
101
+
102
+ and if for whatever reason your translation needs to say weight first
103
+ and then length, you can say something like:
104
+
105
+ "WEIGHT IS %2\$d, LENGTH IS %1\$d"
106
+
107
+ The reason you need a backslash before dollar sign is because
108
+ this is a double quoted string in Tcl language, and without
109
+ it the letter introduces a variable interpolation, which you
110
+ do not want here.
111
+
112
+ - A long message can be split across multiple lines by ending the
113
+ string with a double quote, and starting another string on the next
114
+ line with another double quote. They will be concatenated in the
115
+ result. For example:
116
+
117
+ #: lib/remote_branch_delete.tcl:189
118
+ #, tcl-format
119
+ msgid ""
120
+ "One or more of the merge tests failed because you have not fetched the "
121
+ "necessary commits. Try fetching from %s first."
122
+ msgstr ""
123
+ "HERE YOU WILL WRITE YOUR TRANSLATION OF THE ABOVE LONG "
124
+ "MESSAGE IN YOUR LANGUAGE."
125
+
126
+You can test your translation by running "make install", which would
127
+create po/af.msg file and installs the result, and then running the
128
+resulting git-gui under your locale:
129
+
130
+ $ make install
131
+ $ LANG=af git-gui
132
+
133
+There is a trick to test your translation without first installing, if
134
+you prefer. First, create this symbolic link in the source tree:
135
+
136
+ $ ln -s ../po lib/msgs
137
+
138
+After setting up such a symbolic link, you can:
139
+
140
+ $ make
141
+ $ LANG=af ./git-gui.sh
142
+
143
+When you are satisfied with your translation, commit your changes, and
144
+push it back to the 'mob' branch:
145
+
146
+ $ edit po/af.po
147
+ ... be sure to update Last-Translator: and
148
+ ... PO-Revision-Date: lines.
149
+ $ git add po/af.po
150
+ $ git commit -m 'Started Afrikaans translation.'
151
+ $ git push
152
+
153
+
154
+3. Updating your translation.
155
+
156
+There may already be a translation for your language, and you may want
157
+to contribute an update. This may be because you would want to improve
158
+the translation of existing messages, or because the git-gui software
159
+itself was updated and there are new messages that need translation.
160
+
161
+In any case, make sure you are up-to-date before starting your work:
162
+
163
+ $ git pull
164
+
165
+In the former case, you will edit po/af.po (again, replace "af" with
166
+your language code), and after testing and updating the Last-Translator:
167
+and PO-Revision-Date: lines, "add/commit/push" as in the previous
168
+section.
169
+
170
+By comparing "POT-Creation-Date:" line in po/git-gui.pot file and
171
+po/af.po file, you can tell if there are new messages that need to be
172
+translated. You would need the GNU gettext package to perform this
173
+step.
174
+
175
+ $ msgmerge -U po/af.po po/git-gui.pot
176
+
177
+[NEEDSWORK: who is responsible for updating po/git-gui.pot file by
178
+running xgettext? IIRC, Christian recommended against running it
179
+nilly-willy because it can become a source of unnecessary merge
180
+conflicts. Perhaps we should mention something like "
181
+
182
+The po/git-gui.pot file is updated by the internationalization
183
+coordinator from time to time. You _could_ update it yourself, but
184
+translators are discouraged from doing so because we would want all
185
+language teams to be working off of the same version of git-gui.pot.
186
+
187
+" here?]
188
+
189
+This updates po/af.po (again, replace "af" with your language
190
+code) so that it contains msgid lines (i.e. the original) that
191
+your translation did not have before. There are a few things to
192
+watch out for:
193
+
194
+ - The original text in English of an older message you already
195
+ translated might have been changed. You will notice a comment line
196
+ that begins with "#, fuzzy" in front of such a message. msgmerge
197
+ tool made its best effort to match your old translation with the
198
+ message from the updated software, but you may find cases that it
199
+ matched your old translated message to a new msgid and the pairing
200
+ does not make any sense -- you would need to fix them, and then
201
+ remove the "#, fuzzy" line from the message (your fixed translation
202
+ of the message will not be used before you remove the marker).
203
+
204
+ - New messages added to the software will have msgstr lines with empty
205
+ strings. You would need to translate them.