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:
use the language parameter to %TRANSLATE,
use the CONTENT_LANGUAGE preference variable or
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:
… 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:
To separate the application of translated strings from their translation you might specify a lexicon, either
using the lexicon parameter of the %TRANSLATE makro or
using the WebLexicon topic in the current web or
using the WEBLEXICON preference variable or
using the SITELEXICON preference variable
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.
(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:
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.
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.
Caution: To display the localized language name correctly by using the $name format token your Foswiki's {Site}{CharSet} should be set to utf-8.
This is recommended for any new Foswiki installation. See Foswiki:Extensions/CharsetConvertorContrib. for a tool to convert existing content to utf-8.
Examples
All languages
Render a full table of all known languages:
$index
$language
$name
$code
$country
$icon(32)
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
Caution: To display the localized language name correctly by using the 
Automation