diff options
Diffstat (limited to 'git-gui/po/README')
| -rw-r--r-- | git-gui/po/README | 251 |
1 files changed, 251 insertions, 0 deletions
diff --git a/git-gui/po/README b/git-gui/po/README new file mode 100644 index 0000000000..0f5837d48e --- /dev/null +++ b/git-gui/po/README @@ -0,0 +1,251 @@ +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. |