TopicTranslationsPlugin

TopicTranslationsPlugin manages topics translations into several languages, by assigning suffixes to topic names corresponding to known languages. TopicTranslationsPlugin also automatically redirects users to the best available translation, based on the languages available and the languages informed as acceptable by the user.

Syntax Rules

Each web that is going to use TopicTranslationsPlugin must define a variable named %TOPICTRANSLATIONS%, which must contains a comma-delimited list of language code. %TOPICTRANSLATIONS% can be defined system-wide, which means that those languages will be used for the entire site. It can also be defined per user. If none of the above is set, the plugin setting for TopicTranslationsPlugin with the same name (%TOPICTRANSLATIONS%) will be used as a default.

For example:

   * Set TOPICTRANSLATIONS = pt-br, en, fr

TopicTranslationsPlugin will then use suffixes in the topic names to "recognize" each topic's translations. In the example above, the translations for, say, SomeTopic, will be the following:

• SomeTopic will be the original version (assumed to be written in pt-br)
• SomeTopicEn will be the 1^st translation (in en)
• SomeTopicFr will be the 2^nd translation (in fr)

Important: we'll assume that the first language listed in %TOPICTRANSLATIONS% is the default one. Thus, the topics with no language suffixes are assumed to be written in that language.

Follows the plugin's available tags, along with examples of their usage.

%TRANSLATIONS{}%

List a topic's translations, even if they don't exist yet (so we can create them!)

Parameters for %TRANSLATIONS{}% :

• "MyTopic" or topic="MyTopic": indicates the topic that must have translations listed. Can be "MyTopic" or "Web.MyTopic". Defaults to the current topic.
• format="..." : provides a custom formatting for the list of available translations. This format will be used for each available language. The following variables will be expanded in the format:

  $language	The language code for the current language.
  $topic	The topic whose translations we are listing.
  $translation	the topic corresponding to the current translation.
  $web	the web containing the translations

  Defaults to "[[$web.$translation][$language]]"
• missingformat: like format, but used for translations that were not written yet. Supports the same variables as format and defaults to the same value of format.
• separator="..." : text that will separate the items in the listing. Defaults to " " (a space)
• which="...": controls which translations must be listed. Possible values are:

  available	lists only the available translations (i.e., those who were already written).
  missing	lists only the missing translations (i.e., those who weren't written yet).
  all	lists all the translations

  The default value is "all".

%CURRENTLANGUAGE%

The language detected for the current topic (based on the current topic's name suffix).

%CURRENTLANGUAGESUFFIX%

The language suffix of the current topic (empty if the current topic is in the default language, since the default language has not suffix). This is useful in menus to create links to fixed topics in the current language. Example:

  <a href="%SCRIPTURL{view}%/%WEB%/SomeTopic%CURRENTLANGUAGESUFFIX%"></a>

%DEFAULTLANGUAGE%

The default language (i.e., the first of the listed in %TOPICTRANSLATIONS%)

%INCLUDETRANSLATION{SomeTopic}%

Includes the translation of SomeTopic that is in the same language as the current topic (as detected based on current topic's name suffix)

Parameters for %INCLUDETRANSLATION{}% :

• "MyTopic" : include the suitable MyTopic translation. Can be "MyTopic" or "Web.MyTopic".
• rev="1.2" : include the topic's revision 1.2 (for example). Defaults to the current revision.

The initial motivation for this tag is to include a suitable menu, for example, based on current topic's language. But there are several other possibilities.

%BASETRANSLATION{...}%

Expands to the name of the original topic (the one we are translating), i.e. the name of current topic without any language suffix.

Parameters supported:

• topic="MyTopic": find base translation for MyTopic instead of current topic.

%TRANSLATEMESSAGE{...}%

Displays the correct version of some text according to the language of the current topic. Example:

%TRANSLATEMESSAGE{en="English" pt-br="Português"}% display English when in the English version of a topic, and Português when in the Brazilian Portuguese version.

It's useful when used in conjunction with a view VIEW_TEMPLATE setting or some similar way of making user-editable custom layouts (like the obsolete FreeSkin?), or even site-specific custom skins.

Warnings:

• This tag is a workaround for sites that want to display user-written different translations of some text based on the current topic's language, while Foswiki does not provide a standard way to do that in its core.
• This tag is also somewhat conflicting with core's %MAKETEXT{}%. The difference is that MAKETEXT uses the system-detected language (e.g. detected from the browser, or set explicitly by the user) and TRANSLATEMESSAGE uses TopicTranslationsPlugin-detected language (detected from the topic name), which may be different in some casse.

Automatic Redirection

TopicTranslationsPlugin is capable of automatically redirecting to the available translation best suited to the user's language. Once TopicTranslationsPlugin is installed, this will happen by default.

• User's language is detected according to the REDIRECTMETHOD preference:
  • if REDIRECTMETHOD is http, then the Accept-Language header sent by the user agent (the browser, most of the times) is used by I18N::AcceptLanguage Perl module to detect the language.
  • if REDIRECTMETHOD is user, then the "LANGUAGE" user preference is used as the preferred language.
• The user won't be redirected:
  • during an action other than view and viewauth (of course)
  • if the user came from a link in another translation of the same topic.
  • if the user came from an edit script.
  • Note: the two later cases are detected by the Referer header sent by the user agent.

Disabling automatic redirection

The automatic redirection can be disabled by setting the TopicTranslationsPlugin's preference flag DISABLE_AUTOMATIC_REDIRECTION (i.e., setting its value to something different from no, off and 0).

Examples

Plugin Settings

Plugin settings are stored as preferences variables. To reference a plugin setting write %<plugin>_<setting>%, i.e. %INTERWIKIPLUGIN_SHORTDESCRIPTION%

• One line description, is shown in the TextFormattingRules topic:
  • Set SHORTDESCRIPTION = Manages a topic's translations into several languages.

• Debug plugin: (See output in data/debug.txt)
  • Set DEBUG = 0

• Whether automatic redirection must be disabled or not. Set to yes to disable.
  • Set DISABLE_AUTOMATIC_REDIRECTION = no

• List of available languages:
  • Set TOPICTRANSLATIONS = en, pt-br

• Method used for detect language when redirecting (See "Automatic Redirection" above):
  • Set REDIRECTMETHOD = http

Plugin Installation Instructions

Note: You do not need to install anything on the browser to use this plugin. The following instructions are for the administrator who installs the plugin on the server where Foswiki is running.

• Download the ZIP file from the Plugin web (see below)
• Unzip TopicTranslationsPlugin.zip in your Foswiki installation directory. Content:

  data/System/TopicTranslationsPlugin.txt	NEW
  lib/Foswiki/Plugins/TopicTranslationsPlugin.pm	NEW

• Visit configure in your Foswiki installation, and enable the plugin in the {Plugins} section.
• Test if the installation was successful:
  • see the examples above

Plugin Info

Related Topics: DefaultPreferences, SitePreferences, Plugins

-- Foswiki:Main.AntonioTerceiro - 21 Jul 2009