Manual:Extension/BlueSpiceTranslationTransfer

PDF exclude - start

← Extension

PDF exclude - end

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

Matching path and content language

Set the correct target 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. The site name can be freely chosen, however it is recommended to consistently use the language code here as well. Subsequent reconfiguration of wikis that already contain content can be difficult, as some terms are language-specific (e.g., the syntax of image attributes).

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:

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.

   

   Translate link

2. Select a target language. The number of available languages depends on available language instances in your wiki farm.

   

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

   

   Review or change target page name

5. Click Translate again to save the page name. The translation preview is shown.

   

   Translation preview

6. Click Save to save the translated page in the target wiki. A confirmation dialog window shows the result of the transfer.

   

   Translation confirmation

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

   

   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.

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 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: Wiki links are translated. If a page does not exist in the target wiki, it is displayed accordingly as a "wanted page" (red link).

• Embedded image files (png, jpg, gif,...) are transferred to the target wiki:
  • The file name is retained. For text links, the link label is translated.
  • The description and alternative text of embedded files are translated.
• Attachments: Attachments using the <attachments> tag are transferred like all files to the target wiki. The file label is translated.
• Media (pdf, docx, xlsx, ...): The link description is translated, and the original document is copied to the target wiki.
• Galleries: When a gallery droplet is inserted on a page, the file names are not translated, and the gallery is displayed correctly in the target wiki. The image captions are translated.
• Templates: Templates are transferred with their original page name if they do not exist in the target wiki. The contents of the template are not translated. The different language versions of templates are maintained manually for each language. If template parameters should be translated, they have to be configured server-side.
• Magic words are translated into their canonical name (EN).

Note:

Limitation in earlier BlueSpice versions: If a page is too large, the DeepL API cannot translate it. The best approach is to split the page into smaller subpages or upgrade to the latest version of BlueSpice.

Currently, the page is sent to the translation service in multiple batches and should therefore no longer trigger an error message.

Technical Reference: BlueSpiceTranslationTransfer

PDF exclude - start

---

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

PDF exclude - end