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 1st translation (in en
)
-
SomeTopicFr
will be the 2nd 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 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
Preference Settings
The following settings may be used in your WebPreferences or SitePreferences.
- 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
Installation Instructions
You do not need to install anything in the browser to use this extension. The following instructions are for the administrator who installs the extension on the server.
Open configure, and open the "Extensions" section. Use "Find More Extensions" to get a list of available extensions. Select "Install".
If you have any problems, or if the extension isn't available in
configure
, then you can still install manually from the command-line. See
http://foswiki.org/Support/ManuallyInstallingExtensions for more help.
Info
Author: |
Foswiki:Main.AntonioTerceiro |
Copyright: |
Copyright © 2005-2010, Foswiki:Main.AntonioTerceiro |
License: |
GPL (GNU General Public License) |
Release: |
2.00 |
Version: |
2.00 |
Change History: |
|
01 Feb 2013 |
modernized and fixed plugin: added use strict; use warnings and fixed several non-declared variables; using proper macro registration instead of commonTagsHandler; fixed DEFAULTLANGUAGE not working properly; cut down a few global variables; removed feature to specify preference variables in plugin topic; lazy-load I18N::AcceptLanguage for better performance; fixed plugin redirecting when using short urls and/or lighttpd; fixed inconsistencies while processing params (i.e. the topic one), and make better use core of apis; don't issue a redirect when calling foswiki from the command line |
10 Oct 2010 |
Documentation editing. -- Foswiki:Main.WillNorris |
15 Jun 2010 |
(1.0) New release. Fixed Foswiki:Tasks/Item9162 and Foswiki:Tasks/Item8653 |
09 Feb 2009 |
New release. Fixed redirection when coming from a topic in the same language as the current one. |
21 Jul 2009 |
New release, porting to Foswiki. Foswiki:Tasks/Item5692 is fixed; added new TRANSLATEMESSAGE macro. |
23 Sep 2006 |
New %TRANSLATEMESSAGE{}% tag; thanks to Carla Freitas for the idea. Improvements to the plugin topic; thanks to Peter Thoeny. |
04 Sep 2006 |
new version released. Added patch from Beomsu Chang for flexible language detection; thanks for Foswiki:Main/JoenioCosta for remembering me I should release a new version. |
03 Jul 2005 |
(1.003) fixed to redirect only during view=/=viewauth |
02 Jul 2005 |
(1.002) major rewrite; documented all (or almost all :)) the code; added selection of available/missing translations; added missingformat ; added support for custom topics (and webs) in %TRANSLATIONS% ; added automatic redirection for the "best" translation (detection via I18N::AcceptLanguage ). |
19 Jun 2005: |
(1.001) Initial version |
Dependencies: |
Name | Version | Description |
---|
I18N::AcceptLanguage | >=0 | Required | |
Home page: |
Foswiki:Extensions/TopicTranslationsPlugin |
Support: |
Foswiki:Support/TopicTranslationsPlugin |