| 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 <YOUR@E-MAIL.ADDRESS>, 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 <YOUR@E-MAIL.ADDRESS>\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 'git@vger.kernel.org' \ |
| 160 | --cc 'Johannes Sixt <j6t@kdbg.org>' \ |
| 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. |