Cookbook /
MultiLanguage
Summary: Display content in different languages on a page by user's choice
Version: 20230409
Prerequisites: pmwiki 2.2.62
Status:
Maintainer: Blues
Discussion: MultiLanguage-Talk
Question
How can I publish text of a wiki-page in different languages depending on user's choice?
Answer
You can use multilanguage.phpΔ. For PHP 7.2 or newer please get multilanguage-php82.phpΔ instead and rename it to multilanguage.php.
Features
- Every wiki page can hold different translations in the form:
(:if userlang en:)english text(:if userlang it:)italian text...(:if:)common text - User selected language is stored in a cookie, can be selected with a "?userlang=xx" in the URL, if no language is selected and no cookie present the current language is detected from the browser.
- If the selected language is not available/defined in the current page then a default language is displayed (from a cascade of preferred languages, the first available).
- Different page titles can be defined inside each
(:if userlang xx:)branch and the correct title will be available as{$Title}page variable. Also titled links[[Page|+]]will work correctly. - A
(:selectlang:)directive will automatically display links (with the "?userlang=xx") for the languages that are defined on the page.
Notes
Installation:
Download the script from above and place it in your cookbook directory. Then add
include_once('cookbook/multilanguage.php'); in your local configuration (local/config.php).
Configuration:
Depending on which languages you will use in your wiki pages you will want to use the UTF8 features of PmWiki by adding
include_once('scripts/xlpage-utf-8.php'); to your config.php before including the multilanguage.php.
Before including the
multilanguage.php you may give a value to the following variables:
$DefaultLanguages is an array of preferred languages, it is used to display a default language if the selected one is not available in the page. The default is $DefaultLanguages = array('en');
ex.
$DefaultLanguages = array('en','it','de');
If the user selected 'es' and in the current page only 'it' and 'de' are defined, then 'it' will be displayed.
$LanguageSelectionFmt can be used to personalize the output of the (:selectlang:) directive. Default is $LanguageSelectionFmt = '[[{$FullName}?userlang=$1|$1]] '; which will display links in the form: "en it de".
ex.
$LanguageSelectionFmt = '[[{$FullName}?userlang=$1|Attach:$1.gif]] '; will display links with flags (provided you upload the flags images).
If you use translation pages (see: Internationalizations) you probably want to switch the XLPage definition too. To do this, use an if statement in your local configuration (config.php):
if ($_COOKIE['userlang'] == 'XX') {
XLPage('XX','PmWikiXX.XLPageCookbook');
XLPage('XX','PmWikiXX.XLPage');
XLPage('XX','PmWikiXX.XLPageLocal');
}
Use PmWikiXX.XLPageLocal for your own phrases
Use:
The page content with multilanguage support can be defined including each language in a
(:if userlang xx:) section.
ex.
(:if userlang en:)
english text
(:if userlang it:)
italian text
...
(:if:)
common text
The page variable
{$userlang} holds the currently selected language (eg. "en").
You can put
(:selectlang:) anywere in a page to display links to the available languages for that page.
The following parameters can be used:
page=... to specify the page for which display the links.
default=... to specify a default page for languages present in the $DefaultLanguages but who are not defined in the page (useful to direct the user to a homepage).
A new
langinpage conditional is available, to test whether in a particular page a particular language is defined or not. The conditional takes two parameters, the language and the pagename.
eg.
(:if langinpage en MyGroup.MyPage:)
tests if in the page MyGroup.MyPage is defined the language "en".
eg.
(:pagelist if="langinpage {$userlang} {=$FullName}":)
lists all the pages in which is defined the language currently selected by the user.
Notes:
Available languages and multilanguage page titles are parsed on edit and saved as page attributes to speed-up parsing on page load.
Examples:
You can see the recipe live here (note the links on top of the left bar).
- This recipe was last tested on PmWiki version: 2.1.beta25
- This recipe requires at least PmWiki version: 2.1.beta??
Releases
- 0.0 - 07.11.2004
- First multilanguage concept by KAL.
- 0.1 - 22.01.2006
- First implementation.
- 0.2 - 23.01.2006
- Added parsing of the page to automatically find available languages.
- Added (:selectlang:) directive to display selection links with current available languages.
- 0.3 - 25.01.2006
- Added possibility to configure (:selectlang:) output.
- Available languages are now parsed on edit and saved as attributes, so page load is faster (uses PCache).
- Added parameter to (:selectlang:) directive to display links to a specific page.
- 1.0 - 10.02.2006
- Added cascade of default languages in order of importance.
- Added parameter to (:selectlang:) to display links to a default page when a language is not available.
- Added support to multilanguage titles for [[Page|+]] titled links (saved as page attributes).
- Public release.
- 1.0b - 03.04.2006
- Fixed a problem when
$pagename
- Fixed a problem when
- 1.1 - 05.07.2007
- Added new langinpage conditional.
- Added
{$userlang}page variable (suggested by noskule). - Fixed a problem with setting userlang cookie (fixed by SteP).
- Added version information (see Cookbook.RecipeCheck).
- 1.2 - 14.10.2015
- Changed "Markup" to "Markup_e", so it work now also with PHP >5.5
- 20230409: Update for PHP 8.2 (Petko)
See Also
- MultiLanguageViews - show language specific content and titles according to user choice
- Translatelink, a recipe using google translation feature.
You can see the recipe live here (note the links on top of the left bar).
Contributors
Comments
See discussion at MultiLanguage-Talk
User notes? : If you use, used or reviewed this recipe, you can add your name. These statistics appear in the Cookbook listings and will help newcomers browsing through the wiki.