add git zh_CN l10n examples

jiangxin · jiangxin · commit 4149c7921f2b · 2012-03-29T15:50:59.000+08:00
Signed-off-by: Jiang Xin &lt;worldhello.net@gmail.com&gt;
diff --git a/_posts/2012-02-28-git-l10n.md b/_posts/2012-02-28-git-l10n.md
@@ -3,96 +3,200 @@ layout: post
 title: "Git中文本地化"
 ---
 
-Git从版本1.7.5（2011年4月）即开始国际化/本地化（i18n/l10n）的准备工作，到版本1.7.8正式完成了Git国际化/本地化框架和基础设施工作。
+Git从版本1.7.5（2011年4月）即开始国际化/本地化（i18n/l10n）的准备工作，到版本1.7.8正式完成了Git国际化/本地化框架和基础设施的工作。
 参见 [提交 5e9637c](https://github.com/git/git/commit/5e9637c629702e3d41ad01d95956d1835d7338e0) 。
 
-本地化工作也已经开始，可能会在 Git 1.7.10 版本对部分语种实现本地化。
+针对部分语种的本地化工作已经开始，最早会在 Git 1.7.10 版本开始提供中文的本地化支持。
 
-## Git中文本地化 ##
+## Git中文本地化注意事项 ##
 
-Git中文本地化的协同版本库为： [https://github.com/jiangxin/git-po-zh_CN/](https://github.com/jiangxin/git-po-zh_CN/) ，以下简称 `git-po-zh_CN` 。
-参与Git中文本地化，请使用GitHub提供的 Fork 和 Pull Request 工具。
+Git本地化（包括中文本地化）的协同方式不同于Git项目本身，不使用邮件列表进行提交评审，而是通过GitHub的协同工具来完成，这在Git邮件列表中有专门的讨论： [Git官方邮件列表](http://article.gmane.org/gmane.comp.version-control.git/189584) 。最终确定的工作流程参见Git源码中的文件 [po/README](https://github.com/git/git/blob/master/po/README) 。
 
-1. 本地化参与者使用 GitHub 的 Fork 功能从 `git-po-zh_CN` 派生项目，并将提交推送至派生版本库中。
+### 工作流程 ###
 
-2. 本地化参与者使用 GitHub 的 Pull Request 功能从派生版本库中的提交创建 Pull Request 到 `git-po-zh_CN` 版本库。
+中文本地化的协同版本库为： [https://github.com/gotgit/git-po-zh_CN/][git-po-zh_CN] ，以下简称 [git-po-zh_CN] 。
+如果您对翻译有修改或补充，请参照如下工作流程。
 
-3. 版本库 `git-po-zh_CN` 的管理者审核 Pull Request。若审核通过则将提交合并到代码树中。
+1. 使用 GitHub 的 Fork 功能从 [git-po-zh_CN] 派生项目。
 
-本地化参与者在创建 Pull Request 前，请先确认提交是否遵守下列规范：
-
-* 只能修改 `po/zh_CN.po` 文件，若改动了其他文件则提交被拒绝。
-
-* 提交说明必须使用英文，若在提交说明中包含中文则提交被拒绝。
-
-* 提交说明请使用 `l10n:` 作为前缀，以便和Git其他代码的提交相区分。
-
-* 提交说明中应包含签名。使用命令 `git commit -s` 会自动在提交说明中添加签名。
-
-下面介绍一下 Git 国际化和本地化的整个工作流程。
-
-## Git的国际化和本地化 ##
-
-国际化（i18n）和本地化（l10n）的区别在于其工作内容的不同。Git国际化所做的工作包括：
-
-- Gettext 相关函数的封装。
-- C 语言程序中字符串使用 gettext 相关函数标记。
-- Shell脚本中的字符串用 git-sh-i18n 中封装的 gettext 方法标记。 
-- 提取和维护语言模版文件： `po/git.pot` 。
-
-Git本地化的工作包括：
-
-- 参照模版文件 `po/git.pot` ，逐条翻译为本地语言文件。如简体中文翻译为 `po/zh_CN.po` 。
-- 当 `po/git.pot` 更新时同步更新本地语言文件。
+2. 从您个人派生的版本库克隆。如：
 
-## Git国际化维护模式 ##
+        git clone git@github.com:<your-account>/git-po-zh_CN.git
+        cd git-po-zh_CN
 
-Git国际化的维护模式和 `git.git` 源代码的维护方式并无差别，即：
+3. 修改 [po/zh_CN.po] 文件，补充和完善翻译内容，并提交。
 
-- 贡献者使用 `git format-patch` 命令，将提交转换为补丁文件。
-- 贡献者使用邮件客户端或者调用 `git send-email` 命令发送邮件，将补丁文件发送到Git邮件列表。
-- 开发者通过邮件列表进行代码审核。
-- Git维护者使用 `git am` 命令将邮件中包含的代码补丁应用到代码树。
+        edit po/zh_CN.po
+        ...
+        git add -u
+        git commit
 
-## Git本地化维护模式 ##
+4. 将您的提交推送至GitHub（您的派生版本库）。
 
-Git本地化则完全不同，不能采用 `git.git` 标准的工作模式。因为本地化涉及的翻译的提交只应该在使用同一语种的用户范围内进行审核，Git官方邮件列表中没有人懂得所有语言。
+        git push
 
-Junio 在 [Git官方邮件列表](http://article.gmane.org/gmane.comp.version-control.git/189584) 中对本地化工作流程设想如下：
+5. 使用GitHub提供的 pull request 功能，创建到 [git-po-zh_CN] 版本库的 Pull Request。
 
-1. l10n 协调者从 `git.git` 派生一个专门用于本地化维护的版本库 `git-po` 。
+6. 版本库 [git-po-zh_CN] 的管理者审核您的 Pull Request，若审核通过则将提交合并到代码树中，若不通过则会给出原因。
 
-    例如: [https://github.com/gotgit/git-po/](https://github.com/gotgit/git-po/) 。
+### 提交规范 ###
 
-2. l10n 协调者在 `git-po` 版本库中创建一个 `po/git.pot` 文件。这个文件的维护即由 l10n 协调者负责。
-
-3. 每一个语种会有一个 l10n 团队，并由一个志愿者领导该 l10n 团队。每一个 l10n 团队领导者从版本库 `git-po` 派生本地化专用版本库 `git-po-$locale` 。
-
-    例如中文本地化版本库 `git-po-zh_CN` ，地址为: [https://github.com/jiangxin/git-po-zh_CN/](https://github.com/jiangxin/git-po-zh_CN/) 。
-
-4. 每一个本地化团队工作在他们的 `git-po-$locale` 版本库。只能修改 `po/$locale.po` 文件，而不能改动其他。
-   例如本地化团队不能改动 `po/git.pot` 文件或 `git-po-$locale` 库中的任何源代码文件。 
-
-    本地化团队的协同方式不做规定，可以使用 GitHub，或者一个大的团队可能需要自己的邮件列表。
-
-
-5. 每一个本地化团队会不时地要求 l10n 协调者从他们的本地化版本库拉拽（pull）提交历史，以便 l10n 协调者更新 `git-po` 版本库中的翻译。
-   本地化团队在请求 l10n 协调者拉拽前先可对版本库提交历史进行整理。
-
-6. l10n 协调者不时地从 `git.git` 合并以便获取更新以生成新的 `po/git.pot` 文件。这个更新不要太快，一周一次或更少。
-   l10n 协调者更新 `po/git.pot` 文件后，通知l10n团队。
-
-7. l10n 团队从 `git-po` 拉拽，用获取的新的 `po/git.pot` 模版文件更新 `git-po-$locale` 版本库中的本地化文件。（返回步骤4）
-
-8. l10n 协调者不时地请求 Junio（Git维护者）从 `git-po` 版本库拉拽。
+本地化参与者在创建 Pull Request 前，请先确认提交是否遵守下列规范：
 
-Git本地化贡献者常见的错误如下，在提交时需要注意。
+* 只能修改 [po/zh_CN.po] 文件，或者在 [po/TEAMS] 文件中补充中文翻译团队成员列表。若对其他文件进行改动，会导致 pull request 被拒绝。
 
-1. 提交不要改动除 `po/$locale.po` 外的任何文件。
+* 提交说明符合 “50/72 原则”。
 
-2. 提交说明使用英文，不要在提交说明中出现本地化语言。
+  - 提交说明第一行会作为补丁邮件的标题或者作为简要日志输出，长度以50个字符为限。
 
-3. 提交说明的前缀使用 `l10n:` ，以便能够直观地和Git提交相区分。
+    建议这部分提交说明使用 `l10n:` 作为前缀，以便和Git其他代码的提交相区分。
 
-4. 提交中包含签名，即使用 `git commit -s` 命令在提交中嵌入签名。
+    还有注意这部分内容不能包含中文。
+ 
+  - 一个空行
 
+  - 关于提交的大段说明，例如原翻译存在的问题，为什么要进行修改等。
+  
+    提交说明可以折行，每行以72个字符为限。
+    
+    这部分提交说明可以包含少量中文。
+
+
+* 提交说明中包含签名。可以通过命令 `git commit -s` 会自动在提交说明中添加签名。
+
+### 翻译示例 ###
+
+* C语言字符串中的参数（占位符）很重要，需要维持其顺序。
+
+  注意字符串中出现的两个占位符 `%s` 和 `%s` 的先后顺序要严格保持。
+
+        #: builtin/pack-objects.c:2326
+        #, c-format
+        msgid "unable to parse value '%s' for option %s"
+        msgstr "不能解析值 '%s' 针对于选项 %s"
+
+* 然而，Shell语言字符串中的变量（占位符）的顺序则不重要，可以根据翻译需要调整先后次序。
+
+        msgid "Clone of '$url' into submodule path '$path' failed"
+        msgstr "无法克隆 '$url' 到子模组路径 '$path'"
+
+* 大多数情况下，英文标点翻译为中文标点。如：
+
+        msgid ""
+        "'%s' appears to be a git command, but we were not\n"
+        "able to execute it. Maybe git-%s is broken?"
+        msgstr ""
+        "'%s' 像是一个 git 命令，但却无法运行。\n"
+        "可能是 git-%s 受损？"
+
+* 但是有的字符串要由程序进行后处理，并且处理过程中需要依赖其中的标点符号，这种情况下标点符号不能翻译，要严格保持。如：
+
+        #  译者：末尾两个字节可能被删减，如果翻译为中文标点会出现半个汉字
+        #: wt-status.c:250
+        msgid "modified content, "
+        msgstr "修改的内容, "
+
+* 大多数情况下，要注意保持原文中句子前、后，以及句子中间的空白。大多是排版的需要。
+
+        #  译者：注意保持前导空格
+        #: diff.c:105
+        #, c-format
+        msgid "  Failed to parse dirstat cut-off percentage '%.*s'\n"
+        msgstr "  无法解析 dirstat 阈值 '%.*s'\n"
+
+        #  译者：为保证在输出中对齐，注意调整句中空格！
+        #: wt-status.c:266
+        #, c-format
+        msgid "new file:   %s"
+        msgstr "新文件：    %s"
+
+        #  译者：为保证在输出中对齐，注意调整句中空格！
+        #: wt-status.c:269
+        #, c-format
+        msgid "copied:     %s -> %s"
+        msgstr "拷贝：      %s -> %s"
+
+        #  译者：注意保持句尾空格
+        #: wt-status.c:890
+        msgid "Initial commit on "
+        msgstr "初始提交于 "
+
+* 但有的情况下涉及到两个翻译为中文的字符串拼接，原文中句子前、后包括句中的空白需要在译文中删除。
+
+        #  译者：汉字之间无空格，故删除尾部空格
+        #. TRANSLATORS: This is "remote " in "remote branch '%s' not found"
+        #: builtin/branch.c:163
+        msgid "remote "
+        msgstr "远程"
+
+        #  译者：%s若翻为中文，前后不需要空格
+        #: builtin/commit.c:783
+        #, c-format
+        msgid ""
+        "\n"
+        "It looks like you may be committing a %s.\n"
+        "If this is not correct, please remove the file\n"
+        "\t%s\n"
+        "and try again.\n"
+        msgstr ""
+        "\n"
+        "看起来您正在提交一个%s。\n"
+        "如果不是这样，请删除文件\n"
+        "\t%s\n"
+        "然后重试。\n"
+
+* 大多数情况下，考虑到输出的美观，需要重新对译文字符串进行排版（重新设置换行符）。
+
+        #: builtin/commit.c:42
+        msgid ""
+        "Your name and email address were configured automatically based\n"
+        "on your username and hostname. Please check that they are accurate.\n"
+        "You can suppress this message by setting them explicitly:\n"
+        "\n"
+        "    git config --global user.name \"Your Name\"\n"
+        "    git config --global user.email you@example.com\n"
+        "\n"
+        "After doing this, you may fix the identity used for this commit with:\n"
+        "\n"
+        "    git commit --amend --reset-author\n"
+        msgstr ""
+        "您的姓名和邮件地址基于登录名和主机名进行了自动设置。请检查它们正确\n"
+        "与否。您可以通过下面的命令对其进行明确地设置以免再出现本提示信息：\n"
+        "\n"
+        "    git config --global user.name \"Your Name\"\n"
+        "    git config --global user.email you@example.com\n"
+        "\n"
+        "设置完毕后，您可以用下面的命令来修正本次提交所使用的用户身份：\n"
+        "\n"
+        "    git commit --amend --reset-author\n"
+
+* 但有时保持原有换行方式更好。
+
+  下面的示例中如果译文将两行合并为同一行，会因为两处的 `%s` 被扩展造成输出太长。
+
+        #  译者：保持原换行格式，在输出时 %s 的替代内容会让字符串变长
+        #: builtin/branch.c:137
+        #, c-format
+        msgid ""
+        "deleting branch '%s' that has been merged to\n"
+        "         '%s', but not yet merged to HEAD."
+        msgstr ""
+        "将要删除的分支 '%s' 已经被合并到\n"
+        "         '%s'，但未合并到 HEAD。"
+
+## 术语表 ##
+
+已翻译内容中涉及到的术语的翻译做到了基本一致，若遇到不确认的术语请先在已翻译内容中查找，恕不一一列举。
+
+## 为什么有的Git命令的输出还没有翻译？ ##
+
+如果遇到您需要的Git命令尚未翻译，往往不是因为中文本地化翻译未完成，而是因为相应命令的输出尚未进行国际化标识。
+Git 的国际化（i18n）和本地化（l10n）刚刚开始，肯定存在很多命令输出被遗漏，没有使用相关语法进行标识，导致未能在本地化文件中出现。
+
+如果确实属于此种情况，就不能按照本文介绍的中文本地化工作流程进行操作，而是按照修改Git源代码的工作流程进行工作。
+
+具体参见 [Documentation/SubmittingPatchest](https://github.com/git/git/blob/master/Documentation/SubmittingPatches) 。
+
+ [git-po-zh_CN]: https://github.com/gotgit/git-po-zh_CN/
+ [po/zh_CN.po]: https://github.com/gotgit/git-po-zh_CN/blob/master/po/zh_CN.po
+ [po/TEAMS]: https://github.com/gotgit/git-po-zh_CN/blob/master/po/TEAMS
