User Interface Localisation

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

From TWiki version 4, TWiki uses 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 TWiki.

How can I add a new language to TWiki ?

Adding a new language to TWiki is easy: you just have to make a copy of the translation file template, TWiki.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 TWiki versions, whose strings are frozen, and other for TWiki 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.

Translation topics

TranslationSupport lists the current translation topics:

Language	User Interface	Translator	Backup
Bulgarian	BulgarianTranslation	KrassimirBerov
Chinese	ChineseTranslation simplified and traditional	CheDong
Czech	CzechTranslation	VladimirMarek	JaromirHoudek
Danish	DanishTranslation	ChristianOtkjaer	PeterLorenzen, ErikJohansen, SteffenPoulsen
Dutch	DutchTranslation	WoutMertens	TomArnst
Finnish	FinnishTranslation	HeikkiToivonen
French	FrenchTranslation, Discussion (in french)	JeanbDupont	JeanFruitet, RodolpheVidal
German	GermanTranslation	MartinRaabe
Italian	ItalianTranslation	PaoloTealdi	MassimoMancini
Japanese	JapaneseTranslation, JapaneseTemplateTranslation	HideyoImazu	KenYuminaga
Korean	KoreanTranslation	JeremySuk	JustinKim
Polish	PolishTranslation	ZbigniewKulesza
Portuguese	PortugueseTranslation	CarlinhosCecconi
Russian	RussianTranslation	SergejZnamenskij	AndreyTkachenko, SergeyJSinx
Spanish	SpanishTranslation, Support.TWikiInSpanish	EnriqueMelendez	SebastianKlus, MiguelABayona
Swedish	SwedishTranslation	TorstenEriksson	ErikAman
Ukrainian	UkrainianTranslation	TWiki:Main.SerhijDubyk

Starting in TranslationSupport, please create a new <MyLanguage>Translation topic to coordinate the translation of your language.

Released versions

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

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 TWiki's locale directory using:

svn checkout http://svn.twiki.org/svn/twiki/trunk/core/locale/ TWiki-locale/

This will make a local working copy of TWiki's locale/ directory in Subversion, named TWiki-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 TWiki'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 TWiki-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

TWiki 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: TWiki 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).

-- AntonioTerceiro - 09 Oct 2005

Adding your translation to TWiki

If you are creating a new translation for TWiki, 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:
  • $TWiki::cfg{Languages}{language}{Enabled} = 1;
• attach your translated PO file to Bugs:Item6712 so that a developer can add the translation to the official TWiki 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/TWiki.spec and add a line like this:
  • $TWiki::cfg{Languages}{language}{Enabled} = 1;
• add translator credits to data/TWiki/TWikiHistory.txt

Keeping your translation up-to-date

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

1. Download the latest translation files:
   svn checkout http://svn.twiki.org/svn/twiki/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 Bugs:Item6712

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

Current translation status

(autogenerated)

NOTE: Don't use, this is out of date data!
Language	Translated	Fuzzy	Unstranslated	% translated
bg	522	25	190	70%
cs	566	111	60	76%
da	737	0	0	100%
de	737	0	0	100%
es	737	0	0	100%
fi	261	12	464	35%
fr	731	6	0	99%
it	731	6	0	99%
jp	699	0	38	94%
nl	731	6	0	99%
pl	624	76	37	84%
pt	737	0	0	100%
ru	618	78	41	83%
sv	731	6	0	99%
uk	653	12	72	88%
zh-cn	730	7	0	99%
zh-tw	730	7	0	99%

Coordination of the translation process

See TWikiTranslationProcess

Translation-related topics

Searched: translation

Results from Codev web retrieved at 21:00 (GMT)

-- Contributors: AntonioTerceiro, SteffenPoulsen, RichardDonkin

---

---

Good documentation, have made a few tweaks above.

-- RichardDonkin - 01 Oct 2005

I just created FrenchTranslation as reference for easier linking and summarizing of the French translation efforts.

-- FabianRodriguez - 02 Jan 2006

How is the translation of documentation and Wikipages tackled? I can see that there are many pages that should be available in your local language (for example the formatting notes etc.). I tried finding information on this in the GermanTranslation topic, but all seems quite outdated...

-- PeterLohmann - 10 Jan 2006

It isn't, currently. There have been several strategies discussed, though no firm conclusions yet.

-- CrawfordCurrie - 10 Jan 2006

These things (topics) are not being translated for now. For EdinburghRelease we'll figure out a way of doing that.

-- AntonioTerceiro - 10 Jan 2006

I thought topics (or parts of it) are already translated using the

%MAKETEXT{""}%

commands... As I will be doing this work anyway (I need the translated pages) do you want them for integration in the upstream versions?

-- PeterLohmann - 10 Jan 2006

MAKETEXT is intended to provide translation infrastructure for user interface elements (which is the case of some topics and templates).

The problem is that translating PO files is much harder and has larger possibility of errors than translating regular text. If every piece of text in a topic would be inside a %MAKETEXT{}%, it would be much better if we could just translate all the topic without dealing with PO files.

