MultiLanguage

(redirected from 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
Categories: CMS, International, Layout, PHP72
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
  • 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

You can see the recipe live here (note the links on top of the left bar).

Contributors

  • Blues, implementation
  • KAL, first concept

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.