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 https://github.com/j6t/git-gui $ cd git-gui $ 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: https://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. Generate po/git-gui.pot using $ make po/git-gui.pot 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 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 'Johannes Sixt ' \ --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 $ make ALL_POFILES=po/af.po update-po 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. After testing and updating the Last-Translator: and PO-Revision-Date: lines, "add/commit/push" as in the previous section.