That's why the design decision for Dakar was to internationalise with MAKETEXT only user interface elements, and postpone all documentation-related internationalisation to EdinBurgh. TranslationSupport sketches the basic idea of how it is going to be. Of course that if you already have translated some topics, I'm sure they will be helpful.

-- AntonioTerceiro - 10 Jan 2006

I'm using the /twiki/bin/configure to install the new beaultifull localized TWiki, but now I need to put some letter in this variables:

• UpperNational
• LowerNational

I think, i know this, but i (or someone) can forgot some letter...

Can the values come on an <Select> for some languages? Or, if not, where is the best place on TWiki.org to put this values?

-- AurelioAHeckert - 16 Jan 2006

Why not simply starting here?

-- FranzJosefSilli - 16 Jan 2006

Aurelio, why don't you just use {UseLocaLe} and {LocaleRegexes}? I've certified myself that they do work on Dakar Release (unlike CairoRelease, in which I never could make them work).

-- AntonioTerceiro - 16 Jan 2006

Is there a way of using a time and number format based on the locale (and possibly on a custom setup) that is used? I would like to see Montag, 25. Januar 2005 instead of the autogenerated 25 January 2006.

-- PeterLohmann - 18 Jan 2006

Locale-specific dates aren't supported in TWiki at present. For some discussion of the issues, see UseIsoDates, particularly discussion towards the end which links to TimeZone, TimeFormat, and other relevant discussion.

Also, it's worth noting that customised locale-specific dates are even harder - best to just provide the ingredients and let the user do what they want, like POSIX printf (but note that CPAN:POSIX is not a good route to go for locale-based dates, though it might be OK for a quick hack).

Let's continue discussion over in TimeFormat.

-- RichardDonkin - 30 Jan 2006

Warning: TWiki-4.0.1.tgz does not contain TWiki.pot as told above. I've downloaded TWiki.pot from http://svn.twiki.org/svn/twiki/branches/TWikiRelease04x00/locale/
Below the new attachment it.po with the italian translation

-- MassimoMancini - 19 Mar 2006

Thanks Massimo, much appreciated!

I have made sure that TWiki.pot is included in 4.0.2, thanks for reporting.

Current translation status:

Language	Translated	Untranslated	Fuzzy	Progress
da	653	7	13	97%
de	657	7	9	97%
es	591	40	42	87%
fr	592	39	42	87%
it	653	7	13	97%
nl	651	9	13	96%
pt	592	39	42	87%
ru	753	145	115	74%
zh-cn	592	39	42	87%
zh-tw	592	39	42	87%

To all translators: Translation status for 4.0.2 is tracked at Bugs:Item1787. As we're closing in on a code freeze, I hope you will take a moment soon to update your translations to 4.0.2; some strings have changed since 4.0.1. You can attach updated translations either here or at the Bugs item. Thanks for all your effort!

-- SteffenPoulsen - 19 Mar 2006

For non english users may be important to have some topics available in their language (e.s. FormattingRule, Change/Reset password, ooops templates and so on...). How it can be made? (in a tidy way )

-- MassimoMancini - 20 Mar 2006

I believe this is discussed in TranslationSupport, but there is no supported way of doing this yet. Something to consider for Edinburgh

Just noticed you updated the translation to v1.2, it's committed in.

-- SteffenPoulsen - 21 Mar 2006

should translators be listed in http://svn.twiki.org/svn/twiki/branches/TWikiRelease04x00/AUTHORS as well?

-- WillNorris - 20 Apr 2006

no question. YES!

-- SvenDowideit - 21 Apr 2006

ok, created Bugs:Item2140 to add the credits

-- WillNorris - 21 Apr 2006

Russian Translation 61% 74% for 4.0.2. Please see topic RussianTranslation

-- AndreyTkachenko - 09 Nov 2006

enhancing this documentation as part of work on Bugs:Item3273. Still missing is a refactor of the comments on this topic.

-- AntonioTerceiro - 11 Dec 2006

Thanks Antonio for setting up the automated TWikiTranslationStatus!

-- PeterThoeny - 12 Dec 2006

I just added a patch for 4.1 of the Swedish translation to Bugs:Item2552. The topic SwedishTranslation has been created for documentation and any discussion around this translation.

-- ErikAman - 25 Dec 2006

We are closing in on a new beta release, and it has become time to begin updating translations again (most are at 88% currently / only the japanese translation seems to have some critical problems).

A string freeze has not been officially announced yet, but I have rerun translations in SVN and if anybody wants to start early on their translations they are very welcome to do so (hopefully string updates will be few from now and until release :-)).

On a sidenote, a new release procedure is now used which among other stuff means that at beta release time a branch is made for the release. I will try to keep the two branches in sync best I can with regards to translations, so until further notice please just work in MAIN (those of you with checkin rights) - as usual.

-- SteffenPoulsen - 04 Sep 2007

Just updated this page with information for 4.2 translation. Please note that the preferred way to send translations now is to send the entire PO file, not a patch anymore.

-- AntonioTerceiro - 06 Sep 2007

updated for new svn layout. -- SvenDowideit - 17 Feb 2008