Part 5: Localization

Part 5: Localization

Update (28/08/2017)

A complete and optional documentation is now available along the PnP Starter Intranet version 2.0.0 with an additional fee. It includes:
– A French or English version with free updates following the latest version of the solution
– A complete development guide (about 100 pages) on how to maintain and customize this solution (add a new language, create a new component, etc.)
– A complete user guide (about 40 pages) on how to use this solution from a contributor point of view (create content, manage navigation, etc.)

This present documentation is still relevant be only for the first version(s) of the PnP Starter Intranet solution.


Thank you for supporting us!

Working in Québec, implement multilingual intranets is something very familiar. In the past, I used the SharePoint “variations” feature for on premise projects but with SharePoint Online, things became more complicated. Why?

  • First, the poor authoring experience. Even if it is an OOTB feature, I’m not a big fan of variations especially for this aspect (and some others*). Variations slow the user experience and productivity significantly. Users have to wait several minutes to be able to create translated content because of multiple synchronization jobs. With SharePoint on premise, it was possible to control the timer jobs schedule settings but with SharePoint Online, you don’t have access to this part anymore so using variations as a multilingual solution within Office 365 is not a viable option in my opinion.
  • Then, because of variations depend heavily on timer jobs, they are not a good candidate for automation as well. It can slow your delivery process significantly by tweaking your deployment procedure just to support this. This is not worth it.
  • From an architectural point of view variations are too invasive. By experience, the multilingual part in a SharePoint intranet project is by far the most time consuming among the other features. With variations you have to design your whole solution around it, you can’t implement this part “later”.
  • Finally, Microsoft doesn’t seem to invest a lot for multilingual features within Office 365 especially for SharePoint. Implementing your own basic multilingual system is not something that will be obsolete soon.

*In a previous publication about SharePoint intranets, I’ve made a “SharePoint fact list ” about variations. It is available here (in French).

In the Office 365 starter intranet solution, several UI elements are translated:

  • Navigation links in menus (via taxonomy term translations)
  • Dates (via the Moment.js library)
  • Custom control labels and messages (via the i18next library)
  • SharePoint default labels in search display templates (via the i18next library)

Getting the language context: a matter of perspective

The main question coming with a multilingual solution implementation within SharePoint is: what gives you the current language context? Should it be the current site language? The current page language? The user preferred language? Something else? Most SharePoint multilingual solutions use the current site language to adapt the experience like the default SharePoint variations feature do. The problem with this approach is that you have to create one site per language. If you have a complex structure with multiple sub sites, it can become a nightmare to manage. Here, I wanted to create something very simple: a basic page association mechanism using the current page language giving the whole intranet language context. Here is the language initialization sequence:

  • 1) Get the current page language during the initial page load (the main.ts) by reading the current item language field (notice the _spPageContextInfo.pageItemId use):
  • 2) Set it as the working language for resources and dates:
  • 3) Set it as the working language for taxonomy so all subsequent request will use this language to retrieve terms (see the taxonomy.ts file):

The i18next library


Because of the language context is given by the page itself and not by the current site, custom and SharePoint labels have to be translated manually (because we only use one site). With SharePoint Online, you can’t add your own resource files (*.resx) and then access them by JavaScript* so we used our own resources management solution. I used the i18next JavaScript library to manage the localization. Resources are just stored in .json files and loaded at application start-up according to the current page language. Because the i18n object reference is shared for in the whole application context, all subsequent resource requests will retrieve the correct translations.

 A resources file looks like this:

 Get a resource string like this in a .ts file:

I’ve implemented a dedicated method to get a resource string directly from the global page context (see the previous article to see why we do this):

* It is possible to get OOTB resources strings via the SP.Res object but not useful in this case

The translation control

The translation control is implemented directly within the page layout to avoid to add a custom action in the “Pages” library (custom actions wont’ be supported with the new SharePoint modern experience) and to reuse the component mechanism used for the global solution.

The goal of this control is simply to create a copy of the current page by setting the correct target language and link them with an unique key (i.e a guid) into the same library.

Translation control

All manipulations are done using the PnP JavaScript core library leveraging the underlying REST API.

The language switcher control

This logic of this control is pretty simple: check if there is any translation available for the current page and for intranet target languages. Once again, the PnP JS core library is used (check the getPeerUrls() method in the languageswitcher.viewmodel.ts file):

Language switcher

This is not a “MUI” switch. It would be technically possible by changing the SharePoint user profile property responsible of the MUI language but this update is not instant (few minutes are required before the change be applied).

Working with taxonomy fields

Working with taxonomy fields in a SharePoint multilingual context can be confusing. By default, taxonomy terms are not automatically translated according to the current site language (for example in the search refinement panel). The default term language matches the site working language at the time when the item was saved. It can be different from the default site language.

I retrieve taxonomy terms at several places in the intranet like the page property panel and the search refinement panel:

Getting taxonomy terms

Taxonomy refiner

To get a term label for a specific language, you can set the “workingLanguage” property of the term store object:

 Be careful, getting single or multi valued taxonomy fields is something different. The REST call responses are not the same (see the pageinfo.viewmodel.ts file)


Using this solution “as is” comes with some limitations you have to know:

  • If you use a unique site for the whole intranet, you will have to translate all your component labels manually, including the SharePoint default display templates if you want to use them. It can be done using the i18next library and the getResource () method available from the global context.


+ There are no comments

Add yours

This site uses Akismet to reduce spam. Learn how your comment data is processed.