X-Git-Url: https://git.tokkee.org/?a=blobdiff_plain;f=po%2FREADME;h=10b0ad2ce851b64141e635abbe794498032be6ba;hb=200888ef3bbc150cc20b99e0aa039c751c00e07a;hp=595bbf5dee97e34eeab46b742225fce2f95ab052;hpb=fbbdaa5f425417e7fee83f543b1d03806f034cab;p=git.git diff --git a/po/README b/po/README index 595bbf5de..10b0ad2ce 100644 --- a/po/README +++ b/po/README @@ -1,252 +1,229 @@ -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 internationalization project -repository, so that you can work on it: - - $ git clone mob@repo.or.cz:/srv/git/git-gui/git-gui-i18n.git/ - $ cd git-gui-i18n - $ git checkout --track -b mob origin/mob - $ git config remote.origin.push mob - -The "git checkout" command creates a 'mob' branch from upstream's -corresponding branch and makes it your current branch. You will be -working on this branch. - -The "git config" command records in your repository configuration file -that you would push "mob" branch to the upstream when you say "git -push". - - -2. Starting a new language. - -In the git-gui-i18n directory is a po/ subdirectory. It has a -handful 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 , 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 \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 "$" - between '%' and the conversion ('s', 'd', etc.) to say "-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, and -push it back to the 'mob' branch: - - $ edit po/af.po - ... be sure to update Last-Translator: and - ... PO-Revision-Date: lines. - $ git add po/af.po - $ git commit -m 'Started Afrikaans translation.' - $ git push - - -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 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: +Core GIT Translations +===================== - - 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. +This directory holds the translations for the core of Git. This +document describes how to add to and maintain these translations, and +how to mark source strings for translation. -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. -**************************************************************** +Generating a .pot file +---------------------- -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. +The po/git.pot file contains a message catalog extracted from Git's +sources. You need to generate it to add new translations with +msginit(1), or update existing ones with msgmerge(1). + +Since the file can be automatically generated it's not checked into +git.git. To generate it do, at the top-level: + + make pot + + +Initializing a .po file +----------------------- + +To add a new translation first generate git.pot (see above) and then +in the po/ directory do: + + msginit --locale=XX + +Where XX is your locale, e.g. "is", "de" or "pt_BR". + +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 + +# This file is distributed under the same license as the Git package. + # Ævar Arnfjörð Bjarmason , 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 + + +Updating a .po file +------------------- + +If there's an existing *.po file for your language but you need to +update the translation you first need to generate git.pot (see above) +and then in the po/ directory do: + + msgmerge --add-location --backup=off -U XX.po git.pot + +Where XX.po is the file you want to update. + +Testing your changes +-------------------- + +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 +------------------------------- + +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 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 occured: \$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 occured: \$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 occured: %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 can be compiled with gettext poison +support, at the top-level: + + make GETTEXT_POISON=YesPlease + +That'll give you a git which emits gibberish on every call to +gettext. It's obviously not meant to be installed, but you should run +the test suite with it: + + cd t && 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.