Localization in SPFx solutions when a user can speak several languages
For the past year or so, I’ve been doing a project for a company that has three corporate languages: Finnish, Swedish, and English. Even though Swedish is the second official language of Finland, it doesn’t mean that all Finns speak Swedish (eller “muminsvenska” — a term used by the Swedes for Finland’s Swedish). And the Swedes — our dear sibling-like rivals — definitely don’t speak Finnish! Hence, the common language between the employees is English, which the majority speak quite fluently.
Still, some employees only speak Finnish or Swedish, and because of that, relevant content needs to be offered in those languages as well. Let’s just say that content management can be a bit challenging sometimes.
In this blog post, I’ll tell you a story about one unusual situation in which we had to get texts for a single user from different localization files depending on something else than the user’s chosen language.
Background
It was a dark, wet and exceptionally warm day in January…
The task
I received a task to create a new “stock exchange news feed web part” for the SharePoint Online intranet front page of my long-term customer. The web part had to display news from a publishing service that had a unique feed format. It offered two feeds, one in English and one in Finnish.
If you start feeling bad for the Swedes at this point and think “why is there no news feed in Swedish?”, don’t. The Swedes already had their own news feed web part in place for Sweden-only news from a separate service. The appearance of their web part paled in comparison to what I was about to create, though. If Sweden was ever to beat us in ice hockey world championships again, at least I could comfort myself by thinking that they had an uglier RSS feed web part than the Finns.
Both of the language-specific feeds (Finnish and English) mostly had the same news. At this point, one might have thought, “let’s just use the feed that matches the user’s localization settings.” However, sometimes a news article was only published in one of the languages. And this created a dilemma.
Combining news feeds of different languages
If a Finnish user was to set English as their UI language in Office 365 (which is very common), and a news article was then published only in Finnish, the user would never get the chance to read the news article even though they’d be able to. And vice versa: If the UI language was Finnish and some article was published in English only, the Finn who was fluent also in English would miss the piece entirely. The Swedes couldn’t care less, of course — they would only read the articles available in English.
To solve the dilemma, I put the following logic in place:
- Get the feeds in both languages.
- Primarily use the feed that matches the user’s localization setting.
- Include the news articles from the other feed which don’t exist in the primary language feed. We were able to do this because each news article had a unique news article ID, which was shared by both translations.
Getting the correct category label based on feed language
Combining the news feeds was a simple enough task, but then I ran into another problem. All the news articles had a category label that needed to get displayed on the web part. However, only the category ID was returned in the feed, not the name. I had to get the category name separately based on the ID.
If I were a slacker, I would have just got the text from the localization files based on the user’s language. Instead, I thought that it would look quite unprofessional if the category name was in a different language than the rest of the news article. I needed to show the category text so that it matched the language of the news article, not the language of the logged-in user.
I was able to deduce the language of the news article by checking which feed it originated from. After that, it was just a matter of selecting the correct translation based on the language-specific news feed ID.
I could have done that by simply creating a switch with all the different strings that I wanted to get returned in different situations, but I figured there must be a better way…
Getting the string from a custom localization file
All UI texts should always be located in localization (a.k.a. resource) files. That way, it is a simple task to add support for more languages later. In SPFx solutions, we typically add UI texts to the files in the loc folder. The texts then get fetched automatically from the file that matches the user’s localization setting (the LCID string, e.g., en-US). However, now I needed to get the category name from the correct resource file based on the language of the news article — namely the ID of the language-specific news feed.
First, I created a new assets folder inside the web part folder. In there, I added two JSON files which names contained the IDs of the language-specific feeds, and inserted the category label translations into those files. Here is a simple text-based illustration of the directory structure.
/ webPart
-- / assets
-- / -- / categories-TQIXQKT0OO.json
-- / -- / categories-F6P4DNAMCF.json
Finally, I created a method that allowed me to get the category label translation from the resource file that matched the language of the news article (in other words, the ID of the language-specific feed).
private getCategoryName(feedId: string, categoryId: string): string {
var categories = require(`../assets/categories-${feedId}.json`);
return categories[categoryId];
}
The result
Here is a small sample of what that web part looks like in action. As you can see, the category label (bold text at the top of the card) matches the language of the news article. The book icon gets filled when the user reads the news article (the status gets saved to a cookie).
In case you are wondering, I built the UI using Office UI Fabric React controls. If you’d like to use the same controls for building your SPFx web parts but haven’t learned how to use React yet, read my blog post about How to get started with React for building advanced SPFx solutions.
Afterword
I hope you enjoyed reading this article! It is a bit different from what I usually write. Less code, more background, and storytelling. If you’d like to read more content from me — like this or otherwise — be sure to follow me on Twitter and other social media platforms (links to profiles can be found in the sidebar or at the bottom for mobile).
I also want to thank Julie Turner for giving me the idea for solving this problem based on a blog post written by Waldek Mastykarz. Whenever I have an SPFx related question, Julie more often than not promptly answers. She’s just awesome!
That’s it for now, folks! Thanks again for reading, and until next time.
Laura