Manual:Extension/BlueSpiceTranslationTransfer

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

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

<drawio filename="translation_wikis" alt="Diagram showing a root wiki and four other wikis in the same farm">

</drawio>

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

# '''Select''' a 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.

# '''Click''' ''Translate'' again to save the page name. The translation is displayed.

# '''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.

<gallery widths="220" heights="200">

File:Manual:Extension BlueSpiceTranslationTransfer 1743770053694.png|Translation button

File:Manual:Extension BlueSpiceTranslationTransfer 1743770108045.png|Language selection dialogue

File:Manual:Extension BlueSpiceTranslationTransfer 1743770150061.png|Customise page title

File:Manual:Extension BlueSpiceTranslationTransfer 1743770194009.png|Page translation display and confirmation

File:Manual:Extension BlueSpiceTranslationTransfer 1743769862375.png|Link between the language versions

</gallery>

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

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

# '''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.

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

# '''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 will still be 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 be displayed.

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

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

== 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 [[Manual:Extension/AdhocTranslation|ad-hoc translations]].

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

{{translation}}