TranslationUserInterface

TranslationUserInterface

This document is targeted at translators. If you are looking for instructions on configuring your Foswiki to work with your local language, see InstallationWithI18N?

Foswiki is using CPAN:Locale::Maketext for user interface internationalisation. This is a very flexible framework for localisation, and supports several issues that are critical to good translation in most of existing languages, every those largely different from common western languages (see user interface internationalisation for further details).

The rest of this topic documents how one can contribute a new language to Foswiki.

How can I add a new language to Foswiki ?

Adding a new language to Foswiki is easy: you just have to make a copy of the translation file template, Foswiki.pot to your language's code. For example: fr.po for generic french, fr-fr.po for French as spoken in France, or fr-ca.po for Canadian French.

Note: avoid adding a country-specific translation (e.g. fr-fr, fr-ca) before we have the generic translation (fr).

Here we can differ on two situations: one for released Foswiki versions, whose strings are frozen, and other for Foswiki versions under development. The rest of this section describes how to deal with translation files, create your translation file, send it to the development team, etc. The Translating section describes how to actually translate the file's contents.

Released versions

After unpacking Foswiki's package, you'll find a locale/ directory. It contains the Foswiki.pot template and all the translation files. You can just make copy of Foswiki.pot under the right name for your language and translate the file. Please attach your final translation to this topic so the Foswiki community can benefit from your contribution.

Under-development versions

For under development versions, you're encouraged to follow the changes in the template using Subversion? .

Making an initial working copy

You can download Foswiki's locale directory using:

svn checkout http://svn.foswiki.org/trunk/core/locale/ Foswiki-locale/

This will make a local working copy of Foswiki's locale/ directory in Subversion, named Foswiki-locale/. You can now enter it and start your translation, just as described above for released versions.

Sending your translation to the development team

First create a <MyLanguage>Translation topic here in the Codev web, starting from TranslationSupport? .

If you already have write access to Foswiki's SVN repository you can commit your changes directly. See SubversionReadme? .

Otherwise, you can attach your translation to the <MyLanguage>Translation topic and ask for someone to commit your changes for you.

Tracking changes and keeping translations up-to-date

From times to times, you must update your working copy to synchronize with the development code:

$ cd Foswiki-locale/
$ svn update

This will update your working copy with the latest version of the translation files, and probably it will add new strings to be translated. Strings already translated are preserved.

Translating

To create your translation file, edit your newe PO file with a text editor (or with one of the helper tools listed below, writing your translations following the msgstr keyword.

File format

Foswiki translations uses extended PO format. Here is an abstract for this format. Examples ilustrate a Portuguese translation (although not all the strings are real).

• An PO file has a sequence of msgid/msgstr pairs. The msgid indicates the original string. The msgstr is where you have to write your translation. Example:
  msgid "Edit"
msgstr "Editar"
• Each string can have parameters, identified by a percent sign and a number. Your translation must keep the logic between them. Example:
  msgid "The %1 topic in the %2 web"
msgstr "O tópico %1 na web %2"

Translations marked as "fuzzy" are not used, you must remove the "fuzzy" tag after reviewing the translation. See UserInterfaceInternationalisation#Generating_the_PO_files for details.

Attention: Foswiki translation files must be encoded in UTF-8 !

Helper tools

These tools can be used to ease the translation process for people that are not used to doing translations by hand-editing the PO files with a text editor.

• Gtranslator
• KBabel
• poEdit
• LocFactory Editor (Mac OS X)

Checking your translation

Use the following command to check your translation:

msgfmt --statistics --output=/dev/null <your_language>.po

This will output the number of translated, unstranslated and fuzzy strings. See man msgfmt for details (msgfmt is part of GNU gettext).

Adding your translation to Foswiki

If you are creating a new translation for Foswiki, you can do the following to test your just created translation:

• add your translation file to the locale/ directory. It must end up as locale/language.po
• alter lib/LocalSite.cfg, adding a line like this:
  • $Foswiki::cfg{Languages}{language}{Enabled} = 1;
• attach your translated PO file to Tasks.Item9526 so that a developer can add the translation to the official Foswiki distribution.

If you are a developer adding a new translation to the SVN repository, you must do the following:

• add the translation file to the locale/ directory. It must end up at locale/language.po
• alter lib/Foswiki.spec and add a line like this:
  • $Foswiki::cfg{Languages}{language}{Enabled} = 1;
• add translator credits to data/System/FoswikiHistory.txt

Keeping your translation up-to-date

For sync'ing your language for a FoswikiRelease? , please follow the following procedure:

1. Download the latest translation files:
   svn checkout http://svn.foswiki.org/trunk/core/locale/
   Alternatively, if you have already checked a copy of the repository, you can update it:
   cd locale/
svn update
   
2. update the locale/YOUR_LANGUAGE.po file, using your preferred tool or any regular text editor supporting UTF8.
3. Attach the patch (the YOUR_LANGUAGE.po file) to Tasks.Item9526

For translators that are also developers (with commit rights do the SVN repository branch), just svn up and commit your updates. Assign it to Tasks.Item9526.

Coordination of the translation process

See TranslationProcess

-- Contributors: AntonioTerceiro, SteffenPoulsen, RichardDonkin, AndreUlrich