SharePoint App Localization and REST calls on existing lists

SharePoint App Localization and REST calls on existing lists header image

As the Office store now supports a Dutch version that allows for Dutch apps. App localization just got a little more interesting.It might be a good idea to localize your apps when you are creating Apps for SharePoint. As without localizing your apps there will be a risk when deploying them on other tenants or site configurations. While the title and description might be readable for your users as they will be English, retrieving or storing information on the host web might could potentially be in another language.

You can find a great example on how you need to do localization in your apps on the MSDN Article How to: Localize apps for SharePoint. In this article a few different techniques of localization are mentioned, as well as a nice description on how to achieve this. However there is one part that is missing some information: localization in your JavaScript.

SharePoint elements & Localization

When you are localizing host web components you can easily resort to resource files and call them using replacement parameters in your elements, like the following example: 

<ListInstance
    Title="$Resources:OrdersListInstance_Title"
    OnQuickLaunch="TRUE"
    TemplateType="10000"
    Url="Lists/Orders"
    Description="$Resources:OrdersListInstance_Description">
</ListInstance>

JavaScript localization

If you are thinking of deploying localized JavaScript as well, the MSDN Article How to: Localize apps for SharePoint suggest that you create a with the Culture in the naming convention, like: Resources.Culture.js, this will result in Resources.EN-US.js.

<script type="text/javascript" src="../scripts/Resources.<SharePoint:EncodedLiteral runat='server' text='<%$Resources:wss,language_value%>' EncodeMethod='HtmlEncode' />.js"></script>

This allows for the use of a localized script that contains the strings you would like to display. Yet there is a small downside on this approach, it still requires you to define all the strings you require yourself. Now imagine that you would like to retrieve the default blog library on your site, this information is not available through the web properties. So you have to retrieve that information from somewhere else. Or imagine you need to create a new document library based on the default document library name prefixed with a client name. While this information is available through the use of resources files retrieving it through JavaScript is a bit harder.

Luckily there is a set of JavaScript files provided out of the box, called initstrings and strings. These files live in the /_layouts/LCID folder and contain the localized values. There are also debug versions of those script that can be viewed in your favorite text viewer so you can quickly identify the strings you need.

Unfortunately the default Language parameter that can be passed as query string by your app is the culture info, and not the LCID. So if you want to use your LCID and load the correct script you will need to get the Language from the core resource with the following snippet:

<script type="text/javascript"
    src="/_layouts/15/<SharePoint:EncodedLiteral runat='server'
        text='<%$Resources:core,Language%>'
        EncodeMethod='HtmlEncode' />/sts_initstrings.js"></script>

Once that script is loaded you can call the strings you need, as it creates a new object called Strings that contains an object STS, and that will provide the strings you need.

In our case we used Strings.STS.L_BlogPostFolder, so we can easily do a REST call to retrieve the blog list based on the localized title, as that differs between different languages. That way whether you install your app in a Dutch or an English environment and still execute the following REST query

url: "https://maventionurl/_api/SP.AppContextSite(@target)/web/lists/GetByTitle('" + Strings.STS.L_BlogPostFolder + "')

Without applying localization in your scripts calling out of the box lists through REST will be painfully as you will have to do the localization yourself.

Loading comments…