| -*- 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. |