Table of Contents
Compatible with DokuWiki
- 2022-07-31 "Igor" unknown
- 2020-07-29 "Hogfather" yes
- 2018-04-22 "Greebo" yes
- 2017-02-19 "Frusterick Manners" yes
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
- Version upped (2023-02-02 23:50)
- add hreflang meta tags. replaces #248 (2023-02-02 15:23)
- Add lang and dir to content when UI isn't translated #273 (2023-02-02 11:40)
- style fix for dokuwiki template (2023-02-02 09:16)
- Version upped (2023-02-01 23:50)
- removed obsolete script file (2023-02-01 21:37)
- Add a param to call checkAge() within showTranslations() or not (2023-02-01 21:33)
- updated deleted files (2023-02-01 20:57)
- Search and install the plugin using the Extension Manager.
- Configure it through the Config Manager
- Add the following code in your template's
main.phpin the directory
lib/tpl/<yourTemplate>/(or put it in a
lib/tpl/default/pageheader.htmlfile 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
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.
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 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.
- 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
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:
| || The ISO language code (eg.
| || The real (localized) name of the language (eg.
| ||Show the “Translations of this page” intro text|
| ||Enabling this will add a linebreak after the title|
| ||Display a country flag matching the language (see below for more info)|
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:
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 is supported currently.
Namespace template variables
The translation plugin adds variables usable in Namespace Templates.
|@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>|
Language pre-namespaces in ACL rules can't be replaced to * mask. So
'*:folder:* @user 8' will not work — 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 — Z3Dev 2020-11-27