DokuWiki

It's better when it's simple

User Tools

Site Tools


plugin:translation

Translation Plugin

Compatible with DokuWiki

  • 2016-06-26 "Elenor Of Tsort" unknown
  • 2015-08-10 "Detritus" unknown
  • 2014-09-29 "Hrun" yes
  • 2014-05-05 "Ponder Stibbons" unknown

plugin Help with translation efforts in a multilingual wiki

Last updated on
2016-07-18
Provides
Syntax, Action
Repository
Source
Conflicts with
autotranslation, multilingual, translation3

Tagged with language

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

Download

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

Changes

Installation

  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 in the directory lib/tpl/<yourTemplate>/ (or put it in a lib/tpl/default/pageheader.html file for the old default template)
<?php
$translation = plugin_load('helper','translation');
if ($translation) echo $translation->showTranslations();
?>

Suggestion: Add this code to main.php where the visual element will look best in your theme. 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.

Suggestion 2: For the “dokuwiki”-template you can create sidebarheader.html within lib/tpl/dokuwiki with the code above. Then it looks like the “DokuWiki.org” Homepage and you need not redo this after a dokuwiki update.

Configuration

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 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 translateui 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:

Setting Description
langcode The ISO language code (eg. de)
name The real (localized) name of the language (eg. Deutsch)
title Show the “Translations of this page” intro text
twolines Enabling this will add a linebreak after the title
flag Display a country flag matching the language (see below for more info)

Manual configuration

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';

Usage

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~~

On using country flags

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 correspond 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.

Namespace template variables

The translation plugin add variables usable in Namespace Templates.

Variable Description Example
@LANG@ Language you have entered in your lang config en
@TRANS@ The currently used language. This variable will be empty, if your default language has no sub namespace. en:start → en, start → <blank>

Discussion

Old translation warning based on ACL

I use translation for a public website, and would like a means to only show old translations only to registered users: As I also use the publish plugin, the translation page shows the “old translation” warning if there is a draft of the original.

I am using an ugly hack now, which works, but would very much welcome a proper and maintainable implementation in the future.

Loading language selector

Would be great if the language selector could be loaded without modifying the template (and losing the changes with the next update and then trying hard to remember where you added it the last time). Don't know if there's a hook for that in the default template, but would definitely be helpful. Thanks!

plugin/translation.txt · Last modified: 2016-07-18 09:46 by andi