MultiLanguageViews

Summary: show language specific content and titles according to user choice
Version: 2019-11-12
Prerequisites: PmWiki 2.2.56 or newer
Status: stable
Maintainer: HansB
Download: langviews.phpΔ

Questions answered by this recipe

How can I show language specific content and titles according to user choice?

Description

This recipe adds the following tools to help implement multiple language view features:

  • $Lang global variable
  • ?setlang=<id> language cookie switcher
  • ?lang=<id> language switcher
  • (:if lang <id> :) conditional markup for language content
  • {$Lang} and {$LangLabel} page variables
  • (:title-<id> ...:) language title markup
  • (:if langinpage <id> <pagename>:) conditional markup for language content checks
  • (:selectlang <type>:) markup for links to switch language content
  • (:if !enabled langviews:) conditional markup for content if recipe is not installed

These tools can be used to add language switching features, which will give a user the choice to select from various languages, and the editors and admin to include language specific content and titles in a page.

Installation

Install langviews.phpΔ to the cookbook folder and add to config.php:

include_once("$FarmD/cookbook/langviews.php");

The configuration variables ($MLVList, $MLVDefault etc.) must be defined before the above include code. See details below.

Optionally download flags.zipΔ to add some flag images for use with language selecting links.

Details on usage:

config settings:

$MLVList default array for language id's and labels:

$MLVList = array(
        'en' => 'english',
        'de' => 'deutsch',
        'fr' => 'francais',
        'it' => 'italiano',
        'es' => 'espanol',
     );

Define your own version of $MLVList in config.php before including the recipe script. Use ISO 639-1 2 letter language codes.

$MLVDefault = 'en'; default language id. Set to different default in config.php before including langviews.php.

$MLVSelectDefault= 'id'; default link type for (:selectlang:) markup, set in config.php to different link type before including langviews.php ('label' or 'flag').

$MLVLinkPatterns default array, for defining (:selectlang:) link formats. Note that '$page', '$id' and '$label' are used as pseudo-variables:

SDVA($MLVLinkPatterns, array(
   // links with id label
   'id'    => '[[$page?setlang=$id|$id]]',
   // links with text label
   'label' => '[[$page?setlang=$id|$label]]',
   // links with images (flags) plus tooltip label
   'flag'  => '[[$page?setlang=$id|Attach:Site/Site/$id.png"$label"]]',
));

$EnableMLVBackwardsCompatibility = 0; : set to 'true' in config to enable backward compatibility settings for sites migrating from multilanguage.php. By default the compatibility features (extra variable, page variable, conditionals etc.) are disabled. See Compatibility below.

$MLVCookie: by default the cookie name is 'userlang', with a $CookiePrefix if set (for wiki-specific cookie setting).

$EnableMLVSwitching = 1;: set to false in config to disable language switching via cookie setting.

To change the wiki interface language according to the language view, add something like this to config.php, after including the langviews.php script:

if ($_COOKIE[$MLVCookie] == 'de') {
  XLPage('de','PmWikiDe.XLPage');
  XLPage('de','PmWikiDe.XLPageCookbook');
}

etc. for other language's XL pages

url (and link) parameters:

?setlang=<id> url parameter for switching language by setting a cookie: create action links for switching the language, like [[{$Name}?setlang=de| deutsch]], or use the (:selectlang:) directive to have links for available languages displayed automatically.

?lang=<id> url parameter for non-permanent (non-cookie) language switching.

?userlang=<id> url parameter is retained as part of backwards-compatibility with sites migrating from multilanguage.php; you need to set $EnableMLVBackwardsCompatibility = 1;. See Compatibility below.

markup directives:

