TWiki

MultiLangPlugin

Some useful stuff for providing several distinct TWiki sites with the
same content but in different languages.

Concepts and Design

This plug-in was developed to be able to maintain a web page in two
different languages. It assumes to distinct TWiki installations
which share both a common location in the host's file system and
a common path as seen from the web server. These should only differ
by their language name (e.g. file system
/var/www/twiki/lang/{bin,data} and URL /lang/bin/).
So all the plug-in needs to know is which language a certain TWiki has
(set by WIKILANG below) and where to replace lang in a
given path. You can define templates for this in the Plugin settings
(see below), #LANG# is used as the string to substitute. In the
most common configurations, the plug-in should be able to guess them
by itself given WIKILANG is set correctly.

Concepts that aren't implemented yet/Limitations

Patches welcome

Sometimes it is useful to use different representations of a language's name (e.g. en, English, Englisch (the name of the English language in German)). It would be good (and certainly not too complicated) to allow users to define those mapping with a table in a certain Topic.

To obtain information about topics in other languages the plug-in uses direct access over the file system rather than TWiki::Func (i.e. TWiki::Store) which would be way more flexible. However, because of the many global variables TWiki uses it isn't easy to instantiate two different Store objects for entirely different TWikis and to do it through a wrapper program is probably much, much slower than the current solution which just works for the default configuration.

Theoretically it would be nice to be able to use the same TWiki for all languages (e.g. with a custom TWiki::Store implementation). The lack of real L10N support in templates (i.e. something like gettext) is a big problem for such a solution, though.

The complete URL/path part is grown out of some confusion at my side which sources of information to use. I (or someone else) need to take a deep look at that again. (e.g. should it also try to use TOPICURL). I have also generally ignored the possibility that SCRIPTSUFFIX = "", so this is probably horribly broken.

Interaction with other Plug-ins

If you want to use the FindElsewherePlugin? and the WikiWord expansion
of MultiLangPlugin (%FINDINOTHERLANGS%) you should define a
certain order for calling them both depending on your preferences
(i.e. if you would like to get linked WikiWords to other webs or
other languages if both is possible).

Syntax Rules

MultiLangPlugin introduces the following new variables that are
intended to be used in templates:

%TRANSLATIONS%; will be expanded to a list of available translations of the current topic

%TRANSLATIONCHECK%; if a topic includes the TranslationFormTWikiMetaData, you can use this variable to display a note depending on whether the translation is up-to-date or outdated. Which note to display in what situations is greatly configurable, see below in section Plugin Settings. This part of the plug-in is greatly inspired by the translation system of the Debian website.

%MLP_DATADIRFORM%, %MLP_SCRIPTURLFORM%, %MLP_SCRIPTPATHFORM%; these give you access to the path variables the plug-in uses internally to compute links and file paths. You probably will never need these, except for debugging purposes.

%MLP_USEFORM{ "formname" lang="language" }%; this gives you the ability to produce links and file paths the same way the plug-in does. See section Installation Instructions for an example of its use.

The plug-in also provides some new auto-linking abilities:

WikiWords can be linked to other languages if the topic in question doesn't exist in the current language. This works similar to the FindElsewherePlugin? and some code is borrowed from there.

You can specially request to link a WikiWord to another language by preceding it with the language and a colon (e.g. de:TWiki.WebHome). This is inspired by the InterwikiPlugin.

Skinning support (CSS)

I've tried to hardcode almost nothing into the output the plug-in produces.
All produces links have the class translationLink and a correctly set
lang attribute. This should you to develop complex layouts by using CSS.

Just a quick example: to display a German flag before any link that
links to a German translation use the following CSS