Migrating to Multilingual Pages in SharePoint Online

TL;DR (Summary)

This article is pretty long, so here are the key facts up-front on what to do:

1. Make sure that the multilanguage solution in Confluence is indeed Scroll Translations, as this is supported.
2. Recommendation: Create SharePoint target sites with the same default language that is used in Confluence.
3. Enable the multilinguality feature in your target SharePoint site(s) and add languages.
4. Create appsettings.json to configure WikiTraccs.
5. Start a migration; each language should now get its own page in SharePoint.

A brief introduction to multilingual SharePoint

Over time, there have been many approaches to multilinguality in SharePoint, both out-of-the-box ones and from third parties.

When searching for information on multilingual SharePoint sites remember to look at the date of information you find. Documentation about multilingual SharePoint pages should be newer than 1-2 years, and for SharePoint Online, not SharePoint on-premises.

There are also different approaches depending on whether you want to translate the SharePoint user interface (list titles, content types etc.), or the content of pages (text, web parts).

We shall focus on modern approaches to translating content of modern pages in SharePoint Online.

In general, two approaches of making pages appear in different languages are common in SharePoint:

• providing multiple translations on one page
• using the out-of-the-box feature for multilingual modern SharePoint pages, creating one page per translation

The following sections look at the second option, the out-of-the-box feature to create one page per translation.

How do multilingual pages work in SharePoint?

Microsoft has an out-of-the-box feature for creating page translations documented here: Create multilingual SharePoint sites, pages, and news.

It is disabled by default and has to be switched on on a per-site basis.

When this feature is enabled, a separate page can be created for each supported language. SharePoint takes care of routing the user to the page that matches their profile language.

And that’s basically it. Each language get’s a separate SharePoint page. The pages are connected by metadata.

WikiTraccs can create those translated pages, based on translations it finds in the source Confluence pages.

How to activate multilingual pages in a SharePoint site?

Find your way to the Site settings and click the Language settings link:

By default, the feature is off:

Enable translations and choose the languages SharePoint pages should be translatable to:

Now each page gets a language chooser:

The authoring experience for pages changes slightly in that additional controls will be available to manage the creation and translation of language-specific pages:

Looking at the Site Pages library you will that SharePoint creates a folder for each language where translated pages are stored.

Here it’s the de folder for German pages and the nl folder for Dutch pages:

Note

A SharePoint site’s default language is set when creating the site:

Once set, the default language cannot be changed.

How to create multilingual pages with WikiTraccs?

WikiTraccs knows about SharePoint’s multilingual pages feature and can create language-specific pages, based on translations it finds in Confluence.

Since this is an advanced and not-so-often-used feature, WikiTraccs has to be told to use it via its configuration file, appsettings.json.

Create appsettings.json and add the following configuration:

{
  "CustomSettings": {
    "Translations": {
      "TranslationMigrationModes": [
        "MultiForSharePointSiteLanguages"
      ]
    }
  }
}

Restart WikiTraccs after configuring this.

The next migration of multilingual Confluence pages will create a separate page for each language.

Migrating a page that is available in English, German, and Dutch will result in all three languages being present in SharePoint as well:

When there is a translation missing in Confluence, it will be in SharePoint as well (here Dutch is missing):

How does WikiTraccs handle…

… a mismatch in default languages?

Let’s assume the default language of a Confluence space is German and the target SharePoint site’s default language is English. Does it matter?

WikiTraccs doesn’t care. It maps each language found in Confluence to a language that has been enabled for the target SharePoint site.

WikiTraccs will always create a page in the target site’s default language, though. If the source Confluence page doesn’t provide a translation for this language, an empty SharePoint page will be created.

… a language not being available in the SharePoint site?

Before migrating, you must configure the list of available languages in each target SharePoint site.

When migrating multilingual Confluence pages, WikiTraccs maps to languages that are available (as per your configuration) for translation in the target SharePoint site.

For example, this configuration enables WikiTraccs to create pages in English, German, and Dutch. But not French:

If the source Confluence page provides a translation for a language that is not enabled in the target SharePoint site, no page will be created for this language. It won’t be available in SharePoint.

So, with above configuration, a French translation would be left behind and won’t be available as SharePoint page. In the log file, there will be a corresponding Warning message.

Limitations of WikiTraccs with Regard to Multilingual Pages

As this feature is rarely used, there are limitations.

Permission Migration

The permission migration doesn’t know about multilingual pages. (But you shouldn’t migrate permissions anyway.)

Migrated Confluence page restrictions will only be applied to the SharePoint page that has the default site language.

Delta Migration, Updating Pages

Before updating already migrated pages, the existing SharePoint pages need to be manually deleted from all language folders in the Site Pages library.

Page Attachments

Confluence page attachments are migrated to the attachments folder of the page that has the default site language. The translated SharePoint pages refer to those files as well.

This has implications for restricting access to single SharePoint pages. When removing or granting access on a single SharePoint page, SharePoint also removes or grants access on the attachment folder.

Caveats of Multilingual SharePoint Pages

There are implications of each translation being a separate SharePoint page. The following points apply to the SharePoint feature in general.

Permissions: Retricting permissions on one translated page doesn’t restrict permissions on the other translated pages.

Attachments: Each page gets its own attachments folder. For three translations this means three attachment folders. This can be confusing and can cause attachments to be unavailable if a subset of translated pages is access-restricted. It might also lead to duplicates if the same attachment is dropped onto different translation pages, each ending up in a different folder.

Search: All pages are indexed separately by search and can be surfaced via search. This might be confusing; or duplicate detection kicks in and hides pages from search results.

Comments: Each translated page has its own comments section.

Metrics: Page views, likes etc. are counted separately per translated page. There is no easy way to get overall metrics for a page that includes all translations.