MultiLingualPlugin

Support for a multi lingual Foswiki

This plugin enables you to create wiki content in multiple languages. While Foswiki normally supports over 20 languages to internationalize its user interface, content is not translated in general. All of the standard documentation for Foswiki is shipped in English out of the box. Multi-lingual wikis go beyond pure translation of the user interface. Their main purpose is to maintain the wiki content in multiple languages presenting the matching translation according to the user's language preferences.

This plugin introduces a new macro %TRANSLATE which resembles very much the standard %MAKETEXT macro at first glance. However it adds a lot more flexibility in maintaining translation the wiki way. While %MAKETEXT relies on .po translation files stored somewhere on your Foswiki installation on the file system, translations for %TRANSLATE can be provided as wiki content itself, or inlined as part of the macro call itself. As a last resort will it reuse any translation available in the system's .po lexicon.

Usage

Specifying the target language

The target language to translate strings to can be specified in various ways:

1. use the language parameter to %TRANSLATE,
2. use the CONTENT_LANGUAGE preference variable or
3. default to the user's language settings in the browser

... in the given priority order. Note that you might also use url parameters to configure the output of %TRANSLATE using this code:

%TRANSLATE{"some source text" language="%URLPARAM{"content_language"}%"}%

... or by specifying a wiki application to complute the CONTENT_LANGUAGE preference variable, e.g.

   * Set CONTENT_LANGUAGE = %URLPARAM{"content_language" default="en"}%

Inline translations

Translations can be specified inline:

%TRANSLATE{
  "This here is not a pipe" 
  de="Das hier is keine Pfeife" 
  fr="Ceci n'est pas une pipe"
}%

The macro will return the string matching the selected target language. Note that you might also make use of %INCLUDE to switch to different content maintained somewhere else in your wiki:

%TRANSLATE{
  "$percntINCLUDE{"DefaultText"}$percnt"
  de="$percntINCLUDE{"GermanText"}$percnt"
  en="$percntINCLUDE{"EnglishText"}$percnt"
  fr="$percntINCLUDE{"FrenchText"}$percnt"
}%

Lexicon meta data

To separate the application of translated strings from their translation you might specify a lexicon, either

• using the lexicon parameter to %TRANSLATE or
• using the WEBLEXICON preference variable or
• using the WebLexicon topic in the current web

Multiple lexicons can be specified in the WEBLEXICON preference variable separated by commas. Entries are looked up in the lexicons with the given precedence, that is an entry is returned as found in the first lexicon on the list.

A WebLexicon topic in the current web will allways take highest precedence over all other lexicons listed in WEBLEXICON. It is not required to list it explicitly in the WEBLEXICON prefernce.

Each lexicon is a topic holding %META:LEXICON records as produced by the Foswiki:Extensions/MetaDataPlugin and specified in the LexiconForm shipped with this plugin.

Syntax

TRANSLATE

This is the work horse returning a string based on the selected target language.

Parameter	Description	Default
"string"	(required) the source string to be translated; it serves as a lookup key into the lexicon
language="<lang-code>"	the language code of the target language
lexicon="<topic-name>"	the topic holding the lexicon meta data
args="arg1, arg2, ..."	arguments to be inserted into the translated string
splitargs="<separator>"	expression to separate items in the args list	\s*,\s*
arg<N>="..."	alternative way to specify arguments, e.g. %TRANSLATE{"... " arg1="..." arg2="..." ...}%

A string as well as a translation may contain placeholder such as [_1], [_2], [_3] ... to refer to the first/second/third/... argument in the args list.

Example:

%TRANSLATE{"Sorry, I haven't seen [_1] or [_2] recently." args="Dave, Audrey"}%

Similarly, these tokens come in handy dealing with numbers in translations (see CPAN:Locale::Maketext):

Quantifying nounts:

%TRANSLATE{"Your search matched [quant,_1,document,documents,no documents]" args="0"}%
%TRANSLATE{"Your search matched [quant,_1,document,documents,no documents]" args="1"}%
%TRANSLATE{"Your search matched [quant,_1,document,documents,no documents]" args="2"}%

Format numbers according to this language's conventions.

%TRANSLATE{"Sum taxes [numf,_1]" args="1234.56"}%

Wrapper around Perl's normal sprintf function.

%TRANSLATE{"Couldn't access datanode [sprintf,%f.2,_1]." args="12345"}%

LANGUAGES

This overrides the standard %LANGUAGES macro shipped with Foswiki providing a much improved one.

It iterates over the list of given languages and returns information for each language found.

Parameter	Description	Default
"<lang1>, <lang2>, ..."	list of languages to render information for	languages enabled in Foswiki's configure
header	header string to be prepended to the output result; omitted when no language in the list was found
footer	footer string to be appended to the output; omitted when no language was found
separator	string separating items being formatted	$n
format	string to render information for each language found, see below for known format tokens	$language
selection	depicts a language in the list to be "selected" which activates the $marker string as defined below
marker	string to be inserted into the format when the current language matches the selection	selected="selected"
include	regular expression a language must match for it to be included in the output
exclude	regular expression a language must not match for it to be included in the output
sort	sorting order of output; can be on, off, code, country, name, label or language	language

Each language has got a list of properties that can be referred to in format and sort.

• language: the name of the language latin1 encoded, e.g. Bulgarian
• name: the name of the language, locally encoded, e.g. Български
• code: the language code, e.g. bg
• label: the fully disambiguated name of this language, e.g. Chinese (Taiwan, Province of China)
• icon: an image flag for this language, e.g.
• country: location where this language is spoken, e.g. Bulgaria

This information can be used as tokens in a format string, such as

• $language
• $language_name
• $name (or $langname ... provided for backwards compatibility)
• $code (or $langtag ... provided for backwards compatibility)
• $label
• $label_name
• $icon, $icon(<size>) (the html img with a country flag; use the second form to render a flag in different sizes)
• $country

In addition we have

• $marker (see above for selection and marker)
• $index running index of the language being processed
• $count the total numbers of languages found

Standard escape tokens, i.e. $n, $percnt and $dollar are supported as well.

Examples

All languages

Render a full table of all known languages:

Select language

Default language

%DEFAULTLANGUAGE%

Depending on the setting {SyncUserInterface} this either returns the language the user has configured in his/her browser or the value of {DefaultLanguage} as configured to this plugin.

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. "Extensions Operation and Maintenance" Tab -> "Install, Update or Remove extensions" Tab. Click the "Search for Extensions" button. Enter part of the extension name or description and press search. Select the desired extension(s) and click install. If an extension is already installed, it will not show up in the search results.

You can also install from the shell by running the extension installer as the web server user: (Be sure to run as the webserver user, not as root!)

cd /path/to/foswiki
perl tools/extension_installer <NameOfExtension> 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 https://foswiki.org/Support/ManuallyInstallingExtensions for more help.

Dependencies

Name	Version	Description
Foswiki::Plugins::MetaDataPlugin	>=3.20	Required

Change History

12 Jan 2018	don't require a local WebLexicon to be registered
13 Sep 2017	better handling of enabled languages; added Greek flag to mapping; suppress Locale::Codes' error reporting to stderr
16 Jan 2017	fixed crash translating strings with certain bracket links
02 Sep 2016	added support for WebLexicon
31 May 2016	added arg<N> way of specifying arguments to %TRANSLATE
8 Mar 2016	fixed error using latest Locale::Country
17 Jul 2015	fixed detection of CONTENT_LEXICON and extraction of correct string for a given language
16 Dec 2014	added $label_name and $language_name to ease select boxes
1 Nov 2013	initial release