1Localizing git-gui for your language 2==================================== 3 4This short note is to help you, who reads and writes English and your 5own language, help us getting git-gui localized for more languages. It 6does not try to be a comprehensive manual of GNU gettext, which is the 7i18n framework we use, but tries to help you get started by covering the 8basics and how it is used in this project. 9 101. Getting started. 11 12You would first need to have a working "git". Your distribution may 13have it as "git-core" package (do not get "GNU Interactive Tools" -- 14that is a different "git"). You would also need GNU gettext toolchain 15to test the resulting translation out. Although you can work on message 16translation files with a regular text editor, it is a good idea to have 17specialized so-called "po file editors" (e.g. emacs po-mode, KBabel, 18poedit, GTranslator --- any of them would work well). Please install 19them. 20 21You would then need to clone the git-gui internationalization project 22repository, so that you can work on it: 23 24 $ git clone mob@repo.or.cz:/srv/git/git-gui/git-gui-i18n.git/ 25 $ cd git-gui-i18n 26 $ git checkout --track -b mob origin/mob 27 $ git config remote.origin.push mob 28 29The "git checkout" command creates a 'mob' branch from upstream's 30corresponding branch and makes it your current branch. You will be 31working on this branch. 32 33The "git config" command records in your repository configuration file 34that you would push "mob" branch to the upstream when you say "git 35push". 36 37 382. Starting a new language. 39 40In the git-gui-i18n directory is a po/ subdirectory. It has a 41handful files whose names end with ".po". Is there a file that has 42messages in your language? 43 44If you do not know what your language should be named, you need to find 45it. This currently follows ISO 639-1 two letter codes: 46 47 http://www.loc.gov/standards/iso639-2/php/code_list.php 48 49For example, if you are preparing a translation for Afrikaans, the 50language code is "af". If there already is a translation for your 51language, you do not have to perform any step in this section, but keep 52reading, because we are covering the basics. 53 54If you did not find your language, you would need to start one yourself. 55Copy po/git-gui.pot file to po/af.po (replace "af" with the code for 56your language). Edit the first several lines to match existing *.po 57files to make it clear this is a translation table for git-gui project, 58and you are the primary translator. The result of your editing would 59look something like this: 60 61 # Translation of git-gui to Afrikaans 62 # Copyright (C) 2007 Shawn Pearce 63 # This file is distributed under the same license as the git-gui package. 64 # YOUR NAME <YOUR@E-MAIL.ADDRESS>, 2007. 65 # 66 #, fuzzy 67 msgid "" 68 msgstr "" 69 "Project-Id-Version: git-gui\n" 70 "Report-Msgid-Bugs-To: \n" 71 "POT-Creation-Date: 2007-07-24 22:19+0300\n" 72 "PO-Revision-Date: 2007-07-25 18:00+0900\n" 73 "Last-Translator: YOUR NAME <YOUR@E-MAIL.ADDRESS>\n" 74 "Language-Team: Afrikaans\n" 75 "MIME-Version: 1.0\n" 76 "Content-Type: text/plain; charset=UTF-8\n" 77 "Content-Transfer-Encoding: 8bit\n" 78 79You will find many pairs of a "msgid" line followed by a "msgstr" line. 80These pairs define how messages in git-gui application are translated to 81your language. Your primarily job is to fill in the empty double quote 82pairs on msgstr lines with the translation of the strings on their 83matching msgid lines. A few tips: 84 85 - Control characters, such as newlines, are written in backslash 86 sequence similar to string literals in the C programming language. 87 When the string given on a msgid line has such a backslash sequence, 88 you would typically want to have corresponding ones in the string on 89 your msgstr line. 90 91 - Often the messages being translated are format strings given to 92 "printf()"-like functions. Make sure "%s", "%d", and "%%" in your 93 translated messages match the original. 94 95 When you have to change the order of words, you can add "<number>\$" 96 between '%' and the conversion ('s', 'd', etc.) to say "<number>-th 97 parameter to the format string is used at this point". For example, 98 if the original message is like this: 99 100 "Length is %d, Weight is %d" 101 102 and if for whatever reason your translation needs to say weight first 103 and then length, you can say something like: 104 105 "WEIGHT IS %2\$d, LENGTH IS %1\$d" 106 107 The reason you need a backslash before dollar sign is because 108 this is a double quoted string in Tcl language, and without 109 it the letter introduces a variable interpolation, which you 110 do not want here. 111 112 - A long message can be split across multiple lines by ending the 113 string with a double quote, and starting another string on the next 114 line with another double quote. They will be concatenated in the 115 result. For example: 116 117 #: lib/remote_branch_delete.tcl:189 118 #, tcl-format 119 msgid "" 120 "One or more of the merge tests failed because you have not fetched the " 121 "necessary commits. Try fetching from %s first." 122 msgstr "" 123 "HERE YOU WILL WRITE YOUR TRANSLATION OF THE ABOVE LONG " 124 "MESSAGE IN YOUR LANGUAGE." 125 126You can test your translation by running "make install", which would 127create po/af.msg file and installs the result, and then running the 128resulting git-gui under your locale: 129 130 $ make install 131 $ LANG=af git-gui 132 133There is a trick to test your translation without first installing: 134 135 $ make 136 $ LANG=af ./git-gui.sh 137 138When you are satisfied with your translation, commit your changes, and 139push it back to the 'mob' branch: 140 141 $ edit po/af.po 142 ... be sure to update Last-Translator: and 143 ... PO-Revision-Date: lines. 144 $ git add po/af.po 145 $ git commit -m 'Started Afrikaans translation.' 146 $ git push 147 148 1493. Updating your translation. 150 151There may already be a translation for your language, and you may want 152to contribute an update. This may be because you would want to improve 153the translation of existing messages, or because the git-gui software 154itself was updated and there are new messages that need translation. 155 156In any case, make sure you are up-to-date before starting your work: 157 158 $ git pull 159 160In the former case, you will edit po/af.po (again, replace "af" with 161your language code), and after testing and updating the Last-Translator: 162and PO-Revision-Date: lines, "add/commit/push" as in the previous 163section. 164 165By comparing "POT-Creation-Date:" line in po/git-gui.pot file and 166po/af.po file, you can tell if there are new messages that need to be 167translated. You would need the GNU gettext package to perform this 168step. 169 170 $ msgmerge -U po/af.po po/git-gui.pot 171 172[NEEDSWORK: who is responsible for updating po/git-gui.pot file by 173running xgettext? IIRC, Christian recommended against running it 174nilly-willy because it can become a source of unnecessary merge 175conflicts. Perhaps we should mention something like " 176 177The po/git-gui.pot file is updated by the internationalization 178coordinator from time to time. You _could_ update it yourself, but 179translators are discouraged from doing so because we would want all 180language teams to be working off of the same version of git-gui.pot. 181 182" here?] 183 184This updates po/af.po (again, replace "af" with your language 185code) so that it contains msgid lines (i.e. the original) that 186your translation did not have before. There are a few things to 187watch out for: 188 189 - The original text in English of an older message you already 190 translated might have been changed. You will notice a comment line 191 that begins with "#, fuzzy" in front of such a message. msgmerge 192 tool made its best effort to match your old translation with the 193 message from the updated software, but you may find cases that it 194 matched your old translated message to a new msgid and the pairing 195 does not make any sense -- you would need to fix them, and then 196 remove the "#, fuzzy" line from the message (your fixed translation 197 of the message will not be used before you remove the marker). 198 199 - New messages added to the software will have msgstr lines with empty 200 strings. You would need to translate them.