%META:TOPICINFO{author="SergejZnamenskij" date="1156669353" format="1.1" version="1.39"}%
---+!! 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>&lt;plugin&gt;_&lt;setting&gt;%==, 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 = <Cyr> = ru,ua,bg; <Lat> = !ru,ua,bg; <Any> = !
</verbatim>
   * Debug plugin: (See output in =data/debug.txt=)
      * Set DEBUG = 0

---++ Plugin Installation Instructions
o 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: | &copy; 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 -->&nbsp; |
|   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

%META:TOPICMOVED{by="SergejZnamenskij" date="1156585538" from="TWiki.PolyglotPlugin" to="TWiki.ForUserLanguagesPlugin"}%
