SPFx & react-localization, an easy alternative?
Have you ever ran into a situation where the out of the box SPFx localization mechanism cannot do the trick, then this article is for you. I will quickly look at some examples why it might be worth to swap out the out of the box SPFx localization with something custom. Are you already convinced about the why, then you can directly skip to the how section. In the how section I will explore how to set-up react-localization and including a practical examples.
Why?
When using the out of the box SPFx localization, the selected language is determined by SharePoint. This is very handy in a lot of situations because you do not need to worry about language selecting. According to the documentation, the spPageContextInfo.currentUICultureName object is used to select the correct language. This object in its turn can be determined based on multiple variables:
- Browser language
- SharePoint site language
- User profile language
Elio Struyf has written a great article on Demystifying the mystery behind the UI language in SharePoint
After gathering this information it became clear to me that you don’t have much control over how the language is being set in the web part, which was an issue for the specific scenario I was working on. I wanted to localize the web part based on a custom user profile property instead of the current UI language of the site. As I already used the react-localization npm package before in custom web applications, it thought I would do some investigations into setting this up in a SPFx web part (turns out this was pretty straight forward — see next section).
Next to this scenario I also could think of some other use cases for swapping out the default localization with react-localization:
- Maybe you want the language to be set in the property pane of the web part
- If your web part is exposed as a teams tab, you might want to act on the UI language of Teams
- Another option could be to expose a language switch in the UI of the component
- …
Whatever the scenario might be, using the react-localization option gives you full control over which language is being selected. Now lets look at some code and examples.
How?
Now that we covered the why, lets look into the how. I am not going over the part on how to create a new web part. If you want more information on that I suggest you check out the Build your first SharePoint client-side web part (Hello World part 1) documentation page.
The first step is setting up the react-localization is of course installing the react-localization package:
npm install react-localizationNext-up, remove the references to the default localization of the web part. The ‘loc’ folder that can be found in each web part folder can be removed as we won’t be using these files anymore. Also, for each web part, an entry in the “localizedResources” of the config.json is created. They can be removed as well.
The last step is to remove the references to the WebPartStrings in code. When scaffolding a new web part, it will be referenced in the top level file of that web part.
Once the old artefacts are removed, it is time to create a new localization structure for react-localization. We start by creating a new ‘loc’ folder de ‘src’ folder of the project. In this case I won’t define it in each web part so we can reuse the strings in all the web parts (but if you want you can still create them per web part). the ‘loc’ folder needs at least 2 files
- strings.ts: which defines the keys of the labels
- en-us.ts (or another locale key): which defines the actual labels
In the example here, I added a localization file for English and for Dutch.
First lets look at the strings.ts file:
import LocalizedStrings, { LocalizedStringsMethods } from "react-localization";
import { enStrings } from "./en-us";
import { nlStrings } from "./nl-be"; export interface IStrings extends LocalizedStringsMethods {
MY_GREETING: string;
} export const strings: IStrings = new LocalizedStrings({ en: enStrings, nl: nlStrings });
Let’s explain this:
- Import the methods and objects from react-localization.
- Import the localization files (in my case the English and Dutch one)
- Define the strings interface. Here you expose all the label keys.
- Create the strings object using the LocalizedStrings method. This tells react which string file to use for which locale key.
TIP: The first localization file that is defined in the IStrings interface will be the default one.
Pretty straight forward right? Now lets move on to the localization files itself. They are even more straight forward. It is basically just an object with the key and value of each label as shown below:
Another nice thing about this approach is that visual studio will complain if not all labels are provided so you will never miss one ;).
Almost there. How can we now access these strings? Again, pretty straight forward. From anywhere in your code import the strings.ts file and use strings.MY_LABEL_KEY.
And then of course the last step is to tell react-localization which language to use. And again, at he risk of repeating myself, this is pretty straight forward. Just use the strings.setLanguage() method to pass in the locale key. In the example below you can see I use in the locale that is provided in the property pane.
And were done. Depending on your use case, you can determine the language locale key in your own way and provide it to the react-localization mechanism. At the end of this article there is a link to a github where I provided 2 examples:
- Setting the language in the property pane (as shown in this article)
- Setting the language based on a user profile property (uses PnPjs to fetch the user profile properties)
Conclusion
When the out of the box localization mechanism is not flexible enough for you scenario, the react-localization offers an easy alternative. It is light-weight and easy to set up. Using this method you have full control over the language setting and therefor the labels that are being show.
Resources
Github
Other
Originally published at http://digitalworkplace365.wordpress.com on April 13, 2021.
