blob: f4892d0a321b43934c14ce527fd6e9f61f7e9deb [file] [log] [blame]
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<style type="text/css"> /* <![CDATA[ */
@import "branding/css/tigris.css";
@import "branding/css/inst.css";
/* ]]> */</style>
<link rel="stylesheet" type="text/css" media="print"
href="branding/css/print.css" />
<script type="text/javascript" src="branding/scripts/tigris.js"></script>
<title>Guide to Translating Subversion</title>
</head>
<body>
<div class="app">
<h1 style="text-align: center;">Guide to Translating Subversion</h1>
<p>If you are contributing translations to the Subversion project, please read
this first. For general project guidelines, see the <a href="hacking.html">
Hacker's Guide to Subversion</a>.</p>
<pre>
$LastChangedDate$
</pre>
<div class="h2"><!-- no 'id' or 'title' attribute for ToC -->
<h2>Table of Contents</h2>
<ul>
<li><a href="#introduction">Introduction</a></li>
<li><a href="#version-requirements">Software version requirements</a></li>
<li><a href="#new-translation">Starting a new translation</a></li>
<li><a href="#verifying">Verifying your po file</a></li>
<li><a href="#submitting">Submitting your po file</a></li>
<li><a href="#updating">Updating existing po files</a></li>
<li><a href="#branch-maintenance">Maintenance on branches</a></li>
<li><a href="#po-mo-requirements">Requirements for po and mo files</a></li>
<li><a href="#empty-string-conventions">Conventions for the empty string
msgid section</a></li>
<li><a href="#translation-teams">Translation teams</a></li>
<li><a href="#quotes">Single versus double quotes</a></li>
<li><a href="#error-messages">Error message conventions</a></li>
</ul>
</div>
<div class="h2" id="introduction" title="introduction">
<h2>Introduction</h2>
<p>Subversion uses gettext for its translation. Gettext uses <code>.po</code>
files to store translation information; the existing ones are kept in the
subversion/po directory of the repository. <em>Note that we
deliberately do not require GNU gettext.</em></p>
<p>Please take some time to go through this document as well as the
<a href="hacking.html"> Hacker's Guide to Subversion</a>.</p>
</div> <!-- introduction -->
<div class="h2" id="version-requirements" title="version-requirements">
<h2>Software version requirements</h2>
<p>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.</p>
</div> <!-- version-requirements -->
<div class="h2" id="new-translation" title="new-translation">
<h2>Starting a new translation</h2>
<p>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.</p>
<p>After that, you should perform the following steps:</p>
<div class="h3" id="unix-gnu-gettext" title="unix-gnu-gettext">
<h3>Unix (GNU gettext)</h3>
<ol>
<li>check out Subversion (see INSTALL for more information)</li>
<li>run <code>./autogen.sh</code></li>
<li>run <code>./configure</code></li>
<li>run <code>make locale-gnu-pot</code><br/>
This step is currently only supported for GNU gettext Makefile based
systems</li>
<li>run <code>msginit --locale LOCALE -o LOCALE.po</code> in the
<code>subversion/po</code> directory of your working copy. LOCALE is
the ll[_LL] language and country code used to identify your locale.</li>
</ol>
<p>Steps (2) and (3) generate a Makefile; step (4) generates
<code>subversion/po/subversion.pot</code></p>
<p>The Subversion project has <a href="hacking.html#other-conventions">a
policy</a> not to put names in its files, so please apply the two changes
described below.</p>
<p>The header in the newly generated .po file looks like this:</p>
<pre>
# 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 &lt;EMAIL@ADDRESS&gt;, YEAR.
</pre>
<p>Please replace that block with the following text:</p>
<pre>
# &lt;Your language&gt; translation for subversion package
# Licensed to the Subversion Corporation (SVN Corp.) under one
# or more contributor license agreements. See the NOTICE file
# distributed with this work for additional information
# regarding copyright ownership. The SVN Corp. licenses this file
# to you under the Apache License, Version 2.0 (the
# "License"); you may not use this file except in compliance
# with the License. You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing,
# software distributed under the License is distributed on an
# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
# KIND, either express or implied. See the License for the
# specific language governing permissions and limitations
# under the License.
</pre>
<p>The first translation block in the .po file contains two lines like
these:</p>
<pre>
"Last-Translator: FULL NAME &lt;EMAIL@ADDRESS&gt;\n"
"Language-Team: LANGUAGE &lt;LL@li.org&gt;\n"
</pre>
<p>Please replace those with these two lines:</p>
<pre>
"Last-Translator: Subversion Developers &lt;dev@subversion.tigris.org&gt;\n"
"Language-Team: YOUR LANGUAGE &lt;dev@subversion.tigris.org&gt;\n"
</pre>
</div> <!-- unix-gnu-gettext -->
<div class="h3" id="unix-nongnu-gettext" title="unix-nongnu-gettext">
<h3>Unix (non-GNU gettext)</h3>
<p>To be documented</p>
</div> <!-- unix-nongnu-gettext -->
<div class="h3" id="windows" title="windows">
<h3>Windows</h3>
<p>See <a href="/issues/show_bug.cgi?id=1977">issue #1977</a>.</p>
</div> <!-- windows -->
</div> <!-- new-translation -->
<div class="h2" id="verifying" title="verifying">
<h2>Verifying your po file</h2>
<p>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):</p>
<ol>
<li>run <code>./autogen.sh</code></li>
<li>run <code>./configure</code> (with the appropriate arguments)</li>
<li>run <code>make locale</code></li>
</ol>
<p>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.</p>
</div> <!-- verifying -->
<div class="h2" id="submitting" title="submitting">
<h2>Submitting your po file</h2>
<p>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.</p>
<p>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.</p>
</div> <!-- submitting -->
<div class="h2" id="updating" title="updating">
<h2>Updating existing po files</h2>
<p>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</p>
<pre>
make locale-gnu-po-update
</pre>
<p>To only update a particular language, you may use</p>
<pre>
make locale-gnu-po-update PO=ll
</pre>
<p>where ll is the name of the po file without the extension (i.e. PO=sv).</p>
<p>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:</p>
<ul>
<li><code>gettext(1)</code> 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.</li>
<li>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.</li>
</ul>
</div> <!-- updating -->
<div class="h2" id="branch-maintenance" title="branch-maintenance">
<h2>Maintenance on branches</h2>
<p>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 <code>svn merge</code> to do the job
can lead to conflicts and fuzzy messages due to the changes in line numbers
and string formatting done by gettext.</p>
The scheme below eliminates any complexity which exists when using <code>svn
merge</code> to do branch updates. The following rules apply:
<ul>
<li>Translation updates go to trunk</li>
<li>Messages required on the branch which ever existed on trunk
get merged from trunk</li>
<li>There are 2 mass operations allowed on po files on branches:
<ul>
<li><code>make locale-gnu-po-update</code></li>
<li>merging messages from trunk (see below)</li>
</ul></li>
<li>The remaining few messages which never existed on trunk
in any revision are translated on the branch</li>
<li>Message options (such as fuzzy) can be tweaked</li>
</ul>
<p>The above list is a complete enumeration of all operations allowed on
po files on branches.</p>
<p>Merging messages from trunk revision X of YY.po to your branch working
copy can be done with this command:</p>
<pre>
svn cat -r X http://svn.collab.net/repos/svn/trunk/subversion/po/YY.po | \
po-merge.py YY.po
</pre>
</div> <!-- branch-maintenance -->
<div class="h2" id="po-mo-requirements" title="po-mo-requirements">
<h2>Requirements for po and mo files</h2>
<p>On some gettext implementations we have to ensure that the mo
files&mdash;whether obtained through the project or created locally&mdash;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 <code>bind_textdomain_codeset()</code> is not portable
across implementations.</p>
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.
</div> <!-- po-mo-requirements -->
<div class="h2" id="empty-string-conventions" title="empty-string-conventions">
<h2>Conventions for the empty string msgid section</h2>
<p>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.</p>
<p>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.</p>
</div> <!-- empty-string-conventions -->
<div class="h2" id="translation-teams" title="translation-teams">
<h2>Translation teams</h2>
<p>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.</p>
</div> <!-- translation-teams -->
<div class="h2" id="quotes" title="quotes">
<h2>Single versus double quotes</h2>
<p>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 :-)</p>
</div> <!-- quotes -->
<div class="h2" id="error-messages" title="error-messages">
<h2>Error message conventions</h2>
<p>Since translators will generally see all error messages in the code,
it's important to know that there is a <a href="hacking.html#error-messages">
special section</a> in the Hacker's Guide 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.</p>
</div> <!-- error-messages -->
</div>
</body>
</html>