Multilingual

If you need to build yourself a multilingual knowledge base, documentation site, or intranet. doctor is here to help you out with that.

doctor allows you to configure multilingual on site- and page-level. To make use of doctor its multilingual features, you have to follow this guide.

Configure `doctor` in a multilingual site

The first step is to configure doctor for multilingual site usage. You need to do this in the doctor.json file.

Example setup:

{
  "multilingual": {
    "enableTranslations": true,
    "languages": [
      1043
    ],
    "overwriteTranslationsOnChange": true,
    "translator": null
  }
}

More information about the setup can be found on the doctor.json page under the multilingual section.

Required configuration on page level

When creating multilingual pages, you will need to link each of the language pages to the source page.

Localization source page

On your source page, you add the localization property to its front matter. You can do this as follows:

localization:
  "nl-nl": ./home.nl.lang.md

The localization property contains the following. locale name and relative path to the linked language page.

The languages setting takes the same locale names as the localization front matter, so both sides use one vocabulary:

{
  "multilingual": {
    "enableTranslations": true,
    "languages": ["nl-nl", "fr-fr", "es-es"]
  }
}

LCIDs keep working as well, and the two styles can be mixed: ["nl-nl", 1036] is the same as ["nl-nl", "fr-fr"]. An entry which is neither stops the run instead of quietly changing the languages of your site.

Localization translation page

Name the translation page with a .lang.md suffix, home.nl.lang.md in the above example. That suffix is what tells doctor the file holds the content of a localized page: it is left out of the standard page processing and published in the localization phase instead, under the URL SharePoint issues for the translation.

Because a translation never gets a slug of its own, a slug in its front matter is ignored.

By default, SharePoint will copy the header settings from the source page. If you want to override these settings, you can add the same options as all other pages.

Using Azure Translator service

If you want to make use of the Azure Translator service which is part of the Azure Cognitive Services family. You will first need to create the translator service in your Azure tenant and provide the following config:

{
  "multilingual": {
    "enableTranslations": true,
    "languages": [
      1043
    ],
    "overwriteTranslationsOnChange": true,
    "translator": {
      "key": "<subscription key>",
      "endpoint": "https://api.cognitive.microsofttranslator.com/",
      "region": "<region name, example: westeurope>"
    }
  }
}

Both endpoint forms Azure hands out are supported:

The global endpoint: https://api.cognitive.microsofttranslator.com
The endpoint of your own resource: https://<your-resource>.cognitiveservices.azure.com

Automatically translate pages

When you want to make use of these APIs for page translations. All you need to do is specifying the localization property to its front matter of the page. In this case, you do not need to specify the path to the page. As the page will be translated on the fly.

localization:
  "nl-nl":