@matheusbsbs / matheus-bagliano / commits / 2631a81b90
Fork 0

git-gui po/README: Guide to translators

This short note is to help a translation contributor to help us localizing git-gui message files by covering the basics. Signed-off-by: Junio C Hamano <gitster@pobox.com>

Junio C Hamano committed Jul 27, 2007 at 16:05 UTC 2631a81b901fc7baa274f98530a0d9cc05cecd17
1 file changed +205
po/README new
+205
@@ -0,0 +1,205 @@
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.