From: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
Date: Fri, 10 Sep 2010 18:46:20 +0000 (+0000)
Subject: gettext docs: add "Marking strings for translation" section in po/README
X-Git-Tag: ko-pu~10^2~46
X-Git-Url: https://git.tokkee.org/?a=commitdiff_plain;h=76e01a1258aa3fe907dfeba618de6d8796feacb9;p=git.git

gettext docs: add "Marking strings for translation" section in po/README

Add a "Marking strings for translation" section to po/README and
mention it in Documentation/CodingGuidelines.

This section documents how the maintainers of Git's source code should
go about properly marking strings for translation.

Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---

diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
index 09ffc4656..93fac9127 100644
--- a/Documentation/CodingGuidelines
+++ b/Documentation/CodingGuidelines
@@ -77,6 +77,10 @@ For shell scripts specifically (not exhaustive):
      are ERE elements not BRE (note that \? and \+ are not even part
      of BRE -- making them accessible from BRE is a GNU extension).
 
+ - Use Git's gettext wrappers in git-sh-i18n to make the user
+   interface translatable. See "Marking strings for translation" in
+   po/README.
+
 For C programs:
 
  - We use tabs to indent, and interpret tabs as taking up to
@@ -139,3 +143,6 @@ For C programs:
 
  - When we pass <string, length> pair to functions, we should try to
    pass them in that order.
+
+ - Use Git's gettext wrappers to make the user interface
+   translatable. See "Marking strings for translation" in po/README.
diff --git a/po/README b/po/README
index 8ba06c848..4dc0c2d98 100644
--- a/po/README
+++ b/po/README
@@ -2,7 +2,8 @@ Core GIT Translations
 =====================
 
 This directory holds the translations for the core of Git. This
-document describes how to add to and maintain these translations.
+document describes how to add to and maintain these translations, and
+how to mark source strings for translation.
 
 
 Generating a .pot file
@@ -69,3 +70,42 @@ changed PO file with `msgfmt --check`, the --check option flags many
 common errors, e.g. missing printf format strings, or translated
 messages that deviate from the originals in whether they begin/end
 with a newline or not.
+
+
+Marking strings for translation
+-------------------------------
+
+Before strings can be translated they first have to be marked for
+translation.
+
+Git uses an internationalization interface that wraps the system's
+gettext library, so most of the advice in your gettext documentation
+(on GNU systems `info gettext` in a terminal) applies.
+
+General advice:
+
+ - Don't mark everything for translation, only strings which will be
+   read by humans (the porcelain interface) should be translated.
+
+   The output from Git's plumbing utilities will primarily be read by
+   programs and would break scripts under non-C locales if it was
+   translated. Plumbing strings should not be translated, since
+   they're part of Git's API.
+
+ - Adjust the strings so that they're easy to translate. Most of the
+   advice in `info '(gettext)Preparing Strings'` applies here.
+
+ - If something is unclear or ambiguous you can use a "TRANSLATORS"
+   comment to tell the translators what to make of it. These will be
+   extracted by xgettext(1) and put in the po/*.po files, e.g. from
+   git-am.sh:
+
+       # TRANSLATORS: Make sure to include [y], [n], [e], [v] and [a]
+       # in your translation. The program will only accept English
+       # input at this point.
+       gettext "Apply? [y]es/[n]o/[e]dit/[v]iew patch/[a]ccept all "
+
+   Or in C, from builtin/revert.c:
+
+       /* TRANSLATORS: %s will be "revert" or "cherry-pick" */
+       die(_("%s: Unable to write new index file"), me);