| 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: |
| |
| 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. |
| 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. |