git-gui/po/README - jrn/git - Git at Google

 Localizing git-gui for your language
 ====================================

 This short note is to help you, who reads and writes English and your
 own language, help us getting git-gui localized for more languages.  It
 does not try to be a comprehensive manual of GNU gettext, which is the
 i18n framework we use, but tries to help you get started by covering the
 basics and how it is used in this project.

 1. Getting started.

 You would first need to have a working "git".  Your distribution may
 have it as "git-core" package (do not get "GNU Interactive Tools" --
 that is a different "git").  You would also need GNU gettext toolchain
 to test the resulting translation out.  Although you can work on message
 translation files with a regular text editor, it is a good idea to have
 specialized so-called "po file editors" (e.g. emacs po-mode, KBabel,
 poedit, GTranslator --- any of them would work well).  Please install
 them.

 You would then need to clone the git-gui project repository and create
 a feature branch to begin working:

 	$ git clone git://repo.or.cz/git-gui.git
 	$ cd git-gui.git
 	$ git checkout -b my-translation

 The "git checkout" command creates a new branch to keep your work
 isolated and to make it simple to post your patch series when
 completed.  You will be working on this branch.


 2. Starting a new language.

 In the git-gui directory is a po/ subdirectory.  It has a handful of
 files whose names end with ".po".  Is there a file that has messages
 in your language?

 If you do not know what your language should be named, you need to find
 it.  This currently follows ISO 639-1 two letter codes:

 	http://www.loc.gov/standards/iso639-2/php/code_list.php

 For example, if you are preparing a translation for Afrikaans, the
 language code is "af".  If there already is a translation for your
 language, you do not have to perform any step in this section, but keep
 reading, because we are covering the basics.

 If you did not find your language, you would need to start one yourself.
 Copy po/git-gui.pot file to po/af.po (replace "af" with the code for
 your language).  Edit the first several lines to match existing *.po
 files to make it clear this is a translation table for git-gui project,
 and you are the primary translator.  The result of your editing would
 look something like this:

     # Translation of git-gui to Afrikaans
     # Copyright (C) 2007 Shawn Pearce
     # This file is distributed under the same license as the git-gui package.
     # YOUR NAME <YOUR@E-MAIL.ADDRESS>, 2007.
     #
     #, fuzzy
     msgid ""
     msgstr ""
     "Project-Id-Version: git-gui\n"
     "Report-Msgid-Bugs-To: \n"
     "POT-Creation-Date: 2007-07-24 22:19+0300\n"
     "PO-Revision-Date: 2007-07-25 18:00+0900\n"
     "Last-Translator: YOUR NAME <YOUR@E-MAIL.ADDRESS>\n"
     "Language-Team: Afrikaans\n"
     "MIME-Version: 1.0\n"
     "Content-Type: text/plain; charset=UTF-8\n"
     "Content-Transfer-Encoding: 8bit\n"

 You will find many pairs of a "msgid" line followed by a "msgstr" line.
 These pairs define how messages in git-gui application are translated to
 your language.  Your primarily job is to fill in the empty double quote
 pairs on msgstr lines with the translation of the strings on their
 matching msgid lines.  A few tips:

  - Control characters, such as newlines, are written in backslash
    sequence similar to string literals in the C programming language.
    When the string given on a msgid line has such a backslash sequence,
    you would typically want to have corresponding ones in the string on
    your msgstr line.

  - Some messages contain an optional context indicator at the end,
    for example "@@noun" or "@@verb".  This indicator allows the
    software to select the correct translation depending upon the use.
    The indicator is not actually part of the message and will not
    be shown to the end-user.

    If your language does not require a different translation you
    will still need to translate both messages.

  - Often the messages being translated are format strings given to
    "printf()"-like functions.  Make sure "%s", "%d", and "%%" in your
    translated messages match the original.

    When you have to change the order of words, you can add "<number>$"
    between '%' and the conversion ('s', 'd', etc.) to say "<number>-th
    parameter to the format string is used at this point".  For example,
    if the original message is like this:

 	"Length is %d, Weight is %d"

    and if for whatever reason your translation needs to say weight first
    and then length, you can say something like:

 	"WEIGHT IS %2$d, LENGTH IS %1$d"

    A format specification with a '*' (asterisk) refers to *two* arguments
    instead of one, hence the succeeding argument number is two higher
    instead of one. So, a message like this

 	"%s ... %*i of %*i %s (%3i%%)"

    is equivalent to

 	"%1$s ... %2$*i of %4$*i %6$s (%7$3i%%)"

  - A long message can be split across multiple lines by ending the
    string with a double quote, and starting another string on the next
    line with another double quote.  They will be concatenated in the
    result.  For example:

    #: lib/remote_branch_delete.tcl:189
    #, tcl-format
    msgid ""
    "One or more of the merge tests failed because you have not fetched the "
    "necessary commits.  Try fetching from %s first."
    msgstr ""
    "HERE YOU WILL WRITE YOUR TRANSLATION OF THE ABOVE LONG "
    "MESSAGE IN YOUR LANGUAGE."

 You can test your translation by running "make install", which would
 create po/af.msg file and installs the result, and then running the
 resulting git-gui under your locale:

 	$ make install
 	$ LANG=af git-gui

 There is a trick to test your translation without first installing:

 	$ make
 	$ LANG=af ./git-gui.sh

 When you are satisfied with your translation, commit your changes then submit
 your patch series to the maintainer and the Git mailing list:

 	$ edit po/af.po
 	... be sure to update Last-Translator: and
 	... PO-Revision-Date: lines.
 	$ git add po/af.po
 	$ git commit -s -m 'git-gui: added Afrikaans translation.'
 	$ git send-email --to 'git@vger.kernel.org' \
 	   --cc 'Pat Thoyts <patthoyts@users.sourceforge.net>' \
 	   --subject 'git-gui: Afrikaans translation' \
 	   master..


 3. Updating your translation.

 There may already be a translation for your language, and you may want
 to contribute an update.  This may be because you would want to improve
 the translation of existing messages, or because the git-gui software
 itself was updated and there are new messages that need translation.

 In any case, make sure you are up to date before starting your work:

 	$ git checkout master
 	$ git pull

 In the former case, you will edit po/af.po (again, replace "af" with
 your language code), and after testing and updating the Last-Translator:
 and PO-Revision-Date: lines, "add/commit/push" as in the previous
 section.

 By comparing "POT-Creation-Date:" line in po/git-gui.pot file and
 po/af.po file, you can tell if there are new messages that need to be
 translated.  You would need the GNU gettext package to perform this
 step.

 	$ msgmerge -U po/af.po po/git-gui.pot

 This updates po/af.po (again, replace "af" with your language
 code) so that it contains msgid lines (i.e. the original) that
 your translation did not have before.  There are a few things to
 watch out for:

  - The original text in English of an older message you already
    translated might have been changed.  You will notice a comment line
    that begins with "#, fuzzy" in front of such a message.  msgmerge
    tool made its best effort to match your old translation with the
    message from the updated software, but you may find cases that it
    matched your old translated message to a new msgid and the pairing
    does not make any sense -- you would need to fix them, and then
    remove the "#, fuzzy" line from the message (your fixed translation
    of the message will not be used before you remove the marker).

  - New messages added to the software will have msgstr lines with empty
    strings.  You would need to translate them.

 The po/git-gui.pot file is updated by the internationalization
 coordinator from time to time.  You _could_ update it yourself, but
 translators are discouraged from doing so because we would want all
 language teams to be working off of the same version of git-gui.pot.

 ****************************************************************

 This section is a note to the internationalization coordinator, and
 translators do not have to worry about it too much.

 The message template file po/git-gui.pot needs to be kept up to date
 relative to the software the translations apply to, and it is the
 responsibility of the internationalization coordinator.

 When updating po/git-gui.pot file, however, _never_ run "msgmerge -U
 po/xx.po" for individual language translations, unless you are absolutely
 sure that there is no outstanding work on translation for language xx.
 Doing so will create unnecessary merge conflicts and force needless
 re-translation on translators.  The translator however may not have access
 to the msgmerge tool, in which case the coordinator may run it for the
 translator as a service.

 But mistakes do happen.  Suppose a translation was based on an older
 version X, the POT file was updated at version Y and then msgmerge was run
 at version Z for the language, and the translator sent in a patch based on
 version X:

          ? translated
         /
     ---X---Y---Z (master)

 The coordinator could recover from such a mistake by first applying the
 patch to X, replace the translated file in Z, and then running msgmerge
 again based on the updated POT file and commit the result.  The sequence
 would look like this:

     $ git checkout X
     $ git am -s xx.patch
     $ git checkout master
     $ git checkout HEAD@{1} po/xx.po
     $ msgmerge -U po/xx.po po/git-gui.pot
     $ git commit -c HEAD@{1} po/xx.po

 State in the message that the translated messages are based on a slightly
 older version, and msgmerge was run to incorporate changes to message
 templates from the updated POT file.  The result needs to be further
 translated, but at least the messages that were updated by the patch that
 were not changed by the POT update will survive the process and do not
 need to be re-translated.
	Localizing git-gui for your language
	====================================

	This short note is to help you, who reads and writes English and your
	own language, help us getting git-gui localized for more languages. It
	does not try to be a comprehensive manual of GNU gettext, which is the
	i18n framework we use, but tries to help you get started by covering the
	basics and how it is used in this project.

	1. Getting started.

	You would first need to have a working "git". Your distribution may
	have it as "git-core" package (do not get "GNU Interactive Tools" --
	that is a different "git"). You would also need GNU gettext toolchain
	to test the resulting translation out. Although you can work on message
	translation files with a regular text editor, it is a good idea to have
	specialized so-called "po file editors" (e.g. emacs po-mode, KBabel,
	poedit, GTranslator --- any of them would work well). Please install
	them.

	You would then need to clone the git-gui project repository and create
	a feature branch to begin working:

	$ git clone git://repo.or.cz/git-gui.git
	$ cd git-gui.git
	$ git checkout -b my-translation

	The "git checkout" command creates a new branch to keep your work
	isolated and to make it simple to post your patch series when
	completed. You will be working on this branch.


	2. Starting a new language.

	In the git-gui directory is a po/ subdirectory. It has a handful of
	files whose names end with ".po". Is there a file that has messages
	in your language?

	If you do not know what your language should be named, you need to find
	it. This currently follows ISO 639-1 two letter codes:

	http://www.loc.gov/standards/iso639-2/php/code_list.php

	For example, if you are preparing a translation for Afrikaans, the
	language code is "af". If there already is a translation for your
	language, you do not have to perform any step in this section, but keep
	reading, because we are covering the basics.

	If you did not find your language, you would need to start one yourself.
	Copy po/git-gui.pot file to po/af.po (replace "af" with the code for
	your language). Edit the first several lines to match existing *.po
	files to make it clear this is a translation table for git-gui project,
	and you are the primary translator. The result of your editing would
	look something like this:

	# Translation of git-gui to Afrikaans
	# Copyright (C) 2007 Shawn Pearce
	# This file is distributed under the same license as the git-gui package.
	# YOUR NAME <YOUR@E-MAIL.ADDRESS>, 2007.
	#
	#, fuzzy
	msgid ""
	msgstr ""
	"Project-Id-Version: git-gui\n"
	"Report-Msgid-Bugs-To: \n"
	"POT-Creation-Date: 2007-07-24 22:19+0300\n"
	"PO-Revision-Date: 2007-07-25 18:00+0900\n"
	"Last-Translator: YOUR NAME <YOUR@E-MAIL.ADDRESS>\n"
	"Language-Team: Afrikaans\n"
	"MIME-Version: 1.0\n"
	"Content-Type: text/plain; charset=UTF-8\n"
	"Content-Transfer-Encoding: 8bit\n"

	You will find many pairs of a "msgid" line followed by a "msgstr" line.
	These pairs define how messages in git-gui application are translated to
	your language. Your primarily job is to fill in the empty double quote
	pairs on msgstr lines with the translation of the strings on their
	matching msgid lines. A few tips:

	- Control characters, such as newlines, are written in backslash
	sequence similar to string literals in the C programming language.
	When the string given on a msgid line has such a backslash sequence,
	you would typically want to have corresponding ones in the string on
	your msgstr line.

	- Some messages contain an optional context indicator at the end,
	for example "@@noun" or "@@verb". This indicator allows the
	software to select the correct translation depending upon the use.
	The indicator is not actually part of the message and will not
	be shown to the end-user.

	If your language does not require a different translation you
	will still need to translate both messages.

	- Often the messages being translated are format strings given to
	"printf()"-like functions. Make sure "%s", "%d", and "%%" in your
	translated messages match the original.

	When you have to change the order of words, you can add "<number>$"
	between '%' and the conversion ('s', 'd', etc.) to say "<number>-th
	parameter to the format string is used at this point". For example,
	if the original message is like this:

	"Length is %d, Weight is %d"

	and if for whatever reason your translation needs to say weight first
	and then length, you can say something like:

	"WEIGHT IS %2$d, LENGTH IS %1$d"

	A format specification with a '' (asterisk) refers to two* arguments
	instead of one, hence the succeeding argument number is two higher
	instead of one. So, a message like this

	"%s ... %i of %i %s (%3i%%)"

	is equivalent to

	"%1$s ... %2$i of %4$i %6$s (%7$3i%%)"

	- A long message can be split across multiple lines by ending the
	string with a double quote, and starting another string on the next
	line with another double quote. They will be concatenated in the
	result. For example:

	#: lib/remote_branch_delete.tcl:189
	#, tcl-format
	msgid ""
	"One or more of the merge tests failed because you have not fetched the "
	"necessary commits. Try fetching from %s first."
	msgstr ""
	"HERE YOU WILL WRITE YOUR TRANSLATION OF THE ABOVE LONG "
	"MESSAGE IN YOUR LANGUAGE."

	You can test your translation by running "make install", which would
	create po/af.msg file and installs the result, and then running the
	resulting git-gui under your locale:

	$ make install
	$ LANG=af git-gui

	There is a trick to test your translation without first installing:

	$ make
	$ LANG=af ./git-gui.sh

	When you are satisfied with your translation, commit your changes then submit
	your patch series to the maintainer and the Git mailing list:

	$ edit po/af.po
	... be sure to update Last-Translator: and
	... PO-Revision-Date: lines.
	$ git add po/af.po
	$ git commit -s -m 'git-gui: added Afrikaans translation.'
	$ git send-email --to 'git@vger.kernel.org' \
	--cc 'Pat Thoyts <patthoyts@users.sourceforge.net>' \
	--subject 'git-gui: Afrikaans translation' \
	master..


	3. Updating your translation.

	There may already be a translation for your language, and you may want
	to contribute an update. This may be because you would want to improve
	the translation of existing messages, or because the git-gui software
	itself was updated and there are new messages that need translation.

	In any case, make sure you are up to date before starting your work:

	$ git checkout master
	$ git pull

	In the former case, you will edit po/af.po (again, replace "af" with
	your language code), and after testing and updating the Last-Translator:
	and PO-Revision-Date: lines, "add/commit/push" as in the previous
	section.

	By comparing "POT-Creation-Date:" line in po/git-gui.pot file and
	po/af.po file, you can tell if there are new messages that need to be
	translated. You would need the GNU gettext package to perform this
	step.

	$ msgmerge -U po/af.po po/git-gui.pot

	This updates po/af.po (again, replace "af" with your language
	code) so that it contains msgid lines (i.e. the original) that
	your translation did not have before. There are a few things to
	watch out for:

	- The original text in English of an older message you already
	translated might have been changed. You will notice a comment line
	that begins with "#, fuzzy" in front of such a message. msgmerge
	tool made its best effort to match your old translation with the
	message from the updated software, but you may find cases that it
	matched your old translated message to a new msgid and the pairing
	does not make any sense -- you would need to fix them, and then
	remove the "#, fuzzy" line from the message (your fixed translation
	of the message will not be used before you remove the marker).

	- New messages added to the software will have msgstr lines with empty
	strings. You would need to translate them.

	The po/git-gui.pot file is updated by the internationalization
	coordinator from time to time. You _could_ update it yourself, but
	translators are discouraged from doing so because we would want all
	language teams to be working off of the same version of git-gui.pot.

	****************************************************************

	This section is a note to the internationalization coordinator, and
	translators do not have to worry about it too much.

	The message template file po/git-gui.pot needs to be kept up to date
	relative to the software the translations apply to, and it is the
	responsibility of the internationalization coordinator.

	When updating po/git-gui.pot file, however, _never_ run "msgmerge -U
	po/xx.po" for individual language translations, unless you are absolutely
	sure that there is no outstanding work on translation for language xx.
	Doing so will create unnecessary merge conflicts and force needless
	re-translation on translators. The translator however may not have access
	to the msgmerge tool, in which case the coordinator may run it for the
	translator as a service.

	But mistakes do happen. Suppose a translation was based on an older
	version X, the POT file was updated at version Y and then msgmerge was run
	at version Z for the language, and the translator sent in a patch based on
	version X:

	? translated
	/
	---X---Y---Z (master)

	The coordinator could recover from such a mistake by first applying the
	patch to X, replace the translated file in Z, and then running msgmerge
	again based on the updated POT file and commit the result. The sequence
	would look like this:

	$ git checkout X
	$ git am -s xx.patch
	$ git checkout master
	$ git checkout HEAD@{1} po/xx.po
	$ msgmerge -U po/xx.po po/git-gui.pot
	$ git commit -c HEAD@{1} po/xx.po

	State in the message that the translated messages are based on a slightly
	older version, and msgmerge was run to incorporate changes to message
	templates from the updated POT file. The result needs to be further
	translated, but at least the messages that were updated by the patch that
	were not changed by the POT update will survive the process and do not
	need to be re-translated.