undef/git-commit-vandalism
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

l10n: README: refactor to use GFM syntax

Browse Source 
Format README.md using GFM (GitHub Flavored Markdown) syntax.

- In order to use more than 3 level headings, use ATX style headings
  instead of setext style headings.

- In order to add highlights for code blocks, use fenced code blocks
  instead of indented code blocks.

Signed-off-by: Jiang Xin <worldhello.net@gmail.com>
This commit is contained in:
Jiang Xin 2021-08-06 11:07:48 +08:00
parent fb2aacea67
commit cb92e28384
1 changed files with 237 additions and 186 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

423
po/README.md
View File

@ -1,5 +1,4 @@
Core GIT Translations # Core GIT Translations
=====================
This directory holds the translations for the core of Git. This document This directory holds the translations for the core of Git. This document
describes how you can contribute to the effort of enhancing the language describes how you can contribute to the effort of enhancing the language
@ -8,14 +7,14 @@ coverage and maintaining the translation.
The localization (l10n) coordinator, Jiang Xin <worldhello.net@gmail.com>, The localization (l10n) coordinator, Jiang Xin <worldhello.net@gmail.com>,
coordinates our localization effort in the l10 coordinator repository: coordinates our localization effort in the l10 coordinator repository:
https://github.com/git-l10n/git-po/ https://github.com/git-l10n/git-po/
The two character language translation codes are defined by ISO_639-1, as The two character language translation codes are defined by ISO\_639-1, as
stated in the gettext(1) full manual, appendix A.1, Usual Language Codes. stated in the gettext(1) full manual, appendix A.1, Usual Language Codes.
Contributing to an existing translation ## Contributing to an existing translation
---------------------------------------
As a contributor for a language XX, you should first check TEAMS file in As a contributor for a language XX, you should first check TEAMS file in
this directory to see whether a dedicated repository for your language XX this directory to see whether a dedicated repository for your language XX
exists. Fork the dedicated repository and start to work if it exists. exists. Fork the dedicated repository and start to work if it exists.
@ -28,10 +27,10 @@ For this case, wrong translations should be reported and fixed through
their workflows. their workflows.
Creating a new language translation ## Creating a new language translation
-----------------------------------
If you are the first contributor for the language XX, please fork this If you are the first contributor for the language XX, please fork this
repository, prepare and/or update the translated message file po/XX.po repository, prepare and/or update the translated message file "po/XX.po"
(described later), and ask the l10n coordinator to pull your work. (described later), and ask the l10n coordinator to pull your work.
If there are multiple contributors for the same language, please first If there are multiple contributors for the same language, please first
@ -40,8 +39,8 @@ language, so that the l10n coordinator only needs to interact with one
person per language. person per language.
Core translation ## Core translation
----------------
The core translation is the smallest set of work that must be completed The core translation is the smallest set of work that must be completed
for a new language translation. Because there are more than 5000 messages for a new language translation. Because there are more than 5000 messages
in the template message file "po/git.pot" that need to be translated, in the template message file "po/git.pot" that need to be translated,
@ -51,21 +50,25 @@ The core template message file which contains a small set of messages
will be generated in "po-core/core.pot" automatically by running a helper will be generated in "po-core/core.pot" automatically by running a helper
program named "git-po-helper" (described later). program named "git-po-helper" (described later).
git-po-helper init --core XX.po ```shell
git-po-helper init --core XX.po
```
After translating the generated "po-core/XX.po", you can merge it to After translating the generated "po-core/XX.po", you can merge it to
"po/XX.po" using the following commands: "po/XX.po" using the following commands:
msgcat po-core/XX.po po/XX.po -s -o /tmp/XX.po ```shell
mv /tmp/XX.po po/XX.po msgcat po-core/XX.po po/XX.po -s -o /tmp/XX.po
git-po-helper update XX.po mv /tmp/XX.po po/XX.po
git-po-helper update XX.po
```
Edit "po/XX.po" by hand to fix "fuzzy" messages, which may have misplaced Edit "po/XX.po" by hand to fix "fuzzy" messages, which may have misplaced
translated messages and duplicate messages. translated messages and duplicate messages.
Translation Process Flow ## Translation Process Flow
------------------------
The overall data-flow looks like this: The overall data-flow looks like this:
+-------------------+ +------------------+ +-------------------+ +------------------+
@ -79,21 +82,20 @@ The overall data-flow looks like this:
| Language Team XX | | Language Team XX |
+------------------+ +------------------+
* Translatable strings are marked in the source file. - Translatable strings are marked in the source file.
* L10n coordinator pulls from the source (1) - L10n coordinator pulls from the source (1)
* L10n coordinator updates the message template po/git.pot - L10n coordinator updates the message template "po/git.pot"
* Language team pulls from L10n coordinator (2) - Language team pulls from L10n coordinator (2)
* Language team updates the message file po/XX.po - Language team updates the message file "po/XX.po"
* L10n coordinator pulls from Language team (3) - L10n coordinator pulls from Language team (3)
* L10n coordinator asks the result to be pulled (4). - L10n coordinator asks the result to be pulled (4).
Maintaining the po/git.pot file ## Maintaining the "po/git.pot" file
-------------------------------
(This is done by the l10n coordinator). (This is done by the l10n coordinator).
The po/git.pot file contains a message catalog extracted from Git's The "po/git.pot" file contains a message catalog extracted from Git's
sources. The l10n coordinator maintains it by adding new translations with sources. The l10n coordinator maintains it by adding new translations with
msginit(1), or update existing ones with msgmerge(1). In order to update msginit(1), or update existing ones with msgmerge(1). In order to update
the Git sources to extract the messages from, the l10n coordinator is the Git sources to extract the messages from, the l10n coordinator is
@ -105,62 +107,68 @@ Language contributors use this file to prepare translations for their
language, but they are not expected to modify it. language, but they are not expected to modify it.
Initializing a XX.po file ## Initializing a "XX.po" file
-------------------------
(This is done by the language teams). (This is done by the language teams).
If your language XX does not have translated message file po/XX.po yet, If your language XX does not have translated message file "po/XX.po" yet,
you add a translation for the first time by running: you add a translation for the first time by running:
msginit --locale=XX ```shell
msginit --locale=XX
```
in the po/ directory, where XX is the locale, e.g. "de", "is", "pt_BR", in the "po/" directory, where XX is the locale, e.g. "de", "is", "pt\_BR",
"zh_CN", etc. "zh\_CN", etc.
Then edit the automatically generated copyright info in your new XX.po Then edit the automatically generated copyright info in your new "XX.po"
to be correct, e.g. for Icelandic: to be correct, e.g. for Icelandic:
@@ -1,6 +1,6 @@ ```diff
-# Icelandic translations for PACKAGE package. @@ -1,6 +1,6 @@
-# Copyright (C) 2010 THE PACKAGE'S COPYRIGHT HOLDER -# Icelandic translations for PACKAGE package.
-# This file is distributed under the same license as the PACKAGE package. -# Copyright (C) 2010 THE PACKAGE'S COPYRIGHT HOLDER
+# Icelandic translations for Git. -# This file is distributed under the same license as the PACKAGE package.
+# Copyright (C) 2010 Ævar Arnfjörð Bjarmason <avarab@gmail.com> +# Icelandic translations for Git.
+# This file is distributed under the same license as the Git package. +# Copyright (C) 2010 Ævar Arnfjörð Bjarmason <avarab@gmail.com>
# Ævar Arnfjörð Bjarmason <avarab@gmail.com>, 2010. +# This file is distributed under the same license as the Git package.
# Ævar Arnfjörð Bjarmason <avarab@gmail.com>, 2010.
```
And change references to PACKAGE VERSION in the PO Header Entry to And change references to PACKAGE VERSION in the PO Header Entry to
just "Git": just "Git":
perl -pi -e 's/(?<="Project-Id-Version: )PACKAGE VERSION/Git/' XX.po ```shell
perl -pi -e 's/(?<="Project-Id-Version: )PACKAGE VERSION/Git/' XX.po
```
Once you are done testing the translation (see below), commit the result Once you are done testing the translation (see below), commit the result
and ask the l10n coordinator to pull from you. and ask the l10n coordinator to pull from you.
Updating a XX.po file ## Updating a "XX.po" file
---------------------
(This is done by the language teams). (This is done by the language teams).
If you are replacing translation strings in an existing XX.po file to If you are replacing translation strings in an existing "XX.po" file to
improve the translation, just edit the file. improve the translation, just edit the file.
If there's an existing XX.po file for your language, but the repository If there's an existing "XX.po" file for your language, but the repository
of the l10n coordinator has newer po/git.pot file, you would need to first of the l10n coordinator has newer "po/git.pot" file, you would need to first
pull from the l10n coordinator (see the beginning of this document for its pull from the l10n coordinator (see the beginning of this document for its
URL), and then update the existing translation by running: URL), and then update the existing translation by running:
msgmerge --add-location --backup=off -U XX.po git.pot ```shell
msgmerge --add-location --backup=off -U XX.po git.pot
```
in the po/ directory, where XX.po is the file you want to update. in the "po/" directory, where "XX.po" is the file you want to update.
Once you are done testing the translation (see below), commit the result Once you are done testing the translation (see below), commit the result
and ask the l10n coordinator to pull from you. and ask the l10n coordinator to pull from you.
Fuzzy translation
----------------- ## Fuzzy translation
Fuzzy translation is a translation marked by comment "fuzzy" to let you Fuzzy translation is a translation marked by comment "fuzzy" to let you
know that the translation is out of date because the "msgid" has been know that the translation is out of date because the "msgid" has been
@ -172,14 +180,15 @@ After fixing the corresponding translation, you must remove the "fuzzy"
tag in the comment. tag in the comment.
Testing your changes ## Testing your changes
--------------------
(This is done by the language teams, after creating or updating XX.po file). (This is done by the language teams, after creating or updating "XX.po" file).
Before you submit your changes go back to the top-level and do: Before you submit your changes go back to the top-level and do:
make ```shell
make
```
On systems with GNU gettext (i.e. not Solaris) this will compile your On systems with GNU gettext (i.e. not Solaris) this will compile your
changed PO file with `msgfmt --check`, the --check option flags many changed PO file with `msgfmt --check`, the --check option flags many
@ -188,8 +197,7 @@ messages that deviate from the originals in whether they begin/end
with a newline or not. with a newline or not.
Marking strings for translation ## Marking strings for translation
-------------------------------
(This is done by the core developers). (This is done by the core developers).
@ -202,132 +210,155 @@ gettext library, so most of the advice in your gettext documentation
General advice: General advice:
- Don't mark everything for translation, only strings which will be - Don't mark everything for translation, only strings which will be
read by humans (the porcelain interface) should be translated. read by humans (the porcelain interface) should be translated.
The output from Git's plumbing utilities will primarily be read by The output from Git's plumbing utilities will primarily be read by
programs and would break scripts under non-C locales if it was programs and would break scripts under non-C locales if it was
translated. Plumbing strings should not be translated, since translated. Plumbing strings should not be translated, since
they're part of Git's API. they're part of Git's API.
- Adjust the strings so that they're easy to translate. Most of the - Adjust the strings so that they're easy to translate. Most of the
advice in `info '(gettext)Preparing Strings'` applies here. advice in `info '(gettext)Preparing Strings'` applies here.
- If something is unclear or ambiguous you can use a "TRANSLATORS" - If something is unclear or ambiguous you can use a "TRANSLATORS"
comment to tell the translators what to make of it. These will be 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 extracted by xgettext(1) and put in the "po/\*.po" files, e.g. from
git-am.sh: git-am.sh:
# TRANSLATORS: Make sure to include [y], [n], [e], [v] and [a] ```shell
# in your translation. The program will only accept English # TRANSLATORS: Make sure to include [y], [n], [e], [v] and [a]
# input at this point. # in your translation. The program will only accept English
gettext "Apply? [y]es/[n]o/[e]dit/[v]iew patch/[a]ccept all " # 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: Or in C, from builtin/revert.c:
/* TRANSLATORS: %s will be "revert" or "cherry-pick" */ ```c
die(_("%s: Unable to write new index file"), action_name(opts)); /* TRANSLATORS: %s will be "revert" or "cherry-pick" */
die(_("%s: Unable to write new index file"), action_name(opts));
```
We provide wrappers for C, Shell and Perl programs. Here's how they're We provide wrappers for C, Shell and Perl programs. Here's how they're
used: used:
C:
- Include builtin.h at the top, it'll pull in gettext.h, which ### C
defines the gettext interface. Consult with the list if you need to
use gettext.h directly.
- The C interface is a subset of the normal GNU gettext Include builtin.h at the top, it'll pull in gettext.h, which
interface. We currently export these functions: defines the gettext interface. Consult with the list if you need to
use gettext.h directly.
- _() The C interface is a subset of the normal GNU gettext
interface. We currently export these functions:
Mark and translate a string. E.g.: - \_()
printf(_("HEAD is now at %s"), hex); Mark and translate a string. E.g.:
- Q_() ```c
printf(_("HEAD is now at %s"), hex);
```
Mark and translate a plural string. E.g.: - Q\_()
printf(Q_("%d commit", "%d commits", number_of_commits)); Mark and translate a plural string. E.g.:
This is just a wrapper for the ngettext() function. ```c
printf(Q_("%d commit", "%d commits", number_of_commits));
```
- N_() This is just a wrapper for the ngettext() function.
A no-op pass-through macro for marking strings inside static - N\_()
initializations, e.g.:
static const char *reset_type_names[] = { A no-op pass-through macro for marking strings inside static
N_("mixed"), N_("soft"), N_("hard"), N_("merge"), N_("keep"), NULL initializations, e.g.:
};
And then, later: ```c
static const char *reset_type_names[] = {
N_("mixed"), N_("soft"), N_("hard"), N_("merge"), N_("keep"), NULL
};
```
die(_("%s reset is not allowed in a bare repository"), And then, later:
_(reset_type_names[reset_type]));
Here _() couldn't have statically determined what the translation ```c
string will be, but since it was already marked for translation die(_("%s reset is not allowed in a bare repository"),
with N_() the look-up in the message catalog will succeed. _(reset_type_names[reset_type]));
```
Shell: Here `_()` couldn't have statically determined what the translation
string will be, but since it was already marked for translation
- The Git gettext shell interface is just a wrapper for with `N_()` the look-up in the message catalog will succeed.
gettext.sh. Import it right after git-sh-setup like this:
. git-sh-setup
. git-sh-i18n
And then use the gettext or eval_gettext functions:
# For constant interface messages:
gettext "A message for the user"; echo
# To interpolate variables:
details="oh noes"
eval_gettext "An error occurred: \$details"; echo
In addition we have wrappers for messages that end with a trailing
newline. I.e. you could write the above as:
# For constant interface messages:
gettextln "A message for the user"
# To interpolate variables:
details="oh noes"
eval_gettextln "An error occurred: \$details"
More documentation about the interface is available in the GNU info
page: `info '(gettext)sh'`. Looking at git-am.sh (the first shell
command to be translated) for examples is also useful:
git log --reverse -p --grep=i18n git-am.sh
Perl:
- The Git::I18N module provides a limited subset of the
Locale::Messages functionality, e.g.:
use Git::I18N;
print __("Welcome to Git!\n");
printf __("The following error occurred: %s\n"), $error;
Run `perldoc perl/Git/I18N.pm` for more info.
Testing marked strings ### Shell
----------------------
Git's tests are run under LANG=C LC_ALL=C. So the tests do not need be The Git gettext shell interface is just a wrapper for
gettext.sh. Import it right after git-sh-setup like this:
```shell
. git-sh-setup
. git-sh-i18n
```
And then use the `gettext` or `eval_gettext` functions:
```shell
# For constant interface messages:
gettext "A message for the user"; echo
# To interpolate variables:
details="oh noes"
eval_gettext "An error occurred: \$details"; echo
```
In addition we have wrappers for messages that end with a trailing
newline. I.e. you could write the above as:
```shell
# For constant interface messages:
gettextln "A message for the user"
# To interpolate variables:
details="oh noes"
eval_gettextln "An error occurred: \$details"
```
More documentation about the interface is available in the GNU info
page: `info '(gettext)sh'`. Looking at git-am.sh (the first shell
command to be translated) for examples is also useful:
```shell
git log --reverse -p --grep=i18n git-am.sh
```
### Perl
The Git::I18N module provides a limited subset of the
Locale::Messages functionality, e.g.:
```perl
use Git::I18N;
print __("Welcome to Git!\n");
printf __("The following error occurred: %s\n"), $error;
```
Run `perldoc perl/Git/I18N.pm` for more info.
## Testing marked strings
Git's tests are run under `LANG=C LC_ALL=C`. So the tests do not need be
changed to account for translations as they're added. changed to account for translations as they're added.
PO helper ## PO helper
---------
To make the maintenance of XX.po easier, the l10n coordinator and l10n To make the maintenance of "XX.po" easier, the l10n coordinator and l10n
team leaders can use a helper program named "git-po-helper". It is a team leaders can use a helper program named "git-po-helper". It is a
wrapper to gettext suite, specifically written for the purpose of Git wrapper to gettext suite, specifically written for the purpose of Git
l10n workflow. l10n workflow.
@ -337,64 +368,84 @@ To build and install the helper program from source, see
Usage for git-po-helper: Usage for git-po-helper:
- To start a new language translation: - To start a new language translation:
git-po-helper init XX.po ```shell
git-po-helper init XX.po
```
- To update your XX.po file: - To update your "XX.po" file:
git-po-helper update XX.po ```shell
git-po-helper update XX.po
```
- To check commit log and syntax of XX.po: - To check commit log and syntax of "XX.po":
git-po-helper check-po XX.po ```shell
git-po-helper check-commits git-po-helper check-po XX.po
git-po-helper check-commits
```
Run "git-po-helper" without arguments to show usage. Run "git-po-helper" without arguments to show usage.
Conventions ## Conventions
-----------
There are some conventions that l10n contributors must follow: There are some conventions that l10n contributors must follow:
1. The subject of each l10n commit should be prefixed with "l10n: ". - The subject of each l10n commit should be prefixed with "l10n: ".
2. Do not use non-ASCII characters in the subject of a commit.
3. The length of commit subject (first line of the commit log) should
be less than 50 characters, and the length of other lines of the
commit log should be no more than 72 characters.
4. Add "Signed-off-by" trailer to your commit log, like other commits
in Git. You can automatically add the trailer by committing with
the following command:
git commit -s - Do not use non-ASCII characters in the subject of a commit.
5. Check syntax with "msgfmt" or the following command before creating - The length of commit subject (first line of the commit log) should
your commit: be less than 50 characters, and the length of other lines of the
commit log should be no more than 72 characters.
git-po-helper check-po <XX.po> - Add "Signed-off-by" trailer to your commit log, like other commits
in Git. You can automatically add the trailer by committing with
the following command:
```shell
git commit -s
```
- Check syntax with "msgfmt" or the following command before creating
your commit:
```shell
git-po-helper check-po <XX.po>
```
- Squash trivial commits to make history clear.
- DO NOT edit files outside "po/" directory.
- Other subsystems ("git-gui", "gitk", and Git itself) have their
own workflow. See [Documentation/SubmittingPatches][] for
instructions on how to contribute patches to these subsystems.
6. Squash trivial commits to make history clear.
7. DO NOT edit files outside "po/" directory.
8. Other subsystems ("git-gui", "gitk", and Git itself) have their
own workflow. See [Documentation/SubmittingPatches][] for
instructions on how to contribute patches to these subsystems.
To contribute for a new l10n language, contributor should follow To contribute for a new l10n language, contributor should follow
additional conventions: additional conventions:
1. Initialize proper filename of the "XX.po" file conforming to - Initialize proper filename of the "XX.po" file conforming to
iso-639 and iso-3166. iso-639 and iso-3166.
2. Must complete a minimal translation based on the "po-core/core.pot"
template. Using the following command to initialize the minimal
"po-core/XX.po" file:
git-po-helper init --core <your-language> - Must complete a minimal translation based on the "po-core/core.pot"
template. Using the following command to initialize the minimal
"po-core/XX.po" file:
3. Add a new entry in the "po/TEAMS" file with proper format, and check ```shell
the syntax of "po/TEAMS" by running the following command: git-po-helper init --core <your-language>
```
git-po-helper team --check - Add a new entry in the "po/TEAMS" file with proper format, and check
the syntax of "po/TEAMS" by running the following command:
```shell
git-po-helper team --check
```
[git-po-helper/README]: https://github.com/git-l10n/git-po-helper#readme [git-po-helper/README]: https://github.com/git-l10n/git-po-helper#readme