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 internationalization project
  22 repository, 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
  29 The "git checkout" command creates a 'mob' branch from upstream's
  30 corresponding branch and makes it your current branch.  You will be
  31 working on this branch.
  32
  33 The "git config" command records in your repository configuration file
  34 that you would push "mob" branch to the upstream when you say "git
  35 push".
  36
  37
  38 2. Starting a new language.
  39
  40 In the git-gui-i18n directory is a po/ subdirectory.  It has a
  41 handful files whose names end with ".po".  Is there a file that has
  42 messages in your language?
  43
  44 If you do not know what your language should be named, you need to find
  45 it.  This currently follows ISO 639-1 two letter codes:
  46
  47         http://www.loc.gov/standards/iso639-2/php/code_list.php
  48
  49 For example, if you are preparing a translation for Afrikaans, the
  50 language code is "af".  If there already is a translation for your
  51 language, you do not have to perform any step in this section, but keep
  52 reading, because we are covering the basics.
  53
  54 If you did not find your language, you would need to start one yourself.
  55 Copy po/git-gui.pot file to po/af.po (replace "af" with the code for
  56 your language).  Edit the first several lines to match existing *.po
  57 files to make it clear this is a translation table for git-gui project,
  58 and you are the primary translator.  The result of your editing would
  59 look 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
  79 You will find many pairs of a "msgid" line followed by a "msgstr" line.
  80 These pairs define how messages in git-gui application are translated to
  81 your language.  Your primarily job is to fill in the empty double quote
  82 pairs on msgstr lines with the translation of the strings on their
  83 matching 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
 126 You can test your translation by running "make install", which would
 127 create po/af.msg file and installs the result, and then running the
 128 resulting git-gui under your locale:
 129
 130         $ make install
 131         $ LANG=af git-gui
 132
 133 There is a trick to test your translation without first installing, if
 134 you prefer.  First, create this symbolic link in the source tree:
 135
 136         $ ln -s ../po lib/msgs
 137
 138 After setting up such a symbolic link, you can:
 139
 140         $ make
 141         $ LANG=af ./git-gui.sh
 142
 143 When you are satisfied with your translation, commit your changes, and
 144 push it back to the 'mob' branch:
 145
 146         $ edit po/af.po
 147         ... be sure to update Last-Translator: and
 148         ... PO-Revision-Date: lines.
 149         $ git add po/af.po
 150         $ git commit -m 'Started Afrikaans translation.'
 151         $ git push
 152
 153
 154 3. Updating your translation.
 155
 156 There may already be a translation for your language, and you may want
 157 to contribute an update.  This may be because you would want to improve
 158 the translation of existing messages, or because the git-gui software
 159 itself was updated and there are new messages that need translation.
 160
 161 In any case, make sure you are up-to-date before starting your work:
 162
 163         $ git pull
 164
 165 In the former case, you will edit po/af.po (again, replace "af" with
 166 your language code), and after testing and updating the Last-Translator:
 167 and PO-Revision-Date: lines, "add/commit/push" as in the previous
 168 section.
 169
 170 By comparing "POT-Creation-Date:" line in po/git-gui.pot file and
 171 po/af.po file, you can tell if there are new messages that need to be
 172 translated.  You would need the GNU gettext package to perform this
 173 step.
 174
 175         $ msgmerge -U po/af.po po/git-gui.pot
 176
 177 [NEEDSWORK: who is responsible for updating po/git-gui.pot file by
 178 running xgettext?  IIRC, Christian recommended against running it
 179 nilly-willy because it can become a source of unnecessary merge
 180 conflicts.  Perhaps we should mention something like "
 181
 182 The po/git-gui.pot file is updated by the internationalization
 183 coordinator from time to time.  You _could_ update it yourself, but
 184 translators are discouraged from doing so because we would want all
 185 language teams to be working off of the same version of git-gui.pot.
 186
 187 " here?]
 188
 189 This updates po/af.po (again, replace "af" with your language
 190 code) so that it contains msgid lines (i.e. the original) that
 191 your translation did not have before.  There are a few things to
 192 watch out for:
 193
 194  - The original text in English of an older message you already
 195    translated might have been changed.  You will notice a comment line
 196    that begins with "#, fuzzy" in front of such a message.  msgmerge
 197    tool made its best effort to match your old translation with the
 198    message from the updated software, but you may find cases that it
 199    matched your old translated message to a new msgid and the pairing
 200    does not make any sense -- you would need to fix them, and then
 201    remove the "#, fuzzy" line from the message (your fixed translation
 202    of the message will not be used before you remove the marker).
 203
 204  - New messages added to the software will have msgstr lines with empty
 205    strings.  You would need to translate them.