(:selectlang:) and (:selectlang <type>:)
links markup to show links for language setting. 'type' can be 'id','label' or 'flag' (the latter requires uploading of flag image files). Only links will be shown for which corresponding conditional (:if lang <id> :) or (:if userlang <id> :) sections are present in the page.
(:selectlang ... lang=all:) or (:selectlang ... lang=<id1>,<id2>,<id3>,.. :)
you can force display of all language switch links with lang=all (displaying all from the $MLVList array), or display a specified selection, using comma separated lanuage key names. Presence of language conditionals will no longer be checked.
(:selectlang ... sep=&nbsp;|&nbsp;:)
You can choose a custom separator between consecutive language. Default separator is just a space character.
(:if lang <id>:) conditional markup
add language specific content after the conditional markup. If the text contains other conditional markup, use nested conditions syntax.
(:title-<id> <text>:)
title markup for language specific titles. The {$Title} page variable and links of form [[PageName|+]] will show the title of the corresponding language title markup if present, otherwise of the ordinary title markup if present, otherwise the page name.
(:if langinpage <id> <pagename>:)
conditional markup, to test if a certain language specific content is present in a page. Useful as condition in pagelist markup to show list of pages with language specific content, for instance like
(:pagelist group=SomeGroup if="langinpage {$Lang} {=$FullName}" fmt=title:)
(:if !enabled langviews:)
shows content only if the script is not installed.

page variables:

{$Lang} page variable: Display the current language id in the page or use it in pagelist markup etc.

{$LangLabel} page variable: Display the current language label text.

{$lang} and {$langlabel} (with all letters low case) work as well.

{$userlang} page variable is retained for backwards-compatibility with sites migrating from multilanguage.php; you need to set $EnableMLVBackwardsCompatibility = 1;. It is the same as {$Lang}. See Compatibility below.

Compatibility with existing MultiLanguage markup in pages

By setting $EnableMLVBackwardsCompatibility = 1; the following variables and markup is added:

  • $userlang global variable is set, same as $Lang.
  • {$userlang} page variable is set, same as {$Lang}.
  • (:if userlang <id>:) conditional markup is recognised, although a new shorter markup (:if lang <id>:) can be used.
  • (:if userlang <id>:)(:title <text>:) is recognised, but (:title-<id> <text>:) is the preferred and functionally better way to set language specific page titles.
  • ?userlang=<id> url parameter can be used, but ?setlang=<id> is the prefered parameter, which is used by (:selectlang:).

Also note:

  • cookie name userlang is the same.
  • (:selectlang:) markup directive is similar but enhanced, by accepting 'type' and 'lang=...' parameters.
  • (:if langinpage <id> <pagename>:) conditional markup functions the same way.

Switching from MultiLanguage to this recipe should cause little problems, but you cannot include both recipes at the same time (nor should there be any need). You will need to set specific config variables, which are different from multilanguage.php.

Notes

To use $EnableIMSCaching with this recipe, the following code should be added to config.php:

## Setting the language cookie equals modifying the wiki, thus we invalidate cache
if ($EnableIMSCaching && isset($_GET['setlang'])) {
  SDV($LastModFile,"$WorkDir/.lastmod");
  @touch($LastModFile);
}

To Hans: even though it would be useful to add this to the recipe, the only bulletproof way to do this would be to explicitly state that langviews.php must be included after configuring $EnableIMSCaching. Ordering in config.php being as confusing as it is, perhaps it is better to leave this as a note.

Release notes

  • 2019-11-12: Fixed title markup to be PHP 7.2 compatible, not using Markup_e() any longer.
  • 2018-03-22: redone bugfix from 2015-10-09
  • 2017-06-16: changed selector link markup to use Markup(), not Markup_e()
  • 2015-10-09: Update for PHP 5.5. Fixed bugs : Select language Markup don't produce any more strange output when there isn't translations available. Fixed bugs (thx Sorse): No need two clicks any more to see changes in footer/header produced by XLPage and XLSDV() translations that rely on a cookie for the language choice. Add (idea by Dinalogic): optional separator parameter in the select language markup.
  • 2010-07-05: fixed bug which did not remove mltitle-<id> from page file when language specific title markup was removed from page.
  • 2009-09-15: added lang= option to (:selectlang:) markup.
  • 2009-07-29: added $EnableMLVBackwardsCompatibility variable and $userlang global
  • 2009-07-21: fixed bug in title attribute save
  • 2009-07-20: change in naming a number of variables and key names, to enhance compatibility with existing sites using MultiLanguage, for easier migration.
  • 2009-07-19: initial release.
    Script is based on ViewModes, but expands on it for more multi-language specific tools. Some features are borrowed from MultiLanguage.

See also

Contributors

Comments

See discussion at MultiLanguageViews-Talk

User notes +3: 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.