git-gui: Improve directions regarding POT update in po/README
Keeping POT up to date relative to the software is absolutely necessary. What is unwarranted is updating language files at the same time by running msgmerge without checking if there is any outstanding translation work first. If we assume that the translators do not have access to msgmerge, that is a good service to them (the less they have to do, the better), but otherwise, it is better to be leave po/${language}.po files alone. Signed-off-by: Junio C Hamano <gitster@pobox.com> Signed-off-by: Shawn O. Pearce <spearce@spearce.org>
Junio C Hamano committed
Mar 15, 2008 at 00:43 UTC
739a6d4970836463f5ffc9f56381e4efc9e61914
1 file changed
+50
-12
po/README
+50
-12
@@ -178,18 +178,6 @@ step.
178
179
$ msgmerge -U po/af.po po/git-gui.pot
180
181
-[NEEDSWORK: who is responsible for updating po/git-gui.pot file by
182
-running xgettext? IIRC, Christian recommended against running it
183
-nilly-willy because it can become a source of unnecessary merge
184
-conflicts. Perhaps we should mention something like "
185
-
186
-The po/git-gui.pot file is updated by the internationalization
187
-coordinator from time to time. You _could_ update it yourself, but
188
-translators are discouraged from doing so because we would want all
189
-language teams to be working off of the same version of git-gui.pot.
190
-
191
-" here?]
192
-
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
@@ -207,3 +195,53 @@ watch out for:
195
196
- New messages added to the software will have msgstr lines with empty
197
strings. You would need to translate them.
198
+
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.
203
+
204
+****************************************************************
205
+
206
+This section is a note to the internationalization coordinator, and
207
+translators do not have to worry about it too much.
208
+
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.
212
+
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.
220
+
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:
225
+
226
+ ? translated
227
+ /
228
+ ---X---Y---Z (master)
229
+
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:
234
+
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
241
+
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.