git-gui: Add a simple implementation of SSH_ASKPASS.
[gitweb.git] / po / README
index e7cf40524755e1b66add9e2e3ac3200290e3eb48..595bbf5dee97e34eeab46b742225fce2f95ab052 100644 (file)
--- a/po/README
+++ b/po/README
@@ -88,11 +88,20 @@ matching msgid lines.  A few tips:
    you would typically want to have corresponding ones in the string on
    your msgstr line.
 
+ - Some messages contain an optional context indicator at the end,
+   for example "@@noun" or "@@verb".  This indicator allows the
+   software to select the correct translation depending upon the use.
+   The indicator is not actually part of the message and will not
+   be shown to the end-user.
+
+   If your language does not require a different translation you
+   will still need to translate both messages.
+
  - Often the messages being translated are format strings given to
    "printf()"-like functions.  Make sure "%s", "%d", and "%%" in your
    translated messages match the original.
 
-   When you have to change the order of words, you can add "<number>\$"
+   When you have to change the order of words, you can add "<number>$"
    between '%' and the conversion ('s', 'd', etc.) to say "<number>-th
    parameter to the format string is used at this point".  For example,
    if the original message is like this:
@@ -102,12 +111,17 @@ matching msgid lines.  A few tips:
    and if for whatever reason your translation needs to say weight first
    and then length, you can say something like:
 
-       "WEIGHT IS %2\$d, LENGTH IS %1\$d"
+       "WEIGHT IS %2$d, LENGTH IS %1$d"
+
+   A format specification with a '*' (asterisk) refers to *two* arguments
+   instead of one, hence the succeeding argument number is two higher
+   instead of one. So, a message like this
+
+       "%s ... %*i of %*i %s (%3i%%)"
+
+   is equivalent to
 
-   The reason you need a backslash before dollar sign is because
-   this is a double quoted string in Tcl language, and without
-   it the letter introduces a variable interpolation, which you
-   do not want here.
+       "%1$s ... %2$*i of %4$*i %6$s (%7$3i%%)"
 
  - A long message can be split across multiple lines by ending the
    string with a double quote, and starting another string on the next
@@ -169,18 +183,6 @@ step.
 
        $ msgmerge -U po/af.po po/git-gui.pot
 
-[NEEDSWORK: who is responsible for updating po/git-gui.pot file by
-running xgettext?  IIRC, Christian recommended against running it
-nilly-willy because it can become a source of unnecessary merge
-conflicts.  Perhaps we should mention something like "
-
-The po/git-gui.pot file is updated by the internationalization
-coordinator from time to time.  You _could_ update it yourself, but
-translators are discouraged from doing so because we would want all
-language teams to be working off of the same version of git-gui.pot.
-
-" here?]
-
 This updates po/af.po (again, replace "af" with your language
 code) so that it contains msgid lines (i.e. the original) that
 your translation did not have before.  There are a few things to
@@ -198,3 +200,53 @@ watch out for:
 
  - New messages added to the software will have msgstr lines with empty
    strings.  You would need to translate them.
+
+The po/git-gui.pot file is updated by the internationalization
+coordinator from time to time.  You _could_ update it yourself, but
+translators are discouraged from doing so because we would want all
+language teams to be working off of the same version of git-gui.pot.
+
+****************************************************************
+
+This section is a note to the internationalization coordinator, and
+translators do not have to worry about it too much.
+
+The message template file po/git-gui.pot needs to be kept up to date
+relative to the software the translations apply to, and it is the
+responsibility of the internationalization coordinator.
+
+When updating po/git-gui.pot file, however, _never_ run "msgmerge -U
+po/xx.po" for individual language translations, unless you are absolutely
+sure that there is no outstanding work on translation for language xx.
+Doing so will create unnecessary merge conflicts and force needless
+re-translation on translators.  The translator however may not have access
+to the msgmerge tool, in which case the coordinator may run it for the
+translator as a service.
+
+But mistakes do happen.  Suppose a translation was based on an older
+version X, the POT file was updated at version Y and then msgmerge was run
+at version Z for the language, and the translator sent in a patch based on
+version X:
+
+         ? translated
+        /
+    ---X---Y---Z (master)
+
+The coordinator could recover from such a mistake by first applying the
+patch to X, replace the translated file in Z, and then running msgmerge
+again based on the updated POT file and commit the result.  The sequence
+would look like this:
+
+    $ git checkout X
+    $ git am -s xx.patch
+    $ git checkout master
+    $ git checkout HEAD@{1} po/xx.po
+    $ msgmerge -U po/xx.po po/git-gui.pot
+    $ git commit -c HEAD@{1} po/xx.po
+
+State in the message that the translated messages are based on a slightly
+older version, and msgmerge was run to incorporate changes to message
+templates from the updated POT file.  The result needs to be further
+translated, but at least the messages that were updated by the patch that
+were not changed by the POT update will survive the process and do not
+need to be re-translated.