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 CONTENT_LEXICON preference variable or
• using the WebLexicon topic in the current web

The 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:

#	Language	Name	Code	Country	Flag
1	Bulgarian	Bulgarian	bg	Bulgaria
2	Chinese	Chinese	zh-cn	China
3	Chinese	Chinese	zh-tw	Taiwan (Province of China)
4	Czech	Czech	cs
5	Danish	Danish	da
6	Dutch	Dutch	nl	Netherlands
7	English	English	en	United Kingdom of Great Britain and Northern Ireland
8	Finnish	Finnish	fi	Finland
9	French	French	fr	France
10	German	German	de	Germany
11	Italian	Italian	it	Italy
12	Japanese	Japanese	ja
13	Korean	Korean	ko
14	Norwegian	Norwegian	no	Norway
15	Polish	Polish	pl	Poland
16	Portuguese	Portuguese	pt	Portugal
17	Portuguese	Portuguese	pt-br	Brazil
18	Russian	Russian	ru	Russian Federation
19	Spanish	Spanish	es	Spain
20	Swedish	Swedish	sv	El Salvador
21	Turkish	Turkish	tr	Turkey
22	Ukrainian	Ukrainian	uk

Found 22 languages

Select language

English

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

Dependencies

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

Change History

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