Globalizing JavaScript in SharePoint 2013

When writing code it’s a common good practice to store strings separately in resource files. But how to deal with it when writing JavaScript?

Client or server choose your side

Writing server-side code was the way to go in the past for building SharePoint solutions. The server API was the only way to really benefit of the extensibility capabilities that the platform offered.

One of the investments in SharePoint 2013 was the improvement of the client API. Many of the things that in the past could be achieved only using the server-side API, can now be done by interacting with the client-side object model or REST services.

Separating code and UI

Often solutions consist not only of the logic but also of some user interface that allows users to interact with the system. When building solutions it’s a common good practice to separate the code from the UI. Not only it allows for changing the UI and reusing the code but it also simplifies maintaining the code.

One of the things done during the separation of the UI and code is extracting all strings and storing them in resource files (resx). Storing text labels in resource files helps you build a more consistent UI but also makes it easier for you to localize your solution if necessary.

Working with resource files from server-side code isn’t that difficult and is something that most web developers have experience with. This situation changes however with the advent of JavaScript-based development. After all: globalizing JavaScript files is not something many SharePoint developers have done in the past. So how to deal with globalization of JavaScript files when building SharePoint 2013 solutions?

Globalizing JavaScript in SharePoint 2013

SharePoint 2013 is a rich platform and it proves it once again by anticipating the challenge of localizing JavaScript files. Although it might not be obvious at the first glance, SharePoint 2013 provides us with an easy-to-use mechanism for globalizing JavaScript files.

Globalizing JavaScript files in SharePoint 2013 can be done by using resx files: just as you were globalizing server-side code. Once your resx file is in-place, all you have to do to refer to it, is to call the ScriptResx HTTP Handler passing the name of the resource file and the culture you want to refer to, for example:

/_layouts/15/ScriptResx.ashx?name=sp.publishing.resources&culture=en-us

The name query string parameter contains the name of the resource and the culture parameter contains the name of the culture for which the resources should be loaded.

Calling the ScriptResx HTTP Handler will return the contents of the particular resource file formatted as a JavaScript object, ready to be included in your script and referenced from within your JavaScript code.

The resource strings defined in the file are defined as properties and wrapped in the namespace defined in that particular resource file. In the case of the SP.Publishing.Resources.en-US.resx file all resource strings are defined as properties within the SP.Publishing.Resources namespace, eg.:

SP.Publishing.Resources.spellcheckerCheckSpelling = "Check Spelling";

Important: Note how the first letter of the key of the resource string (spellcheckerCheckSpelling) is converted to lowercase to match the JavaScript naming conventions.

The ScriptResx HTTP Handler can be perfectly combined with the Script On Demand (SOD) script loading approach offered by SharePoint. In your code you would then use the following snippet to refer to your resource file:

SP.SOD.registerSod("sp.publishing.resources.resx", "/_layouts/15/ScriptResx.ashx?name=sp.publishing.resources&culture=" + STSHtmlEncode(Strings.STS.L_CurrentUICulture_Name));

With this you can have your resource file loaded on demand when necessary and refer to resource strings from within your JavaScript code.

Summary

Globalizing code files allows for improving code readability and simplifying maintenance. While many SharePoint developers have experience with globalizing server-side code, globalizing JavaScript files is a relatively new concept. SharePoint 2013 simplifies globalizing JavaScript files by providing the ScriptResx HTTP Handler that can be used to reference standard resource files from JavaScript.