Multilingual

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

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

Configure bdoctor in a multilingual site

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

Example setup:

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

More information about the setup can be found on the bdoctor.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.

Info

An overview of the supported LCIDs for SharePoint can be found on Supported LCIDs by SharePoint.

Warning

languages is applied to the site as-is, it replaces the languages which were enabled on it. Any locale you use in a localization front matter has to be in this list, otherwise SharePoint refuses to create the translation. Better Doctor reports the locales which are missing from it.

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

Info

The file name identifies a translation. type: translation may document its purpose, but does not replace the .lang.md naming convention.

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.

Info

Sample of how you can use multilingual with bdoctor has been provided in https://github.com/woznet/better-doctor-sample.

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

Info

A trailing slash on the endpoint is fine, bdoctor normalizes it. If the run reports Resource Not Found, the endpoint is reachable but the key or region does not match the resource.

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

Info

When you are going to run bdoctor. There will be *.machinetranslated.md pages created next to the parent page. This is done to not create any conflicts with the referenced pages and images. At the end of the process, bdoctor will remove these generated pages. During a debug run, they will not be removed.

Rendering and migration

All translations use the Better Doctor Markdown custom web part. Source pages publish first; translations remain a separate later step, including when only a .lang.md file changed and its source was skipped as unchanged.

Human-maintained .lang.md files follow the Markdown preparation path and the same allowHtml, shortcode, partial, and math settings as other content. Machine translation still operates on HTML: Better Doctor expands partials before translation and publishes the resulting body as HTML compatibility content, not Markdown to be parsed a second time. Code, Mermaid, and TeX block sources are protected from prose translation.

Math remains off unless markdown.enableMath or --enableMath true enables it. A browser preview cannot regenerate Azure translations or rerun local partials/custom shortcode modules. Generated HTML is read-only in the inspection/export view; make lasting changes in the repository and republish.

Existing localized legacy controls also need confirmed migration. Include both human translations and generated HTML in the tenant pilot, checking source ordering, locale URLs, protected block sources, and rollback. Those browser/tenant checks have not been executed for this change.