git-gui/po/README

   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 git://repo.or.cz/git-gui.git
  25         $ cd git-gui.git
  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 Copy po/git-gui.pot file to po/af.po (replace "af" with the code for
  51 your language).  Edit the first several lines to match existing *.po
  52 files to make it clear this is a translation table for git-gui project,
  53 and you are the primary translator.  The result of your editing would
  54 look something like this:
  55
  56     # Translation of git-gui to Afrikaans
  57     # Copyright (C) 2007 Shawn Pearce
  58     # This file is distributed under the same license as the git-gui package.
  59     # YOUR NAME <YOUR@E-MAIL.ADDRESS>, 2007.
  60     #
  61     #, fuzzy
  62     msgid ""
  63     msgstr ""
  64     "Project-Id-Version: git-gui\n"
  65     "Report-Msgid-Bugs-To: \n"
  66     "POT-Creation-Date: 2007-07-24 22:19+0300\n"
  67     "PO-Revision-Date: 2007-07-25 18:00+0900\n"
  68     "Last-Translator: YOUR NAME <YOUR@E-MAIL.ADDRESS>\n"
  69     "Language-Team: Afrikaans\n"
  70     "MIME-Version: 1.0\n"
  71     "Content-Type: text/plain; charset=UTF-8\n"
  72     "Content-Transfer-Encoding: 8bit\n"
  73
  74 You will find many pairs of a "msgid" line followed by a "msgstr" line.
  75 These pairs define how messages in git-gui application are translated to
  76 your language.  Your primarily job is to fill in the empty double quote
  77 pairs on msgstr lines with the translation of the strings on their
  78 matching msgid lines.  A few tips:
  79
  80  - Control characters, such as newlines, are written in backslash
  81    sequence similar to string literals in the C programming language.
  82    When the string given on a msgid line has such a backslash sequence,
  83    you would typically want to have corresponding ones in the string on
  84    your msgstr line.
  85
  86  - Some messages contain an optional context indicator at the end,
  87    for example "@@noun" or "@@verb".  This indicator allows the
  88    software to select the correct translation depending upon the use.
  89    The indicator is not actually part of the message and will not
  90    be shown to the end-user.
  91
  92    If your language does not require a different translation you
  93    will still need to translate both messages.
  94
  95  - Often the messages being translated are format strings given to
  96    "printf()"-like functions.  Make sure "%s", "%d", and "%%" in your
  97    translated messages match the original.
  98
  99    When you have to change the order of words, you can add "<number>$"
 100    between '%' and the conversion ('s', 'd', etc.) to say "<number>-th
 101    parameter to the format string is used at this point".  For example,
 102    if the original message is like this:
 103
 104         "Length is %d, Weight is %d"
 105
 106    and if for whatever reason your translation needs to say weight first
 107    and then length, you can say something like:
 108
 109         "WEIGHT IS %2$d, LENGTH IS %1$d"
 110
 111    A format specification with a '*' (asterisk) refers to *two* arguments
 112    instead of one, hence the succeeding argument number is two higher
 113    instead of one. So, a message like this
 114
 115         "%s ... %*i of %*i %s (%3i%%)"
 116
 117    is equivalent to
 118
 119         "%1$s ... %2$*i of %4$*i %6$s (%7$3i%%)"
 120
 121  - A long message can be split across multiple lines by ending the
 122    string with a double quote, and starting another string on the next
 123    line with another double quote.  They will be concatenated in the
 124    result.  For example:
 125
 126    #: lib/remote_branch_delete.tcl:189
 127    #, tcl-format
 128    msgid ""
 129    "One or more of the merge tests failed because you have not fetched the "
 130    "necessary commits.  Try fetching from %s first."
 131    msgstr ""
 132    "HERE YOU WILL WRITE YOUR TRANSLATION OF THE ABOVE LONG "
 133    "MESSAGE IN YOUR LANGUAGE."
 134
 135 You can test your translation by running "make install", which would
 136 create po/af.msg file and installs the result, and then running the
 137 resulting git-gui under your locale:
 138
 139         $ make install
 140         $ LANG=af git-gui
 141
 142 There is a trick to test your translation without first installing:
 143
 144         $ make
 145         $ LANG=af ./git-gui.sh
 146
 147 When you are satisfied with your translation, commit your changes then submit
 148 your patch series to the maintainer and the Git mailing list:
 149
 150         $ edit po/af.po
 151         ... be sure to update Last-Translator: and
 152         ... PO-Revision-Date: lines.
 153         $ git add po/af.po
 154         $ git commit -s -m 'git-gui: added Afrikaans translation.'
 155         $ git send-email --to 'git@vger.kernel.org' \
 156            --cc 'Pat Thoyts <patthoyts@users.sourceforge.net>' \
 157            --subject 'git-gui: Afrikaans translation' \
 158            master..
 159
 160
 161 3. Updating your translation.
 162
 163 There may already be a translation for your language, and you may want
 164 to contribute an update.  This may be because you would want to improve
 165 the translation of existing messages, or because the git-gui software
 166 itself was updated and there are new messages that need translation.
 167
 168 In any case, make sure you are up to date before starting your work:
 169
 170         $ git checkout master
 171         $ git pull
 172
 173 In the former case, you will edit po/af.po (again, replace "af" with
 174 your language code), and after testing and updating the Last-Translator:
 175 and PO-Revision-Date: lines, "add/commit/push" as in the previous
 176 section.
 177
 178 By comparing "POT-Creation-Date:" line in po/git-gui.pot file and
 179 po/af.po file, you can tell if there are new messages that need to be
 180 translated.  You would need the GNU gettext package to perform this
 181 step.
 182
 183         $ msgmerge -U po/af.po po/git-gui.pot
 184
 185 This updates po/af.po (again, replace "af" with your language
 186 code) so that it contains msgid lines (i.e. the original) that
 187 your translation did not have before.  There are a few things to
 188 watch out for:
 189
 190  - The original text in English of an older message you already
 191    translated might have been changed.  You will notice a comment line
 192    that begins with "#, fuzzy" in front of such a message.  msgmerge
 193    tool made its best effort to match your old translation with the
 194    message from the updated software, but you may find cases that it
 195    matched your old translated message to a new msgid and the pairing
 196    does not make any sense -- you would need to fix them, and then
 197    remove the "#, fuzzy" line from the message (your fixed translation
 198    of the message will not be used before you remove the marker).
 199
 200  - New messages added to the software will have msgstr lines with empty
 201    strings.  You would need to translate them.
 202
 203 The po/git-gui.pot file is updated by the internationalization
 204 coordinator from time to time.  You _could_ update it yourself, but
 205 translators are discouraged from doing so because we would want all
 206 language teams to be working off of the same version of git-gui.pot.
 207
 208 ****************************************************************
 209
 210 This section is a note to the internationalization coordinator, and
 211 translators do not have to worry about it too much.
 212
 213 The message template file po/git-gui.pot needs to be kept up to date
 214 relative to the software the translations apply to, and it is the
 215 responsibility of the internationalization coordinator.
 216
 217 When updating po/git-gui.pot file, however, _never_ run "msgmerge -U
 218 po/xx.po" for individual language translations, unless you are absolutely
 219 sure that there is no outstanding work on translation for language xx.
 220 Doing so will create unnecessary merge conflicts and force needless
 221 re-translation on translators.  The translator however may not have access
 222 to the msgmerge tool, in which case the coordinator may run it for the
 223 translator as a service.
 224
 225 But mistakes do happen.  Suppose a translation was based on an older
 226 version X, the POT file was updated at version Y and then msgmerge was run
 227 at version Z for the language, and the translator sent in a patch based on
 228 version X:
 229
 230          ? translated
 231         /
 232     ---X---Y---Z (master)
 233
 234 The coordinator could recover from such a mistake by first applying the
 235 patch to X, replace the translated file in Z, and then running msgmerge
 236 again based on the updated POT file and commit the result.  The sequence
 237 would look like this:
 238
 239     $ git checkout X
 240     $ git am -s xx.patch
 241     $ git checkout master
 242     $ git checkout HEAD@{1} po/xx.po
 243     $ msgmerge -U po/xx.po po/git-gui.pot
 244     $ git commit -c HEAD@{1} po/xx.po
 245
 246 State in the message that the translated messages are based on a slightly
 247 older version, and msgmerge was run to incorporate changes to message
 248 templates from the updated POT file.  The result needs to be further
 249 translated, but at least the messages that were updated by the patch that
 250 were not changed by the POT update will survive the process and do not
 251 need to be re-translated.