DokuWiki

You've loaded an old revision of the document! If you save it, you will create a new version with this data.

====== Translation Plugin ======
---- plugin ----
description: Help with translation efforts in a multilingual wiki
author     : Andreas Gohr
email      : andi@splitbrain.org
type       : syntax, action
lastupdate : 2023-05-17
compatible : Angua, Adora Belle, Hrun, Frusterick Manners, Greebo, Hogfather
depends    : 
conflicts  : 
similar    : 
tags       : language, translation

downloadurl: https://github.com/splitbrain/dokuwiki-plugin-translation/zipball/master
sourcerepo : https://github.com/splitbrain/dokuwiki-plugin-translation/
bugtracker : https://github.com/splitbrain/dokuwiki-plugin-translation/issues
donationurl: http://donate.dokuwiki.org/Translation
----

This plugin shows a list of available translations for a page. It is very simple and was built with the needs of [[:dokuwiki|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 [[plugin:extension|Extension Manager]]. Refer to [[:Plugins]] on how to install plugins manually.
==== Changes ====

{{rss>https://github.com/splitbrain/dokuwiki-plugin-translation/commits/master.atom date}}

===== Installation =====

- Search and install the plugin using the [[plugin:Extension]] Manager.
  - Configure it through the [[plugin:config|Config Manager]]
  - 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)

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

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

- a default language in the root namespace and translations in sub namespaces
  - 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 [[wp>List_of_ISO_639-1_codes|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 [[config:lang]]) here or omit it.

- for the default language in the top namespace, omit it from the config
  - 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|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:

=== Manual configuration ===

If you don't use the [[plugin:config|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:

<code php>
$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';
</code>

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

<code>
~~NOTRANS~~
</code>

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

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

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

===== Namespace template variables =====

===== Discussion =====

Please add %%~~TRANS~~%% syntax, because of page about [[.:imagebox]] and many other plugins here don't show this.  --- [[user>Dr-Yukon|Dr-Yukon]] //2018-05-13 02:39//

Language pre-namespaces in ACL rules can't be replaced to * mask. So '''*:folder:* @user 8''' will not work --- [[user>Dr-Yukon|Dr-Yukon]] //2019-02-15 19:43//

The list of languages is found in lib/plugins/translation/lang/langnames.txt (which doe not exist). Just add this file, and add a line for each language: code name
--- [[user>z3dev|Z3Dev]] //2020-11-27//

Please fill all the letters into the box to prove you're human. S᠎ O K᠎ I Y Please keep this field empty:

Edit summary

Note: By editing this page you agree to license your content under the following license: CC Attribution-Share Alike 4.0 International