Manual:Extension/BlueSpiceInterWikiLinks and Multilingual wiki: Difference between pages

(Difference between pages)
(Changed categories.)
 
No edit summary
 
Line 1: Line 1:
<bookshelf src="Book:Admin manual" />
{{DISPLAYTITLE:Multilingual wiki (single wiki)}}
{{DISPLAYTITLE:Interwiki links}}
[[File:hallo-cloud.png|link=https://en.wiki.bluespice.com/wiki/File:hallo-cloud.png|alt=word cloud with translations of the greeting "hello"|right|200x200px]]
A wiki can be set up to include different language versions for wiki pages. Wiki administrators have to make some decisions regarding how they want to support each wiki user's language setting in addition to simply providing translated content.


The extension '''InterWikiLinks''' allows creating abbreviations for various external wikis. The full URL only needs to be known when the interwiki link is defined and not every time it is used. You can find the interwiki links manager in the ''Global actions'' menu under ''Management > Interwiki links.''
The following considerations refer to a single-wiki scenario in ''BlueSpice pro'' and don't apply if the language versions are maintained in multiple wikis. A lot of this functionality is also supported in ''BlueSpice free'' which will be documented here soon.


==Interwiki links manager==
== Concepts ==
Interwiki links are managed from the page ''Special:InterwikiLinks''. It can be loaded from the navigation item ''Global actions > Management > Interwiki link''s.
To make a single wiki multilingual, some basic steps are necessary:
[[File:Manual:interwikilink manager.png|alt=Interwiki link manager|center|thumb|650x650px|Interwiki link manager]]


<br />
* Import a '''language switcher'''
==Interwiki link syntax==
* Create  wiki pages with '''linked''' '''translation subpages'''
** Alternative way: connect unrelated "random" pages


Admins can create and delete Interwikilinks with the Interwiki links manager.
Existing links can be edited by clicking the "wrench" icon when the link is selected or deleted by clicking the "X" button.


The syntax for interwiki links is:
In addition, depending on your wiki setup, further aspects can and should be considered:
* Create '''flexible''' '''page lists''' for each language
* Create '''portal pages''' based on user language
* Create '''template and form labels''' based on user language
* Create a multilingual '''category system'''
* Create multilingual '''navigation links'''


<code><nowiki>http://URL_OF_THE_WIKI/$1</nowiki></code>
== Techniques ==
[[File:langswitcher.png|alt=language switcher|thumb|language switcher]]
[[File:usrelanguage-switchlabels.png|link=https://en.wiki.bluespice.com/wiki/File:usrelanguage-switchlabels.png|alt=Content based on user language settings|thumb|250x250px|Content based on user language ]]
[[File:multilingual-categories.png|link=https://en.wiki.bluespice.com/wiki/File:multilingual-categories.png|alt=Multilingual category tree|thumb|250x250px|Multilingual category tree]]The explanations on this page use the following techniques, which we will look at in more detail:


<code>$1</code> is the placeholder for the article title of the other wiki.
#'''Smart language switcher''':  A menu bar directly inserted on wiki pages.  It provides:
[[File:Manual:interwikilink-url.png|alt=Interwiki link of the BlueSpice helpdesk|center|thumb|550x550px|Interwiki link of the BlueSpice helpdesk]]
#*'''language support''': settings to define which languages are used in the wiki
<br />
#*'''navigation:''' a mechanism to automatically switch between the language versions of a page
==Using interwiki links on a page==
#*'''tracking:''' a property that tracks the page language for each page (supported in ''BlueSpice pro'')
#*'''fall-back mechanism:'''  an automatic category assignment system that can track the page language
#*'''translated page titles:''' a way to provide a display title for language subpages that otherwise would show the language code as the title. <br />
#'''User language:''' A simple mechanism to determine which language  a user has defined in their personal settings.  It provides options to:
#* show or hide content based on the user language
#*swap the entire page content shown to the user
#*customize the main navigation
#*display template and form labels to users based on their user preference. <br />
#'''Categories:''' A multilingual category system.  It is useful for:
#*users that don't speak the "main" language (the content language) of the wiki and, therefore, want to tag pages in another supported language.


In edit mode, links to other wikis are added just like links to local wiki pages, but with the interwiki prefix at the beginning.
==A note about MediaWiki translation extensions==
The following information gives you some suggestions for organising a wiki around its multilingual content based on the previously mentioned aspects. It does not consider using  MediaWiki extensions like [[mediawikiwiki:Extension:Translate|Translate]]  or the [[mediawikiwiki:MediaWiki_Language_Extension_Bundle|MW Language Extension Bundle]] which can be installed in multlingual wikis to faciliate a section-by-section translation of wiki pages.  


For example:
If most of your wiki content needs consistently accurate translations, these extensions can be valuable. Such a focus on translation, however, requires an understanding of how this mechanism technically works and might hinder the spontaneous contribution  to the wiki by a broad user base. In addition, these extensions are not bundled with BlueSpice and require additional administrative effort during wiki updates or upgrades.


The URL to the Wikipedia article "Tree house" is:
Here, we look at techniques that support multilingual content in an easy way. All that is necessary, in addition to using already built-in mechanisms, is importing a language switcher template which provides the necessary information to easily change between different languages. This template also tracks the language versions of a page in a way that makes it easy to create targeted overview pages for users with different language backgrounds.


<code><nowiki>https://en.wikipedia.org/wiki/Tree_house</nowiki></code>
== Considerations before using the subpages approach ==
Many wikis use the approach of creating language subpages of a page that is written in the wiki's main language (=content language defined during wiki installation). This is a great mechanism if we assume that the majority of content is available in the wiki's main language first. This is often the case in English wikis.  But what if there is no "main" language in a wiki - when the language(s) of many contributors do not match this content language of the wiki?


Wikipedia is a default entry in the Interwiki link manager:
The solution in this case is often to maintain separate wikis for each language "community" and then connect the wikis via so called [[Manual:Extension/BlueSpiceInterWikiLinks|interwiki links]]. Wiki administrators have to create a plan for dealing with wiki elements such as uploaded files, templates, forms, properties and other functionality.


<code>prefix: wikipedia, url: https://en.wikipedia.org/wiki/$1</code>
But what if you still want to use a single wiki in this scenario? How and where should wiki users create their pages? The following solutions are feasible:


As a result, a link to any wikipedia page can be inserted by using the wikipedia prefix.
=== Interwikilinks used within a single wiki ===
[[File:interlanguagelink-menu.png|alt=Interlanguage links menu|thumb|Interlanguage links menu]]
It is possible to think of each language as independent and allow users to create pages in their preferred language. A German speaking user could create a page "Urlaubsregelung" in an English wiki. If another user creates a "matching" page "Vacation policy" in the wiki, these two pages can be connected  manually by adding interlanguage links to the page. For this purpose, wiki administrators can create the needed interwiki links. The pages are then connected via the built-in  interlanguage menu  of the wiki.  


<code><nowiki>[[wikipedia:Tree_house|Wikipedia article about tree houses]]</nowiki></code>
The disadvantages of this approach are that the menu is collapsed. If  you want to know which translations are available for the page you are viewing, you always have to expand the menu to find out. In addition, by default these links open in new browser tabs, which might be inconvenient if you have to switch a lot between languages. This mechanism also does not track the actual page language for further processing.
==Special use case: multilingualism==


If you want to maintain multiple language versions of your wiki on separate wikis, you can use interwiki links to cross-reference related pages.
=== Language-independent page names ===
Fore a more flexible approach to the interwiki-links solution, which was mainly designed for supporting multiple wikis, you can use a variation of the standard language switcher described below. This language switcher variation does not track language subpages, but it allows to connect any pages in the wiki. You can download this InterLanguages template here on the helpdesk. Since it works similarly to the standard language switcher for subpages, we don't look at it in more detail for now.


With BlueSpice, flag symbols are automatically inserted when the interwiki links with language abbreviations are set.
== Importing the language switcher==
As already mentioned, it is useful to indicate that a page has different versions by providing a language switcher. If you have no language switcher in your wiki, you can [[Templates download/Language switcher|download a language switcher template]]. The techniques shown in the following sections assume that this particular language switcher is available and used.  


Be sure to read the configuration instructions on the downloads page. You need to define the languages that you want to support in your wiki in the  template itself.


'''Linking the language versions''':
[[File:language-switcher-template.png|alt=language switcher on a wiki page|center|thumb|450x450px|language switcher on a wiki page]]


#Create interwiki links for the required languages ​​and configure them in the ''Interwiki link manager'' (see above) of all language sites. The prefix must always be an [https://en.wikipedia.org/wiki/ISO_3166-1 ISO-3166] country code, e.g. de, en, fr.
==Creating wiki pages with translated subpages==
#Add the interwiki links at the bottom of the related pages to create the language switch.  '''Example:'''  In the English article "Tree", insert the following interwiki links:
Let's take a page called ''Vacation policy'' in a wiki with English as its content language and create a German language version.
<syntaxhighlight lang="html">
[[en:{{FULLPAGENAME}}]] 
[[de:Baum]]
</syntaxhighlight>The result of setting the first link is that the English flag will be shown in the language selection of the page header toolbar. This is not necessary and can also be omitted. The second link connects the page with the related german page "Baum" in the German wiki and generates the German flag as a switch in the header toolbar:
[[File:Manual:interwikilink-languageswitcher-EN.png|alt=Links to different language versions|center|thumb|650x650px|Links to different language versions ]]


{{Messagebox|boxtype=note|icon=|Note text=When  working with translation subpages, it is important to know the [https://www.mediawiki.org/wiki/Manual:Language content language] of the wiki. It is the language in which the wiki has been installed. To find it out, you can add the magic word <nowiki>{{CONTENTLANGUAGE}}</nowiki> to the source view of any wiki page and save it. The page will then display the language code.|bgcolor=}}


== Special page "WithoutInterwiki" ==
To view a list of all pages on a wiki that don't have interwiki links, an administator can review the page ''Special:WithoutInterwiki''.


{{Box Links-en
To create a language version for the main language (=content language), a subpage with the ISO-639 language code as subpage name is created. This means that for the page Vacation policy, you need to create the subpage ''Vacation policy/d''e.
|Topic1=[[Reference:BlueSpiceInterWikiLinks]]
 
As you can see in the screenshots below, the page content is always shown in the context of the user language preferences of each user. This means that the user interface elements do not necessarily correspond to the translated language. But since the user decided to use this language setting, it does not negatively affect this user, but actually supports them when navigating the wiki.
 
<gallery widths="500" heights="350">
File:language-subpage-de.png|alt=German content version with user language preference English.|German content version (1) with user language preference English (2).
File:language-subpage-de-uselang-de.png|alt=German content version with user language preference German.|German content version with user language preference German.
</gallery>
 
===Adding the language switcher to a page===
Now that we have two language versions, we want to connect them with the language switcher. To add the language switcher to a page:
#'''Open''' the page in edit mode.
#'''Insert''' the template ''Languages'' form the editor toolbar.
#'''Enter''' a display title for the page (recommended for subpages).[[File:language-displaytitle.png|link=https://en.wiki.bluespice.com/wiki/File:language-displaytitle.png|alt=Setting the display title|center|thumb|450x450px|Setting the display title]]The search engine will index this display title  so that the title search returns the expected result.
#'''Save''' the page.
#'''Repeat''' steps 1-4 with other language subpages (e.g, fr, nl).
 
 
The language switcher in the right corner of the page now shows what other languages are already available.
[[File:languageswitcher-DE.png|alt=Language switcher shows all available translations|center|thumb|550x550px|The language switcher shows all available translations]]
#
#
 
==Creating page lists for different languages==
Over time, a wiki can have lots of these translated pages.  We want to make sure that users know what pages are available in what language. For this purpose, the language switcher template includes a custom property L''anguages/tracklang'' that allows to easily create filtered page lists for this purpose.
 
In ''BlueSpice pro,'' you can include different inline queries on any wiki page. This example lists German language pages in the main namespace  and displays them in a category-type output (A-Z listing): <syntaxhighlight lang="text">
{{#ask:
[[:+]][[Languages/tracklang::de]]
|format=category
}}
}}
</syntaxhighlight>
[[File:languageswitcher-ask-result-category-de.png|alt=Results format "category"|center|thumb|450x450px|Results format "category"]]
Explanation of the arguments for this query:
*'''<nowiki>[[:+]]</nowiki>''': Returns pages only in the main namespace. To show the pages form the entire wiki, simply delete this argument. Other options:
**<nowiki>[[QM::+]]</nowiki>: Returns pages from the namespace QM
**<nowiki>[[QM:+||Help:+]]</nowiki>: Returns pages from the namespaces QM and Help.
*'''<nowiki>[[Languages/tracklang::de]]</nowiki>''': Returns only pages that are marked by the language switcher template as German language pages. Other options:
**<nowiki>[[Languages/tracklang::+]]</nowiki>: Returns all language pages that are tracked in the wiki by the language switcher template.
**<nowiki>[[Languages/tracklang::!de]]</nowiki>: Returns all language pages except German pages.
**<nowiki>[[Languages/tracklang::de||fr]]</nowiki>: Returns all language pages in German and French (in the example above restricted to the main namespace.
*'''format=category''': returns a category style output.
** format=ul: returns a list style output
[[File:languageswitcher-ask-result-de.png|alt=Results format "ul"|center|thumb|250x250px|Results format "ul"]]
To see more examples for defining and further modifying a query, go to our [[SMW queries|SMW-query examples]] page.
{{Messagebox|boxtype=note|icon=|Note text=Working with properties requires the [https://www.mediawiki.org/wiki/Extension:Semantic_MediaWiki Semantic MediaWiki extensions], which are bundled in ''BlueSpice pro'', but not in ''BlueSpice free''. There are, however, alternative approaches for [[#Mulitlingual content in BlueSpice free|creating page lists in ''BlueSpice free'']].|bgcolor=}}
==Creating portal pages based on user language settings==
Portal pages are pages  that serve as entry points to different topics or areas in the portal, often considering the needs of specific user groups. A typical example is the main page of the wiki, which should give users a high-level orientation in the wiki. A portal page is a good place to take the language needs of different users into account.
Here, we can take two different approaches:
#Show the '''same page to all users''', but include '''some content''' that targets specific user languages.
#Show completely '''separate content''' to users based on their user language.
===What is the user language?===
Wiki users  can change their own language setting in the user preferences:
[[File:userlanguage.png|alt=User language preference|center|thumb|550x550px|User language preference]]
Depending on this setting, users then see the user interface elements in that language as we have seen in [[Multilingual wiki#Creating wiki pages with translated subpages|previous screenshots]]. This applies to interface elements that already have translated system messages.
To provide additional support for this setting, we can include checks on wiki pages that determine the user language and serve up additional or alternative information as needed.
===Preparing the user language check===
Checking for the user language requires that we create a system message for this purpose. This is easy to do, but needs to be done by users in the role ''admin'' or ''structuremanager.''
To create a system message for the user language:
#'''Create''' the page ''MediaWiki:lang w''ith the content being the language code of the content language of your wiki. If you are not sure in what language your wiki was installed, you can add the magic word <nowiki>{{CONTENTLANGUAGE}}</nowiki> to the source of any wiki page and look at its output.  If you have an English wiki, you need to add "en" as the content to this page. If your wiki is German, add "de" instead.[[File:message key-lang.png|alt=Page MediaWiki:Lang|center|thumb|650x650px|Page MediaWiki:Lang]]
#'''Create''' subpages to this page for the user languages you want to support. For example in an English wiki:
#*MediaWiki:Lang/de
#*MediaWiki:Lang/fr
Now  we have a mechanism to detect the user language. By checking for the value of the "[[mediawikiwiki:Help:Magic_words#Localization|magic word]]" <nowiki>{{int:lang}}</nowiki> , we  can use it in many different scenarios.
===Displaying additional content===
To show content on a page only to users with a specific language setting — for example, German — we can add the following check:<syntaxhighlight lang="text">
{{#ifeq: {{int:lang}}|de|show this content|}}
</syntaxhighlight>
===Switching to different page content===
To show entirely different content to users with different language settings, you can prepare different pages and then serve them up as needed. As an example we take the homepage of the wiki.
To display different homepage content based on user language in an English wiki, where the homepage is called ''Main Page'':
#Create a subpage for each language you want to support, e.g.
## Main Page/en
##Main Page/de
## Main Page/fr
#On the page Main Page, add the following switch:<syntaxhighlight lang="text">
{{#switch: {{int:lang}}|de={{:Main Page/de}}|fr={{:Main Page/fr}}|{{:Main Page/en}} }}
</syntaxhighlight>Users with language setting "de" will see the content of page ''Main Page/de'', users with "fr" language setting the page ''Main Page/fr'', all other users get the page Main ''Page/en''.
===Switching labels===
To show different labels or short text snippets directly on a page, we can also use the switch function:<syntaxhighlight lang="text">
{{#switch:{{int:lang}}|de=Überschrift 2|en=Heading 2}}
</syntaxhighlight>To summarize, the following main page can be accomplished in two different ways:
#By creating separate subpages for each user language and then transcluding them with a user language check on the actual Main Page.
#By loading the actual Main Page and then building the language checks into the page itself. The following picture shows examples of:
#*(1), (2) Switching headings
#*(3) Displaying query results based on the tracked language from the language switcher template (e.g., <nowiki>[[Languages/tracklang::en]]</nowiki>)
#*(4) Switching display labels in templates (this can also be applied to page forms)
#*(5) Switching image captions
[[File:usrelanguage-switchlabels.png|alt=Content based on user language settings|center|thumb|750x750px|Content based on user language settings]]
===Switching template and form labels===
As the previous screenshot shows, labels in templates (and forms) can also be shown based on user language. You can simply add the switch function directly in the template. The  template ''Template:Contactinfo'' collects street, zip and city info:<syntaxhighlight lang="text">
{| class="wikitable"
! {{#switch:{{int:lang}}|en=Street|de=Straße}}
| {{{street|}}}
|-
! {{#switch:{{int:lang}}|en=Zip|de=PLZ}}
| {{{zip|}}}
|-
! {{#switch:{{int:lang}}|en=City|de=Stadt}}
| {{{city|}}}
|}
</syntaxhighlight>It displays the different labels as needed:<gallery widths="180" heights="100">
File:uselang-template-en.png|alt=English labels|English labels
File:uselang-template-de.png|alt=German labels|German labels
</gallery>
==Multilingual navigation==
Currently, there is no easy mechanism to create multilingual navigation menus, such as the main navigation or the custom menu. More support should be coming in one of the next minor releases of BlueSpice (4.2 or 4.3). In the meantime, you can create [[Manual:Extension/BlueSpiceDiscovery/Main navigation/Language support|individual links based on a user's language settings]].
==Searching content by language==
[[File:search-tracklang1.png|alt=Limiting search results by language|center|thumb|650x650px|Limiting search results by language]]
[[File:search-tracklang2.png|alt=Filtering pages by language|center|thumb|250x250px|Filtering pages by language]]
==Multilingual categories==
An important aspect of organizing content is a well-designed category system for your wiki. By tagging your content, you support both the search functionality and the possibility of creating context-based page lists in all kinds of variations.
To keep an overview of which categories are available translated in different languages and which categories are simply shared by different languages, you can use a prefix mechanism that allows to associate categories by language.
For example, for the category Application, you would use (in an English wiki) the English category ''APP Application'' and the German category ''APPde Anwendung''. Both categories could share the category ''APP SAP''.
[[File:multilingual-categories.png|alt=Multilingual category tree|center|thumb|550x550px|Multilingual category tree]]
Whether you even need the separate category ''APPde Anwendung'' depends simply on the language proficiencies of your users. You don't need to create a language variation of a category just for finding, for example, all German pages that are related to the concept of "Applications", since the language switcher mechanism already collects this information for you.
{{Messagebox|boxtype=tip|icon=yes|Note text=It makes sense to create as many language versions of categories as necessary, but as few categories as possible. To determine if you need a language variation, ask yourself:
*Who needs this category for what purpose?
*Is there already a different mechanism (e.g. a SMW-property, an automatically assigned category, the subpage syntax) that can be used to later "collect" pages based on different commonalities.|bgcolor=}}
===Creating a root category first===
It is also a good idea, to start your category system with a single root category:
[[File:rootcategory.png|alt=Starting with a root category|center|thumb|250x250px|Starting with a root category]]
This allows you to later manage your category system without entangling it with other unrelated categories that might be created by users. Besides your category system, other types of categories might coexist:
*[[mediawikiwiki:Help:Categories#Hidden_categories|Hidden categories]]
*[[mediawikiwiki:Help:Tracking_categories|Tracking categories]]
*Informal tagging-categories created by users "on-the-go"
=== Sharing subcategories===
If you have already assigned a subcategory to a category using the [[Manual:Extension/BlueSpiceCategoryManager|Category manager]], there is no mechanism to assign it to a second category. You have to do the assignment manually and directly on the category page. For example, to use the category ''APP SAP'' as a subcategory of both the category ''APP Application'' and ''APPde Anwendung:''[[File:multiple-parentcats.png|alt=Subcategory of multiple parent categories|center|thumb|550x550px|Subcategory of multiple parent categories]]The category manager then shows the category APP SAP listed under both parent categories:  [[File:multiple-parentcats-catmanager.png|alt=Shared subcategory|center|thumb|280x280px|Shared subcategory]]
{{Messagebox|boxtype=important|icon=yes|Note text=If you delete a shared subcategory from the category manager, it will be deleted from all its parent categories and from all the pages that are assigned to this subcategory.|bgcolor=}}
===Querying multilingual categories===
To show a  list of pages based on categories, you can use different arguments in an ask query.
*Show all pages in categories ''DOC Process description'' OR ''DOC Prozessbeschreibung:''
<syntaxhighlight lang="text">
[[Category:DOC Process description||Category:DOCde Prozessbeschreibung]]
</syntaxhighlight>


*Show all pages in all categories related to Applications (both German and English). This also includes the pages in all subcategories of these two main categories:
<syntaxhighlight lang="text">
[[Category:APP Application||APPde Anwendung]]
</syntaxhighlight>


{{Translation}}
*Show all pages in category ''APP Applicatio''n including pages from the first level of subcategories only. Do not include English versions of any subcategories that are shared across languages. This ensures that the German pages included by default through the shared subcategory ''APP SAP'' are not included in the results<syntaxhighlight lang="text">
[[Category:APP Application|+depth=1]][[Languages/tracklang::!de]]
</syntaxhighlight>


[[Category:Organization]]
{{Messagebox|boxtype=note|icon=|Note text=To avoid deleted pages and redirects showing up in your results list, you can add the property <nowiki>[[Modification date::+]]</nowiki> to any of your queries.|bgcolor=}}
[[Category:Multilingual wiki]]
[[Category:Multilingual wiki]]

Revision as of 15:36, 30 March 2022

word cloud with translations of the greeting "hello"

A wiki can be set up to include different language versions for wiki pages. Wiki administrators have to make some decisions regarding how they want to support each wiki user's language setting in addition to simply providing translated content.

The following considerations refer to a single-wiki scenario in BlueSpice pro and don't apply if the language versions are maintained in multiple wikis. A lot of this functionality is also supported in BlueSpice free which will be documented here soon.

Concepts

To make a single wiki multilingual, some basic steps are necessary:

  • Import a language switcher
  • Create wiki pages with linked translation subpages
    • Alternative way: connect unrelated "random" pages


In addition, depending on your wiki setup, further aspects can and should be considered:

  • Create flexible page lists for each language
  • Create portal pages based on user language
  • Create template and form labels based on user language
  • Create a multilingual category system
  • Create multilingual navigation links

Techniques

language switcher
language switcher
Content based on user language settings
Content based on user language
Multilingual category tree
Multilingual category tree

The explanations on this page use the following techniques, which we will look at in more detail:

  1. Smart language switcher: A menu bar directly inserted on wiki pages. It provides:
    • language support: settings to define which languages are used in the wiki
    • navigation: a mechanism to automatically switch between the language versions of a page
    • tracking: a property that tracks the page language for each page (supported in BlueSpice pro)
    • fall-back mechanism: an automatic category assignment system that can track the page language
    • translated page titles: a way to provide a display title for language subpages that otherwise would show the language code as the title.
  2. User language: A simple mechanism to determine which language a user has defined in their personal settings. It provides options to:
    • show or hide content based on the user language
    • swap the entire page content shown to the user
    • customize the main navigation
    • display template and form labels to users based on their user preference.
  3. Categories: A multilingual category system. It is useful for:
    • users that don't speak the "main" language (the content language) of the wiki and, therefore, want to tag pages in another supported language.

A note about MediaWiki translation extensions

The following information gives you some suggestions for organising a wiki around its multilingual content based on the previously mentioned aspects. It does not consider using MediaWiki extensions like Translate or the MW Language Extension Bundle which can be installed in multlingual wikis to faciliate a section-by-section translation of wiki pages.

If most of your wiki content needs consistently accurate translations, these extensions can be valuable. Such a focus on translation, however, requires an understanding of how this mechanism technically works and might hinder the spontaneous contribution to the wiki by a broad user base. In addition, these extensions are not bundled with BlueSpice and require additional administrative effort during wiki updates or upgrades.

Here, we look at techniques that support multilingual content in an easy way. All that is necessary, in addition to using already built-in mechanisms, is importing a language switcher template which provides the necessary information to easily change between different languages. This template also tracks the language versions of a page in a way that makes it easy to create targeted overview pages for users with different language backgrounds.

Considerations before using the subpages approach

Many wikis use the approach of creating language subpages of a page that is written in the wiki's main language (=content language defined during wiki installation). This is a great mechanism if we assume that the majority of content is available in the wiki's main language first. This is often the case in English wikis. But what if there is no "main" language in a wiki - when the language(s) of many contributors do not match this content language of the wiki?

The solution in this case is often to maintain separate wikis for each language "community" and then connect the wikis via so called interwiki links. Wiki administrators have to create a plan for dealing with wiki elements such as uploaded files, templates, forms, properties and other functionality.

But what if you still want to use a single wiki in this scenario? How and where should wiki users create their pages? The following solutions are feasible:

Interwikilinks used within a single wiki

Interlanguage links menu
Interlanguage links menu

It is possible to think of each language as independent and allow users to create pages in their preferred language. A German speaking user could create a page "Urlaubsregelung" in an English wiki. If another user creates a "matching" page "Vacation policy" in the wiki, these two pages can be connected manually by adding interlanguage links to the page. For this purpose, wiki administrators can create the needed interwiki links. The pages are then connected via the built-in interlanguage menu of the wiki.

The disadvantages of this approach are that the menu is collapsed. If you want to know which translations are available for the page you are viewing, you always have to expand the menu to find out. In addition, by default these links open in new browser tabs, which might be inconvenient if you have to switch a lot between languages. This mechanism also does not track the actual page language for further processing.

Language-independent page names

Fore a more flexible approach to the interwiki-links solution, which was mainly designed for supporting multiple wikis, you can use a variation of the standard language switcher described below. This language switcher variation does not track language subpages, but it allows to connect any pages in the wiki. You can download this InterLanguages template here on the helpdesk. Since it works similarly to the standard language switcher for subpages, we don't look at it in more detail for now.

Importing the language switcher

As already mentioned, it is useful to indicate that a page has different versions by providing a language switcher. If you have no language switcher in your wiki, you can download a language switcher template. The techniques shown in the following sections assume that this particular language switcher is available and used.

Be sure to read the configuration instructions on the downloads page. You need to define the languages that you want to support in your wiki in the template itself.

language switcher on a wiki page
language switcher on a wiki page

Creating wiki pages with translated subpages

Let's take a page called Vacation policy in a wiki with English as its content language and create a German language version.

Note:When working with translation subpages, it is important to know the content language of the wiki. It is the language in which the wiki has been installed. To find it out, you can add the magic word {{CONTENTLANGUAGE}} to the source view of any wiki page and save it. The page will then display the language code.


To create a language version for the main language (=content language), a subpage with the ISO-639 language code as subpage name is created. This means that for the page Vacation policy, you need to create the subpage Vacation policy/de.

As you can see in the screenshots below, the page content is always shown in the context of the user language preferences of each user. This means that the user interface elements do not necessarily correspond to the translated language. But since the user decided to use this language setting, it does not negatively affect this user, but actually supports them when navigating the wiki.

Adding the language switcher to a page

Now that we have two language versions, we want to connect them with the language switcher. To add the language switcher to a page:

  1. Open the page in edit mode.
  2. Insert the template Languages form the editor toolbar.
  3. Enter a display title for the page (recommended for subpages).
    Setting the display title
    Setting the display title
    The search engine will index this display title so that the title search returns the expected result.
  4. Save the page.
  5. Repeat steps 1-4 with other language subpages (e.g, fr, nl).


The language switcher in the right corner of the page now shows what other languages are already available.

Language switcher shows all available translations
The language switcher shows all available translations

Creating page lists for different languages

Over time, a wiki can have lots of these translated pages. We want to make sure that users know what pages are available in what language. For this purpose, the language switcher template includes a custom property Languages/tracklang that allows to easily create filtered page lists for this purpose.

In BlueSpice pro, you can include different inline queries on any wiki page. This example lists German language pages in the main namespace and displays them in a category-type output (A-Z listing):

{{#ask:
[[:+]][[Languages/tracklang::de]]
|format=category
}}
Results format "category"
Results format "category"

Explanation of the arguments for this query:

  • [[:+]]: Returns pages only in the main namespace. To show the pages form the entire wiki, simply delete this argument. Other options:
    • [[QM::+]]: Returns pages from the namespace QM
    • [[QM:+||Help:+]]: Returns pages from the namespaces QM and Help.
  • [[Languages/tracklang::de]]: Returns only pages that are marked by the language switcher template as German language pages. Other options:
    • [[Languages/tracklang::+]]: Returns all language pages that are tracked in the wiki by the language switcher template.
    • [[Languages/tracklang::!de]]: Returns all language pages except German pages.
    • [[Languages/tracklang::de||fr]]: Returns all language pages in German and French (in the example above restricted to the main namespace.
  • format=category: returns a category style output.
    • format=ul: returns a list style output
Results format "ul"
Results format "ul"


To see more examples for defining and further modifying a query, go to our SMW-query examples page.

Note:Working with properties requires the Semantic MediaWiki extensions, which are bundled in BlueSpice pro, but not in BlueSpice free. There are, however, alternative approaches for creating page lists in BlueSpice free.


Creating portal pages based on user language settings

Portal pages are pages that serve as entry points to different topics or areas in the portal, often considering the needs of specific user groups. A typical example is the main page of the wiki, which should give users a high-level orientation in the wiki. A portal page is a good place to take the language needs of different users into account.

Here, we can take two different approaches:

  1. Show the same page to all users, but include some content that targets specific user languages.
  2. Show completely separate content to users based on their user language.

What is the user language?

Wiki users can change their own language setting in the user preferences:

User language preference
User language preference

Depending on this setting, users then see the user interface elements in that language as we have seen in previous screenshots. This applies to interface elements that already have translated system messages.

To provide additional support for this setting, we can include checks on wiki pages that determine the user language and serve up additional or alternative information as needed.

Preparing the user language check

Checking for the user language requires that we create a system message for this purpose. This is easy to do, but needs to be done by users in the role admin or structuremanager.

To create a system message for the user language:

  1. Create the page MediaWiki:lang with the content being the language code of the content language of your wiki. If you are not sure in what language your wiki was installed, you can add the magic word {{CONTENTLANGUAGE}} to the source of any wiki page and look at its output. If you have an English wiki, you need to add "en" as the content to this page. If your wiki is German, add "de" instead.
    Page MediaWiki:Lang
    Page MediaWiki:Lang
  2. Create subpages to this page for the user languages you want to support. For example in an English wiki:
    • MediaWiki:Lang/de
    • MediaWiki:Lang/fr

Now we have a mechanism to detect the user language. By checking for the value of the "magic word" {{int:lang}} , we can use it in many different scenarios.

Displaying additional content

To show content on a page only to users with a specific language setting — for example, German — we can add the following check:

{{#ifeq: {{int:lang}}|de|show this content|}}

Switching to different page content

To show entirely different content to users with different language settings, you can prepare different pages and then serve them up as needed. As an example we take the homepage of the wiki.

To display different homepage content based on user language in an English wiki, where the homepage is called Main Page:

  1. Create a subpage for each language you want to support, e.g.
    1. Main Page/en
    2. Main Page/de
    3. Main Page/fr
  2. On the page Main Page, add the following switch:
    {{#switch: {{int:lang}}|de={{:Main Page/de}}|fr={{:Main Page/fr}}|{{:Main Page/en}} }}
    
    Users with language setting "de" will see the content of page Main Page/de, users with "fr" language setting the page Main Page/fr, all other users get the page Main Page/en.

Switching labels

To show different labels or short text snippets directly on a page, we can also use the switch function:

{{#switch:{{int:lang}}|de=Überschrift 2|en=Heading 2}}

To summarize, the following main page can be accomplished in two different ways:

  1. By creating separate subpages for each user language and then transcluding them with a user language check on the actual Main Page.
  2. By loading the actual Main Page and then building the language checks into the page itself. The following picture shows examples of:
    • (1), (2) Switching headings
    • (3) Displaying query results based on the tracked language from the language switcher template (e.g., [[Languages/tracklang::en]])
    • (4) Switching display labels in templates (this can also be applied to page forms)
    • (5) Switching image captions
Content based on user language settings
Content based on user language settings

Switching template and form labels

As the previous screenshot shows, labels in templates (and forms) can also be shown based on user language. You can simply add the switch function directly in the template. The template Template:Contactinfo collects street, zip and city info:

{| class="wikitable"
! {{#switch:{{int:lang}}|en=Street|de=Straße}}
| {{{street|}}}
|-
! {{#switch:{{int:lang}}|en=Zip|de=PLZ}}
| {{{zip|}}}
|-
! {{#switch:{{int:lang}}|en=City|de=Stadt}}
| {{{city|}}}
|}

It displays the different labels as needed:

Multilingual navigation

Currently, there is no easy mechanism to create multilingual navigation menus, such as the main navigation or the custom menu. More support should be coming in one of the next minor releases of BlueSpice (4.2 or 4.3). In the meantime, you can create individual links based on a user's language settings.

Searching content by language

Limiting search results by language
Limiting search results by language
Filtering pages by language
Filtering pages by language

Multilingual categories

An important aspect of organizing content is a well-designed category system for your wiki. By tagging your content, you support both the search functionality and the possibility of creating context-based page lists in all kinds of variations.

To keep an overview of which categories are available translated in different languages and which categories are simply shared by different languages, you can use a prefix mechanism that allows to associate categories by language.

For example, for the category Application, you would use (in an English wiki) the English category APP Application and the German category APPde Anwendung. Both categories could share the category APP SAP.

Multilingual category tree
Multilingual category tree


Whether you even need the separate category APPde Anwendung depends simply on the language proficiencies of your users. You don't need to create a language variation of a category just for finding, for example, all German pages that are related to the concept of "Applications", since the language switcher mechanism already collects this information for you.

Tip:It makes sense to create as many language versions of categories as necessary, but as few categories as possible. To determine if you need a language variation, ask yourself:
  • Who needs this category for what purpose?
  • Is there already a different mechanism (e.g. a SMW-property, an automatically assigned category, the subpage syntax) that can be used to later "collect" pages based on different commonalities.


Creating a root category first

It is also a good idea, to start your category system with a single root category:

Starting with a root category
Starting with a root category


This allows you to later manage your category system without entangling it with other unrelated categories that might be created by users. Besides your category system, other types of categories might coexist:

Sharing subcategories

If you have already assigned a subcategory to a category using the Category manager, there is no mechanism to assign it to a second category. You have to do the assignment manually and directly on the category page. For example, to use the category APP SAP as a subcategory of both the category APP Application and APPde Anwendung:

Subcategory of multiple parent categories
Subcategory of multiple parent categories

The category manager then shows the category APP SAP listed under both parent categories:

Shared subcategory
Shared subcategory
Important!If you delete a shared subcategory from the category manager, it will be deleted from all its parent categories and from all the pages that are assigned to this subcategory.


Querying multilingual categories

To show a list of pages based on categories, you can use different arguments in an ask query.

  • Show all pages in categories DOC Process description OR DOC Prozessbeschreibung:
[[Category:DOC Process description||Category:DOCde Prozessbeschreibung]]
  • Show all pages in all categories related to Applications (both German and English). This also includes the pages in all subcategories of these two main categories:
[[Category:APP Application||APPde Anwendung]]
  • Show all pages in category APP Application including pages from the first level of subcategories only. Do not include English versions of any subcategories that are shared across languages. This ensures that the German pages included by default through the shared subcategory APP SAP are not included in the results
    [[Category:APP Application|+depth=1]][[Languages/tracklang::!de]]
    
Note:To avoid deleted pages and redirects showing up in your results list, you can add the property [[Modification date::+]] to any of your queries.



To submit feedback about this documentation, visit our community forum.

Discussions