Globalizing JavaScript in SharePoint 2013
Best Practices, Development, JavaScript, SharePoint 2013, Tips & Tricks
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.
January 31st, 2013 at 10:35 pm
This is really a good technique to localize the interface in JavaScript. But this absolutely not new for SharePoint 2013. I have used this in many SharePoint 2010 projects. http://sharepointkunskap.wordpress.com/2012/02/13/scriptresx-ashx-in-sharepoint/
The challenge is to use multiple resources. Every resource file you load gets called Res. We have to append this Res object to our custom namespace. Thanks for your article, Waldek.
January 31st, 2013 at 10:45 pm
From what I've seen the namespace in which the resources are loaded in JavaScript is defined in the resx file itself. The one I took as an example (SP.Publishing.Resources.en-US.resx) has its namespace set to 'SP.Publishing.Resources' so all the resource strings are loaded within that namespace.
February 1st, 2013 at 11:28 am
Yes, Waldek! You are right. So is the case for the built-in resx-files. I compared the built-in files with my own resx-files and found a resheader which defines the namespace of your localization:
<resheader name="classFullName">
<value>SP.Publishing.Resources</value>
</resheader>
Thanks to your post and reply I found this.
February 6th, 2013 at 7:01 am
I published a post explaining how add a javascript namespace to own resx files: http://sharepointkunskap.wordpress.com/2013/02/01/javascript-localization-in-sharepoint/
March 6th, 2013 at 9:43 am
Hi,
Thank you for your article! Small question, why you are using ScriptResx.ashx directly, not via ScriptLink? Are there any bugs that I should be aware of?
Cheers!
March 6th, 2013 at 4:47 pm
Not that I know of. When building public-facing websites I often choose for the light-weight approach where I ommit a lot of the out of the box scripts that I don't need. You could as well use the approach that you mentioned if it suits your scenario better.
March 12th, 2013 at 9:18 pm
Could you provide a more complete example? I have a custom RESX file and I can't find the namespace for it.
The name of the file is: publishingstrings.en-US.resx and my JS is as follows:
function pageLoad() {
SP.SOD.registerSOD("publishingStrings.resx", "/_layouts/15/ScriptResx.ashx?name=publishingStrings&cultre=en-US");
$('#testDiv').text(publishingStrings.testString);
}
What am I doing wrong?
March 14th, 2013 at 8:30 am
First of all there is a typo in the 'culture' query string parameter. Secondly, there is no resx file called publishingStrings: at least not out of the box. Did you mean to use the sp.publishing.resources file instead? Finally, in the sample above you only register the script as a SOD script. In order to be able to use it you have to load it first. See http://blogs.msdn.com/b/sharepointdev/archive/2011/01/27/loading-script-in-sharepoint-2010.aspx for more information about working with SOD in SharePoint.