Localizing in SharePoint Add-in with JavaScript


Let's consider a scenario of an Add-in development, it can be either SharePoint hosted or provider hosted. If we are looking for a localization, there are couple of approaches. If you are writing more ASP.net based add-in driven by code behind then resource files comes handy. This is more an old-school type, we have been doing this over decades and I not going to detail anything on this. More details can be found here - https://msdn.microsoft.com/en-us/library/office/fp179919.aspx. Approaches detailed on this article also includes JavaScript based one, I have tweaked this approach in a more reusable format. OK let's get into the action.

How to use it?

  • Add localizer JS to your web page
  • Create JS resource files in the file name format resource.<<ll-CC>>.js, sample resource file has been shared below
  • Add the attribute localeval="<<ResourceString>>" to the DOM elements, like <h1 localeval="HeaderText"></h1>
  • Use localizer.Init() method

How it works?

User identifies the string literals which are to be MUI and adds localeval attribute to the element with string identifier as the value. Individual resource files are created for all supported languages, and contains actual content in that language against the identifier as a set of array items. Sample resource file is given below. Localizer JS queries through the elements with the localeval element and matches the content based on the string identifier and appends the content to that element. Localizer JS selects the resource file based on the SPLanguage query string passed by the add-in as part of the standard tokens. Make sure that {StandardTokens} parameter added in the add-in app-manifest. By default "en-US" is will be set as language if the resource file is missing. The default language can be overwritten by passing the defaulLang parameter in the <<ll-CC>> format. Resource JS file is getting loaded dynamically and also getting cached for by default, set cache: false to override caching.

Sample resource file

Code Repo

It's a open source project available in GitHub, feel free to fork, star it, raise pull/merge requests and add issues. I'm happy to collaborate, Together we can make it better. https://github.com/rjesh-git/Localization

App for Testing

Also shared the sample SharePoint hosted app directly from the NAPA cloud tools, which will help to compile and deploy site if you already have an subscription. Pre-compile app can be downloaded from here for your on-premises server.

Thoughts

I have been using this approach, since the other documented approaches are quite messy around setting values for the elements from the resource file. Not a huge fan of having script tag embed between each DOM elements. Also needed a more clean pattern which can be easily reused in multiple projects. This method offers more flexibility when used along with libraries like Angular, KnockoutJS and others. There might be better option, but its a worth a choice.

Happy Coding! Peace.

Comments