''Hallo Welt!'' has created a migration tool that can be used to import Confluence spaces into a MediaWiki or BlueSpice installation. This is a command line tool and you need access to your MediaWiki or BlueSpice server environment.

==Migration tool==
The [https://github.com/hallowelt/migrate-confluence/releases/ migration tool can be found on GitHub] and is [https://github.com/hallowelt/migrate-confluence?tab=readme-ov-file#migrate-confluence-xml-export-to-mediawiki-import-data documented there].

It is also available as [https://hub.docker.com/r/bluespice/migrate-confluence docker container] for ease of installation and better automation.

==Extensions==
The output generated by the tool contains certain elements that require '''additional extensions''' to activate. These extensions are already included in a BlueSpice Pro installation:

#[[mediawikiwiki:Extension:TemplateStyles|TemplateStyles]]
#[[mediawikiwiki:Extension:ParserFunctions|ParserFunctions]]
#[[mediawikiwiki:Extension:SimpleTasks|SimpleTasks]]
#[[mediawikiwiki:Extension:Semantic_MediaWiki|Semantic MediaWiki]]
#[[mediawikiwiki:Extension:Header_Tabs|HeaderTabs]]
#[[mediawikiwiki:Extension:SubPageList|SubPageList]]

==Macro check==
On the BlueSpice website, you can use a [https://bluespice.com/confluence-migration-process/#confluence-migration-input-desktop macro check] to see which Confluence macros are not automatically converted. If an important macro is marked as unsupported, the content can most likely still be transferred.
[[File:Confluence macro check.png|alt=Textarea for adding a list of macros (with step-by-step instructions)|center|thumb|650x650px|Macro check]]

== Not migrated ==
The following Confluence elements are excluded from the migration:

*User identities
*Comments
*Various macros
*Some layouts
*Files in an area that cannot be assigned to a page

== Roadmap ==
* April '26: Allow for parallel processing (ERM45405) - Speeds up conversion of large Confluence exports
* April '26: Migrate page comments to [[mw:Extension:CommentStreams]] threads (ERM46627) - Additional content
* April '26: Add support for historic page and file revisions (ERM35013) - Additional content

==More information==

*https://bluespice.com/migration-from-confluence-to-bluespice-mediawiki/
*https://bluespice.com/mediawiki-versus-confluence-not-a-question-of-features/

[[de:Confluence Migration]]
[[Category:Setup]]

2026-03-19T16:39:47Z

Margit.link-rodrigue: (username removed) (log details removed)

The extension '''HitCounter''' counts human page views, but does not ignore multiple visits.

== How it works ==
The extension counts page views and stores them in the MediaWiki database field <code>page.page_counter</code>. Other extensions use this field to return page visit numbers.

== Output of the page views number ==
The extensions Semantic MediaWiki (SMW) and DPL3 (DPL), which are bundled with the BlueSpice distribution, both use the field value for <code>page.page_counter.</code> However, the number that is returned in SMW and DPL queries usually differs.

=== Why SMW and DPL show different page-view numbers ===
Even when both rely on HitCounters, they read the values at '''different points in time''' and with '''different caching layers''', which leads to discrepancies. Below are the main reasons.
{| class="wikitable"
!Feature
!Source
!Updates
!May lag?
|-
!'''SMW <code>Number_of_page_views</code>'''
|SMW store (snapshot)
|Only when page is parsed/resaved
|✔ Yes
|-
!'''DPL <code>ordermethod=counter</code>'''
|<code>page.page_counter</code> (live)
|Immediately when HitCounters logs a view
|✘ No
|}

==== SMW stores values (snapshot) – DPL reads live values ====
'''SMW’s property "Number_of_page_views":'''

* SMW stores the value in its DataStore.
* A page must be parsed/resaved for SMW to update the stored property.
* Therefore: the number can lag behind the real counter.

'''DPL3 ordermethod=counter:'''

* DPL reads the current page.page_counter field directly.
* It does not use SMW data.
* This always shows the latest number, as recorded by HitCounters.

'''Result:''' SMW can show an older number than DPL.

==== Caching differences (ParserCache vs. SMW store) ====
'''SMW:'''

* Uses its own store (SQL + SMW query cache).
* Property values only change when the page is reparsed.

'''DPL:'''

* Uses MediaWiki’s normal page cache but reads the counter directly every time.

If a page received new hits since its last SMW update:

* DPL shows the new higher number
* SMW still shows the older value until the page is updated

=== HitCounters updates only on full page views ===
HitCounters increments the view count only when:

* A normal, human page view occurs

* Not on: API calls, bot views, thumbnail loads, SMW queries, DPL queries

This means numbers may diverge temporarily depending on viewing patterns.

==== Some skins bypass counters ====
If some users view pages via:

* mobile skin
* VisualEditor previews
* REST requests
* API-parsed pages

…those views may not be counted.

If these users access a page differently at different times, SMW and DPL appear inconsistent.

==== SMW’s “Number_of_page_views” rounds or normalizes values ====
SMW’s special property sometimes:

* stores the view count as an integer
* may update only when semantic parsing occurs
* may skip updates depending on SMW’s DeferredUpdate behavior

DPL always shows the raw integer.

==== Quick way to test ====
Take a page with a visible difference (example: SMW shows 120, DPL shows 132).

Do this:

# Open the page → Edit → Save (no change needed). This forces SMW to refresh <code>Number_of_page_views</code>.
# Run your SMW query again.

You will see SMW “catch up” to the DPL counter. However, the values might still differ based on the above reasons.

Example queries:<syntaxhighlight lang="text">
'''Output SMW:'''
{{#ask: [[:+]] [[Modification date::+]]
|?Number_of_page_views
|limit=5
|format=ul
|headers=hide
|sort=Number_of_page_views
|order=desc
|searchlabel=
}}

'''Output DPL:'''
<dpl>
namespace =
ordermethod = counter
order = descending
count = 5
addpagecounter = true
</dpl>
</syntaxhighlight>
'''Output SMW:'''
{{#ask: [[:+]] [[Modification date::+]]
|?Number_of_page_views
|limit=5
|format=ul
|headers=hide
|sort=Number_of_page_views
|order=desc
|searchlabel=
}}

'''Output DPL:'''
<dpl>
namespace =
ordermethod = counter
order = descending
count = 5
addpagecounter = true
</dpl>

2026-03-19T16:09:30Z

Margit.link-rodrigue:

2026-03-16T15:22:50Z

Margit.link-rodrigue:

The translation mechanism in a Wiki farm is controlled via the '''BlueSpiceTranslationTransfer''' extension.{{DISPLAYTITLE:Translations in a Wiki farm (TranslationTransfer)}}

{{Textbox|boxtype=important|header=DeepL API key required:|text=This feature requires a valid DeepL API key, which is not provided by BlueSpice. The key is entered in the [[Manual:Extension/BlueSpiceConfigManager#BlueSpiceTranslationTransfer_(farm)|Config manager of the translation source wiki]].|icon=yes}}

== Determining the source wiki and the target wikis ==
The translation mechanism requires one source and one or multiple target wiki. The content language of the source wiki determines what wiki instance is the source wiki in the farm. For example, if the root wiki is installed as a German wiki (DE as content language), then there '''must be an instance in the wiki named DE.''' This is the source wiki from which translations can be pushed to other language wikis.

The translation mechanism requires a source wiki and one or more target wikis.

The content language of the root wiki determines which wiki instance in the farm serves as the source wiki for translations. The root wiki is the wiki from which the other instances are generated from the page ''Special:FarmManager''.

For example, if the root wiki is installed as a German wiki (with the content language DE), '''an additional instance named DE must exist in the wiki'''. This DE instance now functions as the source wiki for translations. From there, translations of wiki pages into other language wikis can be generated.

The page tools of the wiki pages therefore automatically displays a translation link, even if no DeepL API key has been entered.

=== Creating the target wikis ===
Language wikis are always created with their [[wikipedia:ISO_639-1|two-letter ISO 639-1 language code]] (e.g., DE for the German language instance, FR for the French one). During translation, any translation instance supported by the DeepL translation service can be created.

This also means that a wiki instance named IT is automatically recognized as a language wiki. An instance must then be created for the IT department that does not correspond to the language code for Italian (e.g., IT-Wiki).

=== Matching path and content language ===
When creating a wiki instance, you must ensure that both the path and the content language match the ISO language code. Otherwise, the instance will not be recognized as a language wiki. Subsequent reconfiguration of wikis that already contain content can be difficult, as some terms are language-specific (e.g., the syntax of image attributes).
[[File:Wiki farm - create language instance.png|alt=Dialog box for creating an English language instance in Wikifarm|center|thumb|450x450px|Dialog window for creating a new language instance with site name (1), path name (2) and matching content language (3) in an English root wiki.]]
The relationship between the instances of a wiki farm with regard to translation can therefore be visualized as follows:<drawio filename="translation_wikis" alt="Diagram showing a root wiki and four other wikis in the same farm">

</drawio>

If a wiki farm requires a different setup, the server configuration must be adjusted accordingly by a server administrator (only possible for on-premises installations).

== Translation of a page ==
Pages can be translated from the source wiki and automatically created in another language wiki instance.

To translate a page:
# '''Click''' on the ''Translate'' link in the page tools. A dialog opens.[[File:Manual:Extension BlueSpiceTranslationTransfer 1743770053694.png|alt=Page tools with highlighted "Translate" link|center|thumb|206x206px|Translate link]]
# '''Select''' a target language. The number of available languages depends on available language instances in your wiki farm.[[File:Manual:Extension BlueSpiceTranslationTransfer 1743770108045.png|alt=Language selction dialog with "Deutsch" as selected language|center|thumb|250x250px|Select target language]]
# '''Click''' ''Translate'' to start the translation.
# '''Check''' the suggested page name in the target wiki and change it if necessary. This dialog box only appears for the first translation of the page.[[File:Manual:Extension BlueSpiceTranslationTransfer 1743770150061.png|alt=Dialog for setting the page name in the target wiki|center|thumb|400x400px|Review or change target page name]]
# '''Click''' ''Translate'' again to save the page name. The translation preview is shown.[[File:TranslationTransfer preview.png|alt=Preview window with translated wiki page|center|thumb|400x400px|Translation preview]]
# '''Click''' ''Save'' to save the translated page in the target wiki. A confirmation dialog window shows the result of the transfer.[[File:TranslationTransfer confirmation.png|center|thumb|350x350px|Translation confirmation|alt=Confirmation dialog with information about one transferred embedded template.]]
# '''Click''' ''Done''. You can now go directly to the page in the target wiki. The original language page now shows a language selector in the title area.[[File:Manual:Extension BlueSpiceTranslationTransfer 1743769862375.png|alt=Language selector with "Deutsch" as option|center|thumb|200x200px|Language selector ]]

== Subsequent translations ==
If a page already exists in the target wiki, embedded resources like templates are not pushed to the target wiki again. Templates are maintained separately in each language wiki, since the translation service cannot determine which template elements need translation. After the translation is complete, the wiki shows a confirmation window that lists any embedded resources that have not been transferred to the target wiki.
[[File:TranslationTransfer embedded resources.png|alt=Dialog window that shows that one template has not been copied to the target wiki|center|thumb|350x350px|Notice about embedded resources]]

== Merge page content ==
If a page has already been translated, subsequent translations overwrite the previous page.

However, it is possible to configure in the server to first store subsequent translations in a draft namespace. Users than have to merge any changes between the translation revisions manually. In this case, see the [[Manual:Extension/MergeArticles|documentation of the MergeArticles extension]].

== Translated elements ==
The translated content during the translation process includes:

* '''Page text'''
* '''Page title''' (the title can be adjusted during the initial translation)
* '''Display title'''
* '''Categories'''
** The categories specified on a page are translated during the initial translation of the page, unless the categories have already been translated via another wiki page.
** If a category from the source wiki already exists in the target wiki due to a previous translation of the page or due to a translation via another page, it is excluded from further translation. This prevents the category from being replaced by the translation service with a new, different translation.
* '''Internal links'''
** A link to a wiki page links to the original page in the source wiki if it does not exist in the target wiki. Example:
*** If the English page A links to the English page B, the German translation page A will link to the English page B if it does not exist in German.
*** If the English page A links to the English page B, the German translation page A will link to the German translation page B if it exists in German.
* '''Embedded image files (png, jpg, gif,...)''' are transferred to the target wiki:
** The file name is retained
** The description and alternative text of embedded files are translated
* '''Templates''': Templates are transferred if they do not exist in the target wiki
* '''Magic words''' are translated into their canonical name (EN)
* '''Code blocks''' themselves are not translated; comments within code blocks are translated
{{Textbox|boxtype=note|header=Note:|text=Limitation: If a page is too large, the DeepL API cannot translate it. The best option is to split the page into smaller subpages.|icon=yes}}

== Non-translated or non-transferred elements ==
The following elements are not considered for translation:

* '''Media (pdf, docx, pdf,...) :''' The link description is translated, but the document itslelf is not transferred. It has to be manually uploaded, if a target language version of the document exists locally.
* '''Templates that already exist in the target wiki:''' Templates are not overwritten in the target wiki, if they already exist there.

* '''Forms for templates ([[Reference:Page Forms|Page Forms]]):''' Forms must be manually transferred to the target wikis (see [[Manual:Extension/ContentTransfer|ContentTransfer]]) and manually translated.

* '''File attachments:''' Files are not transferred to the target wiki if they are only displayed as attachments on a page using the <code><nowiki><attachments></nowiki></code> tag.
* '''Transcluded pages:''' Currently, transcluded pages are moved to the target wiki without translation.
* '''Code blocks''' themselves are not translated; comments within code blocks are translated.

== Excluding content from translation ==

=== Excluding text {{Bsvs|bsvFrom=5.2.2}} ===
Before you write the text:

# '''Open''' the "insert (+) menu" in the editor toolbar.
# '''Click''' ''Exclude from translation.''
# '''Add''' the text you want to exclude.
# '''Click''' ''Insert''.

If your text already exists on the page, you need to switch to source edit mode and manually apply the "ignore" tag which has a start and an end tag:<syntaxhighlight lang="text">
<translation:ignore>your text here</translation:ignore>
</syntaxhighlight>

=== Excluding image files ===
A tag can be inserted on the source page to exclude all included files for a specific page from the translation process.

This way, changes made to files in the target system will not be overwritten during the next translation.

Steps to exclude files from translation:

# '''Insert''' the tag <code><nowiki>__BS_NO_AUTOMATIC_DOCUMENT_TRANSLATION__</nowiki></code> in the source code of the page to be translated.
# '''Translate''' the page into the target language. The source wiki files are still displayed in the preview, but they will not be transferred.
# '''Check''' the target page. The file link has been retained with the original name in the source code. The file itself has not been transferred. The file is displayed on the page as a "required file" (redlink). This makes it clear that files are missing and may need to be replaced.

Note: If the file already exists on the target wiki, it will still be displayed as correct.

== Translation overview ==
An overview of all translations is available under <code>Special:TranslationsOverview</code>.
[[File:Manual:Extension BlueSpiceTranslationTransfer 1743771014879.png|center|thumb|700x700px|Translation overview]]

== Translation dictionary ==
The dictionary with all page titles and links can be viewed under <code>Special:TranslationDictionary</code>.

If the title of a target page needs to be adapted after the first translation, this can be done on this special page.
[[File:Manual:Extension BlueSpiceTranslationTransfer 1743771305481.png|center|thumb|600x600px|Translation Dictionary ]]
If a source page is renamed, the titles are automatically retranslated and the title translations are updated in the database and in the wiki.

The different translation versions are still linked correctly. The redirect selected on the source page is also set up on the corresponding target pages.

== Translation glossary ==
Glossary entries for the translation can be maintained on the <code>Special:TranslationsGlossary</code> page. This ensures that certain terms from the source language are always translated with a specific term from the target language. This applies to both the page title and the normal page content.

The maintained wiki glossary is transferred to the DeepL glossary and used in the translation.

([https://developers.deepl.com/docs/api-reference/glossaries#list-supported-glossary-language-pairs See the list of supported glossary languages in the DeepL documentation])
[[File:Manual:Extension BlueSpiceTranslationTransfer 1743771485615.png|center|thumb|600x600px|Translation glossary]]

Please follow these recommendations for defining glossary terms (provided by the DeepL service):

* In general, we recommend to use use idiomatic capitalization when adding an entry in the glossary. Please capitalize/lowercase when it is appropriate in the respective language.
* Since in English, nouns are generally with a lowercase, we highly recommend to use the glossary pair "cat - Katze". Otherwise, the AI will recognise "Cat" (with a capital letter) as a name.

Best practises for glossaries:

* no plural
* no past tense
* use idiomatic capitalization (capitalize/lowercase when it’s appropriate in the respective language)
* use of prefixed articles for nouns is irrelevant and can be ignored
* use infinitive markers with verbs, such as “to” in English to avoid “misunderstandings” ( ''Example: to rain → regnen; rain → Regen)''

== Additional information ==
==== Configuration of wiki structure and namespaces ====

*The translation processes (i.e. which wiki/language can be translated into which wiki/language) must be configured.
*The farm may contain some wiki instances that do not use translation workflows.
*Caution: DeepL translation is not available in all existing languages.

The links between the source and target namespaces must be maintained under <code>Special:BlueSpiceConfigManager</code> and <code>BlueSpiceTranslationTransfer</code> extension.

For example, the pages from the DE source namespace ‘Finanzen’ must be translated into the EN target namespace ‘Finance’.
[[File:Manual:Extension BlueSpiceTranslationTransfer 1743771917649.png|center|thumb|600x600px|Namespace configuration]]
If the pages must first be created in the draft namespace after translation, this must also be [[Reference:MergeArticles|configured in the backend]].

==== Configuration DeepL API ====
The configuration is required in the source wiki.

{{#dpl:title=Manual:Extension/BlueSpiceConfigManager|include=#DeepL API}}

== Error messages ==
There can be some translation conflicts between source and target wikis when pages are deleted or renamed without a redirect. For example:

# '''Source page has been moved:''' A page was moved in an English source wiki from <code>A new page</code> to <code>A new page 1</code> without a redirect. The page was originally translated to the German wiki from page <code>Eine neue Seite</code>. When the user wants to translate <code>A new page 1</code> to <code>Eine neue Seite</code>, the wiki shows an error message that the suggested targt page already exists:[[File:translationtransfer error1.png|alt=page cannot be translated to selected page title because target page already exists|center|thumb|450x450px|Translation transfer error message]]'''Solution:''' It is necessary to delete the original mapping between the two pages <code>A new page</code> and <code>Eine neue Seite</code> from the [[Manual:Extension/BlueSpiceTranslationTransfer#Translation dictionary|Translation dictionary]]. After that, it is possible to set the translation target for <code>A new page 1</code> without problems to <code>Eine neue Seite</code> without getting an error message. The target page <code>Eine neue Seite</code> will keep its version history.

== Ad-hoc Translation ==
In a wiki instance with a configured DeepL API key, ad-hoc translations are possible. This means that users whose language settings differ from the wiki's content language are shown a link to translate the page in their language . This translation is only valid until the page is reloaded. See the documentation for [[Manual:Extension/AdhocTranslation|ad-hoc translations]].

{{Box Links-en|Topic1=[[Manual:Extension/ContentTransfer]]|Topic2=[[Manual:Extension/MergeArticles]]|Topic3=[[Manual:Extension/AdhocTranslation]]}}

{{translation}}

File:Wiki farm - create language instance.png

2026-03-16T15:22:39Z

Margit.link-rodrigue: Margit.link-rodrigue uploaded a new version of File:Wiki farm - create language instance.png