| <!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 <EMAIL@ADDRESS>, YEAR. |
| </pre> |
| |
| <p>Please replace that block with the following text:</p> |
| <pre> |
| # <Your language> 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 <EMAIL@ADDRESS>\n" |
| "Language-Team: LANGUAGE <LL@li.org>\n" |
| </pre> |
| |
| <p>Please replace those with these two lines:</p> |
| <pre> |
| "Last-Translator: Subversion Developers <dev@subversion.tigris.org>\n" |
| "Language-Team: YOUR LANGUAGE <dev@subversion.tigris.org>\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—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 <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> |