Translation Support

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

This topic documents support for topic translations. Look at #See_also for other types of I18N features.

Introduction

The process is documented in UserInterfaceLocalisation. There are several efforts to translate TWiki documentation to languages other than english:

It would be interesting to make possible to show the documentation (mainly TWiki04x02 web topics) in the user's mother language. More generally, it would be even better being able to list available translations for each topic.

TWiki already supports UserInterfaceLocalisation. Now it's time to support DocumentationTranslation

One initial try in that direction is TopicTranslationsPlugin. Altough it does its job, restricting topic names as it requires isn't a good thing.

Translation Support Specification

• translated topic names (more readable for non-English users)
• clear separation between topic name and language name
• translated topics may go into different webs (languages get easily pluggable through adding webs)
• remember original topics revision number in translated topic (to keep translations in sync)

The best place for that meta data would be a META-field. Since there is no easy way to manipulate meta data (apart from implementing a specialised user interface) I propose the use of FORM-fields in the first stage.

A possible TranslationForm may look like this:

The next stage would be a conversion to something like:

%META:TRANSLATION{origin="Web.OriginalTopic" language="de" revision="13"}%

To show all avaiable languages of a specific topic, WebLeftBar can be augmented with this simple SEARCH:

%SEARCH{
  search="FORM.*name\=.*TWiki.TranslationForm" 
  topic="%INCLUDINGTOPIC%" 
  web="%INCLUDINGWEB%" 
  scope="text" 
  nosummary="on" 
  nototal="on" 
  nosearch="on" 
  type="regex" 
  header="----$n   * <b>Languages</b>" 
  format="$percntSEARCH{ 
    search=\"FORM.*name\=.*TWiki.TranslationForm;FIELD.*name\=.*Origin;value\=.*$formfield(Origin)\" 
    web=\"all\" 
    regex=\"on\" 
    scope=\"text\" 
    nosearch=\"on\" 
    nototal=\"on\" 
    format=\"<a href='$dollartopic'><img src='%PUBURL%/%TWIKIWEB%/TWikiDocGraphics/flag_$dollarformfield(Language).png' width='21' height='14' border='0'></a>\"
  }$percnt"
}%

Example in the Sandbox-Web: Sandbox.EnglishPage1

Since a translation may go into a different web, I propose one web per language

• named TWiki_de, TWiki_es, TWiki_fr and so on (maybe we have to allow underscores in web names for that)
• as long as a topic is not yet translated, referring topics link to the english version as fallback
• there will be a topic named TranslationStatus? in each language web with
  • a list showing translated topics and their revisions (to get the translation in sync to the origin)
  • a list of not yet translated topic.
• language packs can be shipped as zip files
• localized templates refer to the translated topics (if available)

Things to think about

• rewrite the above specification considering storing translation information as meta-data.
• think on the UI for handling topic translations:
  • Creating a translation for an existing topic
  • Telling that the current topic is a translation of some other topic
  • updating translation data, like the revision of the original topic corresponding to the current translation.

See also

• UserInterfaceInternationalisation
• UserInterfaceLocalisation

-- Contributors: AntonioTerceiro, OliverKrueger, ChristianKohl, CrawfordCurrie, FrancoisGranger, FrancoisGranger, KarlheinzNolte, MarioFrasca, MartinCleaver, PatrickHansmeier, PeterThoeny, RichardDonkin, RichardDonkin, SamHasler, SvenDowideit, WillNorris, ZbigniewKulesza.

Discussion

note: see Bugs:Item1395. Maybe other components could use this infrastructure to pick the right version of topics for certain uses (e.g. NewUserTemplate).

-- AntonioTerceiro - 13 Jan 2006

I did not get the thing with translations going into different webs. But nevertheless - I will start translating some pages from the english original to spanish and link them to SpanishTranslation. In general, a list of the most important topics that have to be translated would be helpful.

-- SebastianKlus - 13 Mar 2008

Now I got the thing with the translations going into different webs And I like this idea as it leaves it up to every administrator to add a TWiki-language web or not.

Apart from that, I propose the use of flags in the translated topic to clearly mark references to topics that have not been translated yet. You can check it out at TWikiWebHome? . It is the spanish translation for TWiki.

-- SebastianKlus - 27 Apr 2008

Please refer to TranslationNote to see a possible solution for the previously discussed item.

-- SebastianKlus - 02 May 2008

Let's stick a moment to the proposed idea to include translated topics in a separate web, e.g. having a translated TWiki documentation. Technically, how could this be implemented? Like some kind of TWikiExtension? I tried to read into it but my IT-knowledge does not get so far and I already get stuck when the differences between Plugins, Addons and Contribs are discussed (see ReadmeFirst). On the other side I would like to make some experiments with what I translated and how it might work. Maybe someone can give me some help. Thanks.

-- SebastianKlus - 22 May 2008

I like to initialize a DocumentationTranslation by using the TopicTranslationsPlugin from AntonioTerceiro. There are some features missing, but it is a great start and we can improve while we are in the process later on. I already asked Peter to install the plugin.

-- AndreUlrich - 19 Jun 2008

André: I know that the following has more to do with Support, but I tried to install the plugin on Windows & Linux according to the instructions, but although activated in configure, the examples do not work. Did you accomplish to install it on another system?

-- SebastianKlus - 23 Jun 2008

Sebastian, I installed it from SVN on our Linux server TWiki 4.2 and it works like expected. Did not hear anything from Peter yet, maybe he also got problems?

-- AndreUlrich - 25 Jun 2008

Andre, I have it running to now. You have to make sure that the perl module I18N::AcceptLanguage is installed on your system. Worst is: It says so on the plugin-page. Shame on me!

-- SebastianKlus - 08 Jul 2008

I know it the following issue has been discussed previously, but if I understand correctly, the TopicTranslationsPlugin does not support translations of the topic title. But I believe this is important because it is of no use if a not english speaking person does have to go through english titles until finding a corresponding document.

I would therefore appreciate some additional feedback before starting off on the translations itself. In my personal opinion, I believe that the approach of Antonio's initial proposal (see above on this page or see rev. 36) is more user-friendly than using the TopicTranslationsPlugin, although it might request additional effort and configuration / implementation is not so easy.

-- SebastianKlus - 08 Jul 2008

Fine that you now have it running

Regarding the Topic names: This is just for the initial translation and should not the solution for time being. My intention is rather starting quickly and actually getting some translation done as looking for the perfect solution where additional programming is necessary for the first step. Renaming the topics later on will not be that hassle in my opinion.

More important is, that I looked over the existing documentation and find it in a rather bad state. I would like to hear opinions from translators on this issue before translation gets started.

-- AndreUlrich - 10 Jul 2008

Regarding the topic names, I agree to the extend that the possibility of translating them should be within the top 10 of the to-do-list

Regarding the state of the documentation, I believe that it basically reflects a TWiki that did not have a WYSIWYG-frontend for editing. So most of the documentation is still valid, but excludes the features that were added some time ago. And those features are the ones that especially new users will handle first.

-- SebastianKlus - 10 Jul 2008