Custom localization using Microsoft Graph Toolkit’s components in SPFx

Introduction

Ahoy, matey! So ye be wantin’ to learn more ’bout localization, uh? Let’s hoist the anchor and set sail!

I’m not writing as if I’m a pirate without no reason, with this blog post I want to demonstrate how to localize the Microsoft Graph Toolkit (MGT) components strings.

Let’s start with the theory first!

MGT offers the ability to localize some of the components strings. To demonstrate how the localization works I’ve created a sample solution that you can find here.

Visual appearance

Starting with the visual result I want to cover the before and after setting the customized localization strings. Before setting the customization my sample web part looks like the following:

And now the result, and if you’re still wondering why I began with a piratish sentence you’ll get to know why:

You’re right! I changed some of the strings with some pirate wording! That’s just because I like it and of course to show you the result.

The strings I’ve changed are the placeholders of the people picker and search box controls, the button to create a new task and, the due date label of the planner control.

Another example is that I’ve changed the global label for when data is loading or when there’s no result found in the MGT controls, for example in the people picker:

Another useful thing to know is that since the MGT components often contains other MGT components, the custom localizations will be inherited also for those components. In this sample I’ve changed the placeholder for the people picker control, however also the people picker control inside the planner control will reflect those changes. If I click the Assign button of a task an instance of the people picker control will be shown and the placeholder will be the same of the first people picker instantiated:

How to localize the components

As said before, to demonstrate how to localize the MGT components strings, I’ve created a sample solution. What I didn’t mentioned before is that this solution uses MGT v.4 with the support for disambiguation.

I will not cover MGT v.4 and how to set up the disambiguation, for that you can have a look at my other post.

To customize localization you will need to use the LocalizationHelper from the mgt-element package which you can import as following:

import { LocalizationHelper } from "@microsoft/mgt-element";

The LocalizationHelper exposes a strings property that accept an object where you can specify the strings that you want to override.

In the object used to set the strings property of the LocalizationHelper there are two different main things to remember:

• you can set global strings by specifying the string that you want to override.
• you can set strings override for specific components. This can be achieved by specifying, inside the _components property, the name of the component and the string that you want to override.

Let’s have a look at the code and then I will (hopefully) answer your questions.

Before the code a little specification: the solution uses disambiguation. As such, the string I used for disambiguate the controls is mgt-localization, this string must be added before the control name. For example, if you want to override the strings for the people-picker control you will need to specify {your-disamiguation-string}-people-picker.

In short, if I want to localize the people-picker control I will be using mgt-localization-people-picker as the control identifier.

In the sample, the code to override the strings is the following:

LocalizationHelper.strings = {
  loadingMessage: "Arr! Ye data be loading...",
  noResultsFound: "Arr! No results found matey!",
  _components: {
    "mgt-localization-people-picker": {
      inputPlaceholderText: "Ahoy! Do the search to find yer mateys",
    },
    "mgt-localization-search-box": {
      placeholder: "Search for yer treasure"
    },
    "mgt-localization-planner": {
      addTaskButtonSubtitle: "Arr! Add a new task matey",
          due: "Settin’ sail "
    }
  },
};

In the above code I set the global strings for the following values:

• loadingMessage
• noResultsFound

In the _components property on the other hand, I instantiated custom strings for different controls. For example the mgt-localization-search-box specify that, for the SearchBox control, an object is set which overrides the placeholder string.

Conclusions

Localizing the MGT components strings is a nice user experience addition to your solution. It allows you to create more in depth localization and personalization to the already existing controls.

If you want to discover more or deepen your knowledge about localization in MGT you can have a look at the official documentation here.

If you’re wondering what are the localizable strings you can see, for each MGT component, at the bottom of the documentation page, a specific section for localization. For example, for the people picker control, you can see the localization section here.

Hope this helps!