-Localizing git-gui for your language
-====================================
-
-This short note is to help you, who reads and writes English and your
-own language, help us getting git-gui localized for more languages. It
-does not try to be a comprehensive manual of GNU gettext, which is the
-i18n framework we use, but tries to help you get started by covering the
-basics and how it is used in this project.
-
-1. Getting started.
-
-You would first need to have a working "git". Your distribution may
-have it as "git-core" package (do not get "GNU Interactive Tools" --
-that is a different "git"). You would also need GNU gettext toolchain
-to test the resulting translation out. Although you can work on message
-translation files with a regular text editor, it is a good idea to have
-specialized so-called "po file editors" (e.g. emacs po-mode, KBabel,
-poedit, GTranslator --- any of them would work well). Please install
-them.
-
-You would then need to clone the git-gui project repository and create
-a feature branch to begin working:
-
- $ git clone git://repo.or.cz/git-gui.git
- $ cd git-gui.git
- $ git checkout -b my-translation
-
-The "git checkout" command creates a new branch to keep your work
-isolated and to make it simple to post your patch series when
-completed. You will be working on this branch.
-
-
-2. Starting a new language.
-
-In the git-gui directory is a po/ subdirectory. It has a handful of
-files whose names end with ".po". Is there a file that has messages
-in your language?
-
-If you do not know what your language should be named, you need to find
-it. This currently follows ISO 639-1 two letter codes:
-
- http://www.loc.gov/standards/iso639-2/php/code_list.php
-
-For example, if you are preparing a translation for Afrikaans, the
-language code is "af". If there already is a translation for your
-language, you do not have to perform any step in this section, but keep
-reading, because we are covering the basics.
-
-If you did not find your language, you would need to start one yourself.
-Copy po/git-gui.pot file to po/af.po (replace "af" with the code for
-your language). Edit the first several lines to match existing *.po
-files to make it clear this is a translation table for git-gui project,
-and you are the primary translator. The result of your editing would
-look something like this:
-
- # Translation of git-gui to Afrikaans
- # Copyright (C) 2007 Shawn Pearce
- # This file is distributed under the same license as the git-gui package.
- # YOUR NAME <YOUR@E-MAIL.ADDRESS>, 2007.
- #
- #, fuzzy
- msgid ""
- msgstr ""
- "Project-Id-Version: git-gui\n"
- "Report-Msgid-Bugs-To: \n"
- "POT-Creation-Date: 2007-07-24 22:19+0300\n"
- "PO-Revision-Date: 2007-07-25 18:00+0900\n"
- "Last-Translator: YOUR NAME <YOUR@E-MAIL.ADDRESS>\n"
- "Language-Team: Afrikaans\n"
- "MIME-Version: 1.0\n"
- "Content-Type: text/plain; charset=UTF-8\n"
- "Content-Transfer-Encoding: 8bit\n"
-
-You will find many pairs of a "msgid" line followed by a "msgstr" line.
-These pairs define how messages in git-gui application are translated to
-your language. Your primarily job is to fill in the empty double quote
-pairs on msgstr lines with the translation of the strings on their
-matching msgid lines. A few tips:
-
- - Control characters, such as newlines, are written in backslash
- sequence similar to string literals in the C programming language.
- When the string given on a msgid line has such a backslash sequence,
- 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>$"
- 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:
-
- "Length is %d, Weight is %d"
-
- 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"
-
- 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
-
- "%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
- line with another double quote. They will be concatenated in the
- result. For example:
-
- #: lib/remote_branch_delete.tcl:189
- #, tcl-format
- msgid ""
- "One or more of the merge tests failed because you have not fetched the "
- "necessary commits. Try fetching from %s first."
- msgstr ""
- "HERE YOU WILL WRITE YOUR TRANSLATION OF THE ABOVE LONG "
- "MESSAGE IN YOUR LANGUAGE."
-
-You can test your translation by running "make install", which would
-create po/af.msg file and installs the result, and then running the
-resulting git-gui under your locale:
-
- $ make install
- $ LANG=af git-gui
-
-There is a trick to test your translation without first installing:
-
- $ make
- $ LANG=af ./git-gui.sh
-
-When you are satisfied with your translation, commit your changes then submit
-your patch series to the maintainer and the Git mailing list:
-
- $ edit po/af.po
- ... be sure to update Last-Translator: and
- ... PO-Revision-Date: lines.
- $ git add po/af.po
- $ git commit -s -m 'git-gui: added Afrikaans translation.'
- $ git send-email --to 'git@vger.kernel.org' \
- --cc 'Pat Thoyts <patthoyts@users.sourceforge.net>' \
- --subject 'git-gui: Afrikaans translation' \
- master..
-
-
-3. Updating your translation.
-
-There may already be a translation for your language, and you may want
-to contribute an update. This may be because you would want to improve
-the translation of existing messages, or because the git-gui software
-itself was updated and there are new messages that need translation.
-
-In any case, make sure you are up to date before starting your work:
-
- $ git checkout master
- $ git pull
-
-In the former case, you will edit po/af.po (again, replace "af" with
-your language code), and after testing and updating the Last-Translator:
-and PO-Revision-Date: lines, "add/commit/push" as in the previous
-section.
-
-By comparing "POT-Creation-Date:" line in po/git-gui.pot file and
-po/af.po file, you can tell if there are new messages that need to be
-translated. You would need the GNU gettext package to perform this
-step.
-
- $ msgmerge -U po/af.po po/git-gui.pot
-
-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
-watch out for:
-
- - The original text in English of an older message you already
- translated might have been changed. You will notice a comment line
- that begins with "#, fuzzy" in front of such a message. msgmerge
- tool made its best effort to match your old translation with the
- message from the updated software, but you may find cases that it
- matched your old translated message to a new msgid and the pairing
- does not make any sense -- you would need to fix them, and then
- remove the "#, fuzzy" line from the message (your fixed translation
- of the message will not be used before you remove the marker).
-
- - 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.
+Core GIT Translations
+=====================
+
+This directory holds the translations for the core of Git. This document
+describes how you can contribute to the effort of enhancing the language
+coverage and maintaining the translation.
+
+The localization (l10n) coordinator, Jiang Xin <worldhello.net@gmail.com>,
+coordinates our localization effort in the l10 coordinator repository:
+
+ https://github.com/git-l10n/git-po/
+
+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.
+
+
+Contributing to an existing translation
+---------------------------------------
+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
+exists. Fork the dedicated repository and start to work if it exists.
+
+Sometime, contributors may find that the translations of their Git
+distributions are quite different with the translations of the
+corresponding version from Git official. This is because some Git
+distributions (such as from Ubuntu, etc.) have their own l10n workflow.
+For this case, wrong translations should be reported and fixed through
+their workflows.
+
+
+Creating a new language translation
+-----------------------------------
+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
+(described later), and ask the l10n coordinator to pull your work.
+
+If there are multiple contributors for the same language, please first
+coordinate among yourselves and nominate the team leader for your
+language, so that the l10n coordinator only needs to interact with one
+person per language.
+
+
+Translation Process Flow
+------------------------
+The overall data-flow looks like this:
+
+ +-------------------+ +------------------+
+ | Git source code | ---(1)---> | L10n coordinator |
+ | repository | <---(4)--- | repository |
+ +-------------------+ +------------------+
+ | ^
+ (2) (3)
+ V |
+ +------------------+
+ | Language Team XX |
+ +------------------+
+
+ * Translatable strings are marked in the source file.
+ * L10n coordinator pulls from the source (1)
+ * L10n coordinator updates the message template po/git.pot
+ * Language team pulls from L10n coordinator (2)
+ * Language team updates the message file po/XX.po
+ * L10n coordinator pulls from Language team (3)
+ * L10n coordinator asks the result to be pulled (4).
+
+
+Maintaining the po/git.pot file
+-------------------------------
+
+(This is done by the l10n coordinator).
+
+The po/git.pot file contains a message catalog extracted from Git's
+sources. The l10n coordinator maintains it by adding new translations with
+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
+expected to pull from the main git repository at strategic point in
+history (e.g. when a major release and release candidates are tagged),
+and then run "make pot" at the top-level directory.
+
+Language contributors use this file to prepare translations for their
+language, but they are not expected to modify it.
+
+
+Initializing a XX.po file
+-------------------------
+
+(This is done by the language teams).
+
+If your language XX does not have translated message file po/XX.po yet,
+you add a translation for the first time by running:
+
+ msginit --locale=XX
+
+in the po/ directory, where XX is the locale, e.g. "de", "is", "pt_BR",
+"zh_CN", etc.
+
+Then edit the automatically generated copyright info in your new XX.po
+to be correct, e.g. for Icelandic:
+
+ @@ -1,6 +1,6 @@
+ -# Icelandic translations for PACKAGE package.
+ -# Copyright (C) 2010 THE PACKAGE'S COPYRIGHT HOLDER
+ -# This file is distributed under the same license as the PACKAGE package.
+ +# Icelandic translations for Git.
+ +# Copyright (C) 2010 Ævar Arnfjörð Bjarmason <avarab@gmail.com>
+ +# 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
+just "Git":
+
+ perl -pi -e 's/(?<="Project-Id-Version: )PACKAGE VERSION/Git/' XX.po
+
+Once you are done testing the translation (see below), commit the result
+and ask the l10n coordinator to pull from you.
+
+
+Updating a XX.po file
+---------------------
+
+(This is done by the language teams).
+
+If you are replacing translation strings in an existing XX.po file to
+improve the translation, just edit the file.
+
+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
+pull from the l10n coordinator (see the beginning of this document for its
+URL), and then update the existing translation by running:
+
+ msgmerge --add-location --backup=off -U XX.po git.pot
+
+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
+and ask the l10n coordinator to pull from you.
+
+
+Testing your changes
+--------------------
+
+(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:
+
+ make
+
+On systems with GNU gettext (i.e. not Solaris) this will compile your
+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
+-------------------------------
+
+(This is done by the core developers).
+
+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"), action_name(opts));
+
+We provide wrappers for C, Shell and Perl programs. Here's how they're
+used:
+
+C:
+
+ - Include builtin.h at the top, it'll pull in gettext.h, which
+ 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);
+
+ - Q_()
+
+ Mark and translate a plural string. E.g.:
+
+ printf(Q_("%d commit", "%d commits", number_of_commits));
+
+ This is just a wrapper for the ngettext() function.
+
+ - N_()
+
+ A no-op pass-through macro for marking strings inside static
+ initializations, e.g.:
+
+ static const char *reset_type_names[] = {
+ N_("mixed"), N_("soft"), N_("hard"), N_("merge"), N_("keep"), NULL
+ };
+
+ And then, later:
+
+ die(_("%s reset is not allowed in a bare repository"),
+ _(reset_type_names[reset_type]));
+
+ Here _() couldn't have statically determined what the translation
+ string will be, but since it was already marked for translation
+ with N_() the look-up in the message catalog will succeed.
+
+Shell:
+
+ - The Git gettext shell interface is just a wrapper for
+ 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
+----------------------
+
+Even if you've correctly marked porcelain strings for translation
+something in the test suite might still depend on the US English
+version of the strings, e.g. to grep some error message or other
+output.
+
+To smoke out issues like these, Git tested with a translation mode that
+emits gibberish on every call to gettext. To use it run the test suite
+with it, e.g.:
+
+ cd t && GIT_TEST_GETTEXT_POISON=true prove -j 9 ./t[0-9]*.sh
+
+If tests break with it you should inspect them manually and see if
+what you're translating is sane, i.e. that you're not translating
+plumbing output.
+
+If not you should replace calls to grep with test_i18ngrep, or
+test_cmp calls with test_i18ncmp. If that's not enough you can skip
+the whole test by making it depend on the C_LOCALE_OUTPUT
+prerequisite. See existing test files with this prerequisite for
+examples.
projects / thirdparty / git.git / blobdiff