TopicTranslationsPlugin < TWiki/

---+!! !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.


%TOC%

------

---++ Syntax Rules

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

For example:

<code>&nbsp;&nbsp;&nbsp;* Set TOPICTRANSLATIONS = pt-br, en, fr</code>

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

   * =<nop/>SomeTopic= will be the original version (assumed to be written in =pt-br=)
   * =<nop/>SomeTopicEn= will be the 1<sup>st</sup> translation (in =en=)
   * =<nop/>SomeTopicFr= will be the 2<sup>nd</sup> translation (in =fr=)  

__Important:__ we'll assume that the first language listed in =%<nop/>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.

---+++ =%<nop/>TRANSLATIONS{}%= 

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

Parameters for =%<nop/>TRANSLATIONS{}%= :

   * <code>"MyTopic"</code> or <code>topic="MyTopic"</code>: indicates the topic that must
     have translations listed. Can be ="MyTopic"= or ="Web.MyTopic"=.
     Defaults to the current topic.
   * <code>format="..."</code> : 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]<nop/>[$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=.
   * <code>separator="..."</code> : text that will separate the items in the listing.
     Defaults to =" "= (a space)
   * <code>which="..."</code>: 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"=.

---+++ =%<nop/>CURRENTLANGUAGE%=

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

---+++=%<nop/>DEFAULTLANGUAGE%= 

The default language (i.e., the first of the listed in =%<nop/>TOPICTRANSLATIONS%=)

---+++ =%<nop/>INCLUDETRANSLATION{<nop/>SomeTopic}%=

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

Parameters for =%<nop/>INCLUDETRANSLATION{}%= :

   * ="<nop/>MyTopic"= : include the suitable =<nop/>MyTopic= translation. Can be
     ="<nop/>MyTopic"= or ="<nop/>Web.MyTopic"=.
   * <code>rev="1.2"</code> : 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.

---+++ =%<nop/>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:

   * <code>topic="<nop/>MyTopic"</code>: find base translation for <code>MyTopic</code> instead of
     current topic.

---+++ =%<nop/>TRANSLATEMESSAGE{...}%=

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

=%<nop/>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 conjuntcion with a view VIEW_TEMPLATE setting or some
similar way of making TWiki-editable custom layouts (like the obsolete
TWiki:Main/FreeSkin), or even site-specific custom skins.

%RED% __Warnings:__ %ENDCOLOR%

   * 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 TWiki does not provide a standard way to do that in its core (what
     is mainly [[TWiki:Main/AntonioTerceiro][my]] fault).
   * This tag is also somewhat conflicting with core's %<nop/>MAKETEXT{}%. The
     difference is that MAKETEXT uses TWiki-detected language and
     TRANSLATEMESSAGE uses !TopicTranslationsPlugin-detected language, 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 REDIRECT_METHOD preference:
      * if =REDIRECT_METHOD= 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 =REDIRECT_METHOD= 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= (off 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=).

__Note:__ in TWiki:Codev/CairoRelease, to make this work you'll have to apply the
following patch to =TWiki/Func.pm= module (got from TWiki's Subversion repository): 

<verbatim>
--- /var/lib/twiki/lib/TWiki/Func.pm    2005-07-02 13:33:46.893777128 -0300
+++ Func.pm     2005-07-02 13:37:22.187047576 -0300
@@ -407,8 +407,9 @@
 sub getPluginPreferencesFlag
 {
     my( $theKey ) = @_;
-    my $value = getPluginPreferencesValue( $theKey );
-    return TWiki::Prefs::formatAsFlag($value);
+    my $package = caller;
+    $package =~ s/.*:://; # strip off TWiki::Plugins:: prefix
+    return TWiki::Prefs::getPreferencesFlag( "\U$package\E_$theKey" );
 }

 # =========================
</verbatim>

---++ Examples

| *Test* | *Actual test(work if the plugin is installed)* |
| %<nop/>TRANSLATIONS% | %TRANSLATIONS% |
| %<nop/>TRANSLATIONS{format="[[$translation]<nop/>[$language translation]]" separator=", "}% | %TRANSLATIONS{format="[[$translation][$language translation]]" separator=", "}% |
| %<nop/>CURRENTLANGUAGE% | %CURRENTLANGUAGE% |
| %<nop/>DEFAULTLANGUAGE% | %DEFAULTLANGUAGE% |

---++ Plugin Settings

Plugin settings are stored as preferences variables. To reference a plugin setting write ==%<nop>&lt;plugin&gt;_&lt;setting&gt;%==, i.e. ==%<nop>INTERWIKIPLUGIN_SHORTDESCRIPTION%==

   * One line description, is shown in the %TWIKIWEB%.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):
      * REDIRECT_METHOD = 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 TWiki is running. 

   * Download the ZIP file from the Plugin web (see below)
   * Unzip ==%TOPIC%.zip== in your twiki installation directory. Content:
     | *File:* | *Description:* |
     | ==data/TWiki/%TOPIC%.txt== | Plugin topic |
     | ==data/TWiki/%TOPIC%.txt,v== | Plugin topic repository |
     | ==lib/TWiki/Plugins/%TOPIC%.pm== | Plugin Perl module |
   * (Dakar) Visit =configure= in your TWiki installation, and enable the plugin in the {Plugins} section.
   * Test if the installation was successful:
      * see the examples [[#Examples][above]]

---++ Plugin Info

|  Plugin Author: | TWiki:Main.AntonioTerceiro |
|  Copyright: | &copy; 2006, TWiki:Main.AntonioTerceiro |
|  License: | GPL ([[http://www.gnu.org/copyleft/gpl.html][GNU General Public License]]) |
|  Plugin Version: | 03 Jul 2005 (V1.003) |
|  Change History: | <!-- versions below in reverse order -->&nbsp; |
|  23 Sep 2006 | \
New %<nop/>TRANSLATEMESSAGE{}% tag; thanks to TWiki:Main/CarlaFreitas for the idea. \
Improvements to the plugin topic; thanks to TWiki:Main/PeterThoeny. \
|
|  04 Sep 2006 | new version released. Added patch from TWiki:Main/BeomsuChang for flexible language detection; thanks for TWiki:Main/JoenioCosta for remembering me I should release a new version. |
|  03 Jul 2005 | Version =1.003=: fixed to redirect only during =view=/=viewauth= |
|  02 Jul 2005 | Version =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 <code>%<nop/>TRANSLATIONS%</code>; added automatic redirection for the "best" translation (detection via =I18N::AcceptLanguage=).  |
|  19 Jun 2005: | Initial version: =1.001= |
|  TWiki Dependency: | $TWiki::Plugins::VERSION 1.024 |
|  CPAN Dependencies: | =I18N::AcceptLanguage= |
|  Other Dependencies: | none |
|  Perl Version: | 5.005 |
|  TWiki:Plugins/Benchmark: | %TWIKIWEB%.GoodStyle 100%, %TWIKIWEB%.FormattedSearch 100%, %TOPIC% 100% |
|  Plugin Home: | http://TWiki.org/cgi-bin/view/Plugins/%TOPIC% |
|  Feedback: | http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Dev |
|  Appraisal: | http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Appraisal |

__Related Topics:__ %TWIKIWEB%.TWikiPreferences, %TWIKIWEB%.TWikiPlugins

-- TWiki:Main.AntonioTerceiro - 03 Jul 2005
This topic: TWiki/ > TopicTranslationsPlugin
Topic revision: r1 - 29 Sep 2005 - 17:45:33 - AntonioTerceiro?
Copyright � by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback