blob: 76a38e5a0b20ca23c719a7a611a13f801ada5907 [file] [log] [blame]
-*- 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
* Updating existing po files
* 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 the HACKING
document also in this directory.
Software version requirements
=============================
The Makefile build targets locale-gnu-* (used to maintain po files)
require GNU gettext 0.12 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 HACKING 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> Collab Net.
# 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
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.
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
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
HACKING. 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 HACKING 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.