Manual:Extension/BlueSpiceTranslationTransfer

DeepL API key required: This feature requires a valid DeepL API key, which is not provided by BlueSpice. The key is entered in the Config manager of the translation source wiki.

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

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:

1. Click on the Translate link in the page tools. A dialog opens.
2. Select a target language.
3. Click Translate to start the translation.
4. 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.
5. Click Translate again to save the page name. The translation is displayed.
6. Click Save to save the translated page in the target wiki. You can now go directly to the page in the target wiki, translate it into another language (if configured) or close the dialog box without taking any further action.

• 
  Translation button
• 
  Language selection dialogue
• 
  Customise page title
• 
  Page translation display and confirmation
• 
  Link between the language versions

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 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 German translation page B.
• Embedded files are transferred to the target wiki:
  • The file name is retained
  • The description and alternative text of embedded files are translated
• Magic words are translated into their canonical name (EN)
• Transcluded pages are transferred even without translation
• Code blocks themselves are not translated; comments within code blocks are translated.
• Limitation: If a page is too large, the DeepL API cannot translate it. The best option is to split the page into smaller subpages.

Non-translated or transferred elements

The following elements are not considered for translation:

• Template contents: Templates are transferred to the target wiki during translation, but the content is not translated.

• Forms for templates (Page Forms): Forms must be manually transferred to the target wikis (see 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 <attachments> tag.

Excluding files from translation

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:

1. Insert the tag __BS_NO_AUTOMATIC_DOCUMENT_TRANSLATION__ in the source code of the page to be translated.
2. Translate the page into the target language. The source wiki files are still displayed in the preview, but they will not be transferred.
3. 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.

Excluding files from translation

A tag can be inserted on the source page to exclude all embedded 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:

1. Insert the tag __BS_NO_AUTOMATIC_DOCUMENT_TRANSLATION__ in the source code of the page to be translated.
2. Translate the page into the target language. The source wiki files will still be displayed in the preview, but they will not be transferred.
3. 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 be displayed.

Translation overview

An overview of all translations is available under Special:TranslationsOverview.

Translation overview

Translation Dictionary

The dictionary with all page titles and links can be viewed under Special:TranslationDictionary.

If the title of a target page needs to be adapted after the first translation, this can be done on this special page.

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 Special:TranslationsGlossary 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.

(See the list of supported glossary languages in the DeepL documentation)

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 Special:BlueSpiceConfigManager and BlueSpiceTranslationTransfer extension.

For example, the pages from the DE source namespace ‘Finanzen’ must be translated into the EN target namespace ‘Finance’.

Namespace configuration

If the pages must first be created in the draft namespace after translation, this must also be configured in the backend.

Configuration DeepL API

The configuration is required in the source wiki.

The DeepL API configuration can be accessed from the Feature Content Structuring.

DeepL API Key Configuration

Ad-hoc Translation

In a wiki instance with a configured DeepL API key, ad-hoc translations are possible. This meaans 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 ad-hoc translations.

Related info

• Manual:Extension/ContentTransfer
• Manual:Extension/MergeArticles
• Manual:Extension/AdhocTranslation

Technical Reference: BlueSpiceTranslationTransfer

PDF exclude - start

---

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

PDF exclude - end