DokuWiki

It's better when it's simple

User Tools

Site Tools


plugin:translation

Translation Plugin

Compatible with DokuWiki

  • 2024-02-06 "Kaos" unknown
  • 2023-04-04 "Jack Jackrum" unknown
  • 2022-07-31 "Igor" unknown
  • 2020-07-29 "Hogfather" yes

plugin Help with translation efforts in a multilingual wiki

Last updated on
2023-12-14
Provides
Syntax, Action
Repository
Source
Conflicts with
autotranslation, multilingual, translation3

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

Search and install the plugin using the Extension Manager. Refer to Plugins on how to install plugins manually.

Changes

Installation

  1. Search and install the plugin using the Extension 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 the 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 one 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.

If you want to switch on the translation flag only for specific namespaces, you can do this by defining a regular expression that inverts the result, for example
^((?!:redaktionssystem:techn_doku|:technik:verkaufsunterlagen|:en).)*$.
Then only in the namespaces “redaktionssystem:techn_doku”, “technik:verkaufsunterlagen” and “en” the translation plugin is active.

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 Union Flag (aka “Union Jack”) for the UK or the flag of the United states (Stars and stripes)? 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.

New flags can be placed in SVG format in the flags directory of the plugin and need to be named after the language ISO code.

Namespace template variables

The translation plugin adds 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>
plugin/translation.txt · Last modified: 2023-12-14 23:50 by andi

Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Share Alike 4.0 International
CC Attribution-Share Alike 4.0 International Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki