ForUserLanguagesPlugin < TWiki

---+!! ForUserLanguagesPlugin
 ForUserLanguagesPlugin used to insert full or partial translations and keep them in the original topic. 
%TOC% 
---++ Why to keep translation in the same topic?
 There are [[http://twiki.org/cgi-bin/view/Codev/LocalizationFramework][two official ways]] of TWiki internationalisation: [[http://twiki.org/cgi-bin/view/Codev/TranslationSupport][Support for translated topics]] and [[http://twiki.org/cgi-bin/view/Codev/UserInterfaceInternationalisation][Support for translated strings in code]]. Nevertheless, there are valuable reasons to keep several translations in the same topic in sites where to keep information up-to-date is more important than to provide full translation: 
   * It is much more easy to check and keep consistency when update: 
      * Code fragment, image or some other language independent content will be rendered from the unique source fragment and it will be immediately automatically updated in all needed languages simultaneously. 
      * Fragments deletion and moving will also be easily done in all translations together 
      * User see the translations while editing and can replace or mark outdated some translations of editing paragraph. 
   * Sometimes possibility to keep partial translations in original language (i.e. leave in original language some less actual notes, unnecessary explanations, examples, comments etc.) may save a lot of time for a really usefull work. 

---++ Syntax Rules
 There are predefined translation switch to separate contents for different user language, and they are fully customisable. 
---+++ Predefined translation switch
 Plugin introduce the one new variable %<nop>FORUSERLANGUAGES{}%.

The variable must have an argument either
   * the comma separated list of user language codes 
 or 
   * the same list prepended with negation exclamation mark '!'. 
 The text between two %<nop>FORUSERLANGUAGES{}% will disappear if and only if current user <nop>%LANGUAGE% is not in list or it is in list after the exclamation mark.

---++++ Example

=%<nop>FORUSERLANGUAGES{ru,ua,bg}%=

_The part of the topic in Russian_ (for users who prefer Cyrillic text)

=%<nop>FORUSERLANGUAGES{!<nop>ru,ua,bg}%=

_The same part of the topic in English_ (translation for other users)

=%<nop>FORUSERLANGUAGES{!}%=

Language independent or untranslated data comes here.

=%<nop>FORUSERLANGUAGES{!<nop>ru,ua,bg}%=

_The next part of the topic in English again_ (only for non-Cyrillic users)

---+++ Using shortcut aliases example

Compare the code
<verbatim>
<Cyr> Russian version of the text fragment <Lat> English version of the same 
fragment <Any> Common part <Cyr> Russian <Lat> English <Any> version of the next fragment ...
</verbatim> and the rendering result:

<Cyr> Russian version of the text fragment <Lat> English version of the same fragment <Any> Common part <Cyr> Russian <Lat> English <Any> version of the next fragment ...

---++ Plugin Settings

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

   * One line description, is shown in the %TWIKIWEB%.TextFormattingRules topic: 
      * Set SHORTDESCRIPTION = used to insert full or partial translations and keep them in original topic. 

   * Shortcut aliases for any translation switches may be defined via the variable FORUSERLANGUAGESALIASES, which contains the semicolon separated list of aliases. Example above use the following setting in <nop>Main.TwikiPreferences 
 <verbatim>
      * Set FORUSERLANGUAGESALIASES = <ru> = ru,ua,bg; <en> = !ru,ua,bg; <any> = !</verbatim> 
   * Debug plugin: (See output in =data/debug.txt=) 
      * Set DEBUG = 0 

---++ Plugin Installation Instructions
 %u0444o install plugin:

* Unzip the archive to the top of your directory

---+++ Test Plugin Installation

You will see below correct information about user selected language if the plugin has been properly installed.
| %FORUSERLANGUAGES{en}%Default language en (English) %FORUSERLANGUAGES{!en}%Custom language %LANGUAGE%%FORUSERLANGUAGES{!}% selected. |

---++ Plugin Info
|  Plugin Author: | TWiki:Main.SergejZnamenskij |
|  Copyright: | © 2006, %TWIKIWEB%.TWikiContributor |
|  License: | GPL ([[http://www.gnu.org/copyleft/gpl.html][GNU General Public License]]) |
|  Plugin Version: | 26 Aug 2006 |
|  Change History: | <!-- versions below in reverse order --> |
|  26 Aug 2006: | Initial version |
|  TWiki Dependency: | $TWiki::Plugins::VERSION 1.1 |
|  CPAN Dependencies: | none |
|  Other Dependencies: | none |
|  Perl Version: | 5.005 |
|  TWiki:Plugins/Benchmark: | %TWIKIWEB%.GoodStyle 99%, %TWIKIWEB%.FormattedSearch 99%, %TOPIC% 99% |
|  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%.TWikiPlugins, %TWIKIWEB%.DeveloperDocumentationCategory, %TWIKIWEB%.AdminDocumentationCategory, %TWIKIWEB%.TWikiPreferences

-- %TWIKIWEB%.TWikiContributor 25 Aug 2006
This topic: TWiki > ForUserLanguagesPlugin
Topic revision: r2 - 2008-02-07 - 15:09:23 - IlyaDanilov
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
Note: Please contribute updates to this topic on TWiki.org at TWiki:TWiki.ForUserLanguagesPlugin