TRANSLATING - subversion - Git at Google

                                                               -*- text -*-

 If you are contributing code or translations to the Subversion project,
 please read this first.

                    ===============================
                    Guide to translating Subversion
                    ===============================

 $LastChangedDate$

 * Introduction
 * Software version requirements
 * Starting a new translation
 * Verifying your po file
 * Submitting your po file
 * Updating existing po files
 * Maintenance on branches
 * Requirements for po and mo files
 * Conventions for the empty string msgid section
 * Translation teams
 * Single versus double quotes
 * Error message conventions


 Introduction
 ============

 Subversion uses gettext for its translation.  Gettext uses '.po' files
 to store translation information; the existing ones are kept in the
 subversion/po directory of the repository.
 [Note that the last paragraph deliberately does not say GNU gettext.]

 Please take some time to go through this document as well as
 www/hacking.html.


 Software version requirements
 =============================

 The Makefile build targets locale-gnu-* (used to maintain po files)
 require GNU gettext 0.13 or newer.  Note that this is not a requirement
 for those wanting to compile the *.po files into *.mo's.


 Starting a new translation
 ==========================

 Before starting a new translation please contact the subversion
 development mailing list to make sure you are not duplicating efforts. Also
 please note that the project has a strong preference for translations which
 are maintained by more than one person: mailing the lists with your
 intentions might help you find supporters.

 After that, you should perform the following steps:

 * Unix (GNU gettext)

 1) check out Subversion (see INSTALL for more information)
 2) run ./autogen.sh
 3) run ./configure
 4) run make locale-gnu-pot
   This step is currently only supported for GNU gettext Makefile based
   systems
 5) run msginit --locale LOCALE -o LOCALE.po in the
   subversion/po directory of your working copy. LOCALE is the ll[_LL]
   language and country code used to identify your locale.

 Steps (2) and (3) generate a Makefile; step (4) generates
 subversion/po/subversion.pot

 The Subversion project has a policy not to put names in its files, so
 please apply the two changes described below.  (See www/hacking.html
 for a description of this convention.)


 The header in the newly generated .po file looks like this:
   # SOME DESCRIPTIVE TITLE.
   # Copyright (C) YEAR THE PACKAGE'S COPYRIGHT HOLDER
   # This file is distributed under the same license as the PACKAGE package.
   # FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.

 Please replace that block with the following text:
   # <Your language> translation for subversion package
   # Copyright (C) <YEAR> CollabNet.
   # This file is distributed under the same license as the subversion package.

 The first translation block in the .po file contains two lines like these:
   "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
   "Language-Team: LANGUAGE <LL@li.org>\n"

 Please replace those with these two lines:
   "Last-Translator: Subversion Developers <dev@subversion.tigris.org>\n"
   "Language-Team: YOUR LANGUAGE <dev@subversion.tigris.org>\n"


 * Unix (non-GNU gettext)

   To be documented

 * Windows

   See issue #1977 in the subversion issue tracker

 For the time being, hourly updated subversion.pot files are posted at:

 http://hix.nu/subversion/trunk/subversion.pot (for trunk)
 http://hix.nu/subversion/1.1.x/subversion.pot (for 1.1.x)


 Verifying your po file
 ======================

 Before submitting to the mailing list or committing to the repository,
 please make sure your po file 'compiles'.  You can do this with these
 steps (on Makefile based systems):

 1) run './autogen.sh'
 2) run './configure' (with the appropriate arguments)
 3) run 'make locale'

 The autogen.sh step is important, since it adds new po files as
 dependencies of the 'locale' build target.  Note however that steps 1
 and 2 are only needed once after you have added a new translation.


 Submitting your po file
 =======================

 Please don't mail large po files to the mailing lists.  There are many
 subscribers on dev@subversion.tigris.org who are on slow links and do
 not want to receive a large file by email.  Instead, place the po file
 somewhere on the Internet for download, and just post the URL.  If you
 do not have a site available, please ask on dev@ and someone will help
 you find a location.

 Of course, if you have commit access to the Subversion repository, you
 can just commit the po file there, assuming all other requirements
 have been satisfied.


 Updating existing po files
 ==========================

 The Makefile based part of the build system contains a make target to
 facilitate maintenance of existing po files.  To update po files on
 systems with GNU gettext run

     make locale-gnu-po-update

 To only update a particular language, you may use

     make locale-gnu-po-update PO=ll

 where ll is the name of the po file without the extension (i.e. PO=sv).

 It is recommended that the .po update is done by using two commits; one
 after the "make locale-gnu-po-update", and one after the translation is
 done. This has two advantages:

 - gettext(1) produces lots of line number changes which makes the
   resulting diff hard to review by the other translators. By committing
   twice, all the line number changes are stored in the first commit, and
   the second commit contains all the actual translations with no extra
   garbage.
 - If there are several translators for a specific language (which is
   highly preferred by the project) you don't risk working for hours just
   to find that some other translator already has done the job when
   you're finished. You will immediately notice that someone else is
   working on the .po file when you try to perform the first commit,
   because svn will tell you that the file is outdated.


 Maintenance on branches
 =======================

 Editing po files in trunk is pretty straightforward, but gets a bit more
 complicated when those changes are going to be transferred to a release
 branch.  Project policy is to make no direct changes on release branches,
 everything that is committed to the branch should be merged from trunk.
 This also applies to po files.  Using 'svn merge' to do the job can lead
 to conflicts and fuzzy messages due to the changes in line numbers and
 string formatting done by gettext.

 The scheme below eliminates any complexity which exists when using 'svn
 merge' to do branch updates. The following rules apply:

 - Translation updates go to trunk
 - Messages required on the branch which ever existed on trunk
   get merged from trunk
 - There are 2 mass operations allowed on po files on branches:
   * 'make locale-gnu-po-update'
   * merging messages from trunk (see below)
 - The remaining few messages which never existed on trunk
   in any revision are translated on the branch
 - Message options (such as fuzzy) can be tweaked

 The above list is a complete enumeration of all operations allowed on
 po files on branches.

 Merging messages from trunk revision X of YY.po to your branch working
 copy can be done with this command:

   svn cat -r X http://svn.collab.net/repos/svn/trunk/subversion/po/YY.po | \
     po-merge.py YY.po


 Requirements for po and mo files
 ================================

 On some gettext implementations we have to ensure that the mo files -
 whether obtained through the project or created locally - are encoded
 using UTF-8.  This requirement stem from the fact that Subversion uses
 UTF-8 internally, some implementations translate to the active locale
 and the fact that bind_textdomain_codeset() is not portable across
 implementations.

 To satisfy this requirement po files are required to be UTF-8 encoded.
 If the gettext implementation on the target system doesn't support
 bind_textdomain_codeset(), the build system will ensure that the mo
 file is in UTF-8 by removing the Content-Type header from the po file
 header.  Note that some msgfmt utilities dislike the absence of the
 charset designator and will generate warnings along the lines of
 "Won't be able to do character set conversion" because of it.  You can
 safely ignore these warnings.


 Conventions for the empty string msgid section
 ==============================================

 Some gettext implementations use a section with a msgid "" (empty
 string) to keep administrative data.  One of the headers suggested is
 the 'Last-Translator:' field.  Because the Subversion project has a
 policy not to name contributors in specific files, but give credit in
 the repository log messages, you are required not to put your name in
 this field.

 Since some tools require this field to consider the po file valid
 (i.e. Emacs PO Mode), you can put "dev@subversion.tigris.org" into
 this field.


 Translation teams
 =================

 The GNU translation project
 (http://www2.iro.umontreal.ca/~gnutra/po/HTML/) attempts to organise
 translation attempts and get translators for various packages.  Some
 teams have guidelines to stimulate consistency across packages.


 Single versus double quotes
 ===========================

 The project has standardised the use of quotes.  Some translation
 teams have done the same.  If there is no translation team for your
 locale or they did not standardise quoting, please follow the project
 guidelines per www/hacking.html.  If they did: follow them :-)


 Error message conventions
 =========================

 Since translators will generally see all error messages in the code,
 it's important to know that there is a special section in
 www/hacking.html about this category of strings.  Here the same
 applies as does for the quotes: Adhere to them on all points for which
 there is no explicit policy set out by the translation team for your
 language.

 vim: set tw=72 ts=2 sw=2 sts=2 et fo-=2w fo+=n js :
	-- text --

	If you are contributing code or translations to the Subversion project,
	please read this first.

	===============================
	Guide to translating Subversion
	===============================

	$LastChangedDate$

	* Introduction
	* Software version requirements
	* Starting a new translation
	* Verifying your po file
	* Submitting your po file
	* Updating existing po files
	* Maintenance on branches
	* Requirements for po and mo files
	* Conventions for the empty string msgid section
	* Translation teams
	* Single versus double quotes
	* Error message conventions



	Introduction
	============

	Subversion uses gettext for its translation. Gettext uses '.po' files
	to store translation information; the existing ones are kept in the
	subversion/po directory of the repository.
	[Note that the last paragraph deliberately does not say GNU gettext.]

	Please take some time to go through this document as well as
	www/hacking.html.



	Software version requirements
	=============================

	The Makefile build targets locale-gnu-* (used to maintain po files)
	require GNU gettext 0.13 or newer. Note that this is not a requirement
	for those wanting to compile the .po files into .mo's.



	Starting a new translation
	==========================

	Before starting a new translation please contact the subversion
	development mailing list to make sure you are not duplicating efforts. Also
	please note that the project has a strong preference for translations which
	are maintained by more than one person: mailing the lists with your
	intentions might help you find supporters.

	After that, you should perform the following steps:

	* Unix (GNU gettext)

	1) check out Subversion (see INSTALL for more information)
	2) run ./autogen.sh
	3) run ./configure
	4) run make locale-gnu-pot
	This step is currently only supported for GNU gettext Makefile based
	systems
	5) run msginit --locale LOCALE -o LOCALE.po in the
	subversion/po directory of your working copy. LOCALE is the ll[_LL]
	language and country code used to identify your locale.

	Steps (2) and (3) generate a Makefile; step (4) generates
	subversion/po/subversion.pot

	The Subversion project has a policy not to put names in its files, so
	please apply the two changes described below. (See www/hacking.html
	for a description of this convention.)


	The header in the newly generated .po file looks like this:
	# SOME DESCRIPTIVE TITLE.
	# Copyright (C) YEAR THE PACKAGE'S COPYRIGHT HOLDER
	# This file is distributed under the same license as the PACKAGE package.
	# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.

	Please replace that block with the following text:
	# <Your language> translation for subversion package
	# Copyright (C) <YEAR> CollabNet.
	# This file is distributed under the same license as the subversion package.

	The first translation block in the .po file contains two lines like these:
	"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
	"Language-Team: LANGUAGE <LL@li.org>\n"

	Please replace those with these two lines:
	"Last-Translator: Subversion Developers <dev@subversion.tigris.org>\n"
	"Language-Team: YOUR LANGUAGE <dev@subversion.tigris.org>\n"


	* Unix (non-GNU gettext)

	To be documented

	* Windows

	See issue #1977 in the subversion issue tracker

	For the time being, hourly updated subversion.pot files are posted at:

	http://hix.nu/subversion/trunk/subversion.pot (for trunk)
	http://hix.nu/subversion/1.1.x/subversion.pot (for 1.1.x)



	Verifying your po file
	======================

	Before submitting to the mailing list or committing to the repository,
	please make sure your po file 'compiles'. You can do this with these
	steps (on Makefile based systems):

	1) run './autogen.sh'
	2) run './configure' (with the appropriate arguments)
	3) run 'make locale'

	The autogen.sh step is important, since it adds new po files as
	dependencies of the 'locale' build target. Note however that steps 1
	and 2 are only needed once after you have added a new translation.



	Submitting your po file
	=======================

	Please don't mail large po files to the mailing lists. There are many
	subscribers on dev@subversion.tigris.org who are on slow links and do
	not want to receive a large file by email. Instead, place the po file
	somewhere on the Internet for download, and just post the URL. If you
	do not have a site available, please ask on dev@ and someone will help
	you find a location.

	Of course, if you have commit access to the Subversion repository, you
	can just commit the po file there, assuming all other requirements
	have been satisfied.



	Updating existing po files
	==========================

	The Makefile based part of the build system contains a make target to
	facilitate maintenance of existing po files. To update po files on
	systems with GNU gettext run

	make locale-gnu-po-update

	To only update a particular language, you may use

	make locale-gnu-po-update PO=ll

	where ll is the name of the po file without the extension (i.e. PO=sv).

	It is recommended that the .po update is done by using two commits; one
	after the "make locale-gnu-po-update", and one after the translation is
	done. This has two advantages:

	- gettext(1) produces lots of line number changes which makes the
	resulting diff hard to review by the other translators. By committing
	twice, all the line number changes are stored in the first commit, and
	the second commit contains all the actual translations with no extra
	garbage.
	- If there are several translators for a specific language (which is
	highly preferred by the project) you don't risk working for hours just
	to find that some other translator already has done the job when
	you're finished. You will immediately notice that someone else is
	working on the .po file when you try to perform the first commit,
	because svn will tell you that the file is outdated.


	Maintenance on branches
	=======================

	Editing po files in trunk is pretty straightforward, but gets a bit more
	complicated when those changes are going to be transferred to a release
	branch. Project policy is to make no direct changes on release branches,
	everything that is committed to the branch should be merged from trunk.
	This also applies to po files. Using 'svn merge' to do the job can lead
	to conflicts and fuzzy messages due to the changes in line numbers and
	string formatting done by gettext.

	The scheme below eliminates any complexity which exists when using 'svn
	merge' to do branch updates. The following rules apply:

	- Translation updates go to trunk
	- Messages required on the branch which ever existed on trunk
	get merged from trunk
	- There are 2 mass operations allowed on po files on branches:
	* 'make locale-gnu-po-update'
	* merging messages from trunk (see below)
	- The remaining few messages which never existed on trunk
	in any revision are translated on the branch
	- Message options (such as fuzzy) can be tweaked

	The above list is a complete enumeration of all operations allowed on
	po files on branches.

	Merging messages from trunk revision X of YY.po to your branch working
	copy can be done with this command:

	svn cat -r X http://svn.collab.net/repos/svn/trunk/subversion/po/YY.po \| \
	po-merge.py YY.po



	Requirements for po and mo files
	================================

	On some gettext implementations we have to ensure that the mo files -
	whether obtained through the project or created locally - are encoded
	using UTF-8. This requirement stem from the fact that Subversion uses
	UTF-8 internally, some implementations translate to the active locale
	and the fact that bind_textdomain_codeset() is not portable across
	implementations.

	To satisfy this requirement po files are required to be UTF-8 encoded.
	If the gettext implementation on the target system doesn't support
	bind_textdomain_codeset(), the build system will ensure that the mo
	file is in UTF-8 by removing the Content-Type header from the po file
	header. Note that some msgfmt utilities dislike the absence of the
	charset designator and will generate warnings along the lines of
	"Won't be able to do character set conversion" because of it. You can
	safely ignore these warnings.



	Conventions for the empty string msgid section
	==============================================

	Some gettext implementations use a section with a msgid "" (empty
	string) to keep administrative data. One of the headers suggested is
	the 'Last-Translator:' field. Because the Subversion project has a
	policy not to name contributors in specific files, but give credit in
	the repository log messages, you are required not to put your name in
	this field.

	Since some tools require this field to consider the po file valid
	(i.e. Emacs PO Mode), you can put "dev@subversion.tigris.org" into
	this field.



	Translation teams
	=================

	The GNU translation project
	(http://www2.iro.umontreal.ca/~gnutra/po/HTML/) attempts to organise
	translation attempts and get translators for various packages. Some
	teams have guidelines to stimulate consistency across packages.



	Single versus double quotes
	===========================

	The project has standardised the use of quotes. Some translation
	teams have done the same. If there is no translation team for your
	locale or they did not standardise quoting, please follow the project
	guidelines per www/hacking.html. If they did: follow them :-)



	Error message conventions
	=========================

	Since translators will generally see all error messages in the code,
	it's important to know that there is a special section in
	www/hacking.html about this category of strings. Here the same
	applies as does for the quotes: Adhere to them on all points for which
	there is no explicit policy set out by the translation team for your
	language.

	vim: set tw=72 ts=2 sw=2 sts=2 et fo-=2w fo+=n js :