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