Translation Plugin

This plugin shows a list of available translations for a page. It is very simple and was built with the needs of www.dokuwiki.org in mind and is used for documentation translation efforts here. There are a few limitations:

• separate namespaces are used to store translations
• translated pages need to have the same pagename as the main language page

Compatibility: This plugin was compatible with DokuWiki 2009-12-25, due to a changed event the current version is not.

Use the download link given above to download the file manually or through the plugin manager.

• fixed URL in README (2011/02/05 11:40)
• README added (2011/02/05 11:35)
• added de-informal and updates for de (2011/01/08 12:30)
• tradtional chinese translation added (2010/12/23 23:16)
• version upped (2010/12/10 18:20)
• fixed scope fail (2010/12/10 18:15)
• Renamed flags from country identifiers to "matching" languages (2010/12/10 18:13)
• fixed about localization (2010/12/10 18:01)

1. Download and install the plugin through the Plugin Manager.
2. Configure it through the Config Manager
3. Add the following code in your template's main.php (or put it in a lib/tpl/default/pageheader.html file for the default template)

<?php
$translation = &plugin_load('helper','translation');
if ($translation) echo $translation->showTranslations();
?>

Note: add this piece of code not at the top or the bottom of main.php but instead in-between where it makes the best optical impression. You might need to experiment a bit to find the best spot.

If you have several themes or skins installed you need to add this piece of code into each main.php to allow the translation-plugin for every skin.

First, there are two ways how to set up a multilingual wiki:

1. a default language in the root namespace and translations in sub namespaces
2. no pages in the top namespace and all languages in sub namespaces

Here at dokuwiki.org the first method is used. Certain features OTOH will only work with second method.

There are several config options, all accessible through the config manager.

The most important thing to configure is a list of languages you want to use in the translations setting. It is good practice to use ISO language codes for this. Your translation namespaces will be named like the options you set here. Separate each language with a comma or space. Depending on the type of setup you want to use add your default language (the one configured in lang) here or omit it.

1. for the default language in the top namespace, omit it from the config
2. for namespaces for all languages add it here as well

By default a list of translation links is shown. This can take quite a bit space when you have many translations. Enabling the dropdown option should help here.

If you want to restrict translations to a certain namespace you can define it in the translationns option. This is optional, leaving it empty will enable the plugin for the whole wiki.

Similar to the above setting you can also disable translations for certain pages or namespaces using the skiptrans setting. It expects a regular expression to be matched against pagenames. When it matches, the translation switcher will not be displayed. The regexp is applied to the full pagename which starts with colon.

You can optionally choose to let the plugin translate the whole user interface of DokuWiki too when a non-default language page is selected. Just enable the translateui option accordingly.

If you decided to go with a type 2 setup, then your root namespace is pretty useless. Enabling the redirectstart setting will redirect users to the start of a translation namespace based on their browser language. This option only works when the above translatui setting is enabled, too.

When you have a default language that gets translated to other languages, it might be helpful to warn visitors on outdated translations. Enabling the checkage option will do that by comparing the age of the translation page with the one of the original (default language) page. It also tries to find the last revision of the original page that was edited before the translation and links to a diff view.

Finally you might want to explain how the translations work on your wiki to your users. To make this description easily accessible from the language selector, enter the pagename of your description in the about configuration setting. IF you enable the localabout setting, this description page can be translated as any other page and the link will always go to the currently active translation.

Additionally a few options can be selected to influence how the translation selector should look like. This is done through the display option where you can choose from the following settings:

If you don't use the Config Manager and prefer configuring your wiki editing the config file, the useful lines which have to be added to your local.php configuration file are:

$conf['plugin']['translation']['translations']  = 'en,fr,de,it';                        // available languages
$conf['plugin']['translation']['dropdown']      = 1;                                    // use a dropdown
$conf['plugin']['translation']['translationns'] = 'wiki';                               // namespace where to activate translation
$conf['plugin']['translation']['skiptrans']     = '^:(plugin|template):';               // what to skip (regexp)
$conf['plugin']['translation']['translateui']   = 1;                                    // translate the wiki user interface too
$conf['plugin']['translation']['checkage']      = 1;                                    // show notice on outdated translations
$conf['plugin']['translation']['about']         = 'translation:about';                  // page describing the translation process to users
$conf['plugin']['translation']['localabout']    = 1;
$conf['plugin']['translation']['display']       = 'langcode,name';

The plugin does its work automatically by being called from the template (see installation), but you can disable it for a certain page by adding the following code to the page:

~~NOTRANS~~

Usability experts agree that using country flags to represent a language is a really bad idea and should be avoided at all costs. This is because languages do not correspondent to single countries.

Simple example: what flag should represent English? The flag of England (red cross on white), the British flag (Union Jack) or the flag of the United states (Star-spangled banner)? Or what language would you expect when you see the Swiss flag? French? German? Rheto-Romanic?

I added support for flags because of the high demand for it but I strongly advise against using it. If you do, remember that your choice of flags will most probably annoy one group of your users, regardless what you chose.

Please note that flag support isn't 100% working when using the dropdown option in all Browsers.

New flags can be place in the flags directory of the plugin and need to be named after the ISO code. Only .gif is supported currently.

— Borodin Oleg 2011-04-22 19:54UTC

The code below allows you to get any page with a preferred language, not only :start.

That is http://www.somehost.net/aaa translate to http://www.somehost.net/pl/aaa where pl - the preferred language set in your browser. If such a translate on site is not exist, it uses the language of $conf['lang']

--- action.php.orig     2011-04-22 21:50:00.000000000 +0300
+++ action.php  2011-04-25 14:49:29.000000000 +0300
@@ -45,15 +45,15 @@
         global $ID;
         global $lang;
         global $conf;
         global $ACT;
 
-        // redirect away from start page?
-        if($this->conf['redirectstart'] && $ID == $conf['start'] && $ACT == 'show'){
-            $lc = $this->hlp->getBrowserLang();
-            if(!$lc) $lc = $conf['lang'];
-            header('Location: '.wl($lc.':'.$conf['start'],'',true,'&'));
+        $lc = $this->hlp->getBrowserLang();
+        if(!$lc) $lc = $conf['lang'];
+
+        if($this->conf['redirectstart'] && $this->hlp->getLangPart($ID) == '' && $ACT == 'show' &&  $this->hlp->istranslatable($ID)){
+            header('Location: '.wl($lc.':'.$ID,'',true,'&'));
             exit;
         }
 
         // check if we are in a foreign language namespace
         $lc = $this->hlp->getLangPart($ID);

While Release 2011-11-10 “Angua RC1” of dokuwiki works on PHP 5.1 - the translation plugin uses 1 function that is no available by default. You will get a hint about it in apache errorlog:

[error] PHP Fatal error: Call to undefined function array_fill_keys() in /xxxx/lib/plugins/translation/helper.php on line 39

One solution is to create your own array_fill_keys() in helper.php (found in http://wordpress.org/support/topic/plugin-wordpress-wiki-call-to-undefined-function-array_fill_keys)

function array_fill_keys($target, $value = '') {
	if(is_array($target)) {
		foreach($target as $key => $val) {
			$filledArray[$val] = is_array($value) ? $value[$key] : $value;
		}
	}

and call instance method at /xxxx/lib/plugins/translation/helper.php start

  $this->opts = array_map('trim',$this->opts);
  $this->opts = array_fill_keys($this->opts, true); //<--- add $this-> as seen below
  ...
  $this->opts = array_map('trim',$this->opts);
  $this->opts = $this->array_fill_keys($this->opts, true);
  ...