How to: Localize apps for SharePoint

apps for SharePoint

Localize an app for SharePoint by using resource files, JavaScript resource files, and other techniques.

The following will help you prepare for the procedures in this article:

  • Set up a SharePoint development environment for apps. For more information, see Start building apps for Office and SharePoint. Your Microsoft Visual Studio version should be at least 2012 with the most recent version of Microsoft Office Developer Tools for Visual Studio for that version of Visual Studio. Localization of apps for SharePoint is much easier with Visual Studio 2013 with the most recent version of Office Developer Tools for Visual Studio. The procedures in this article assume that you are using the most recent version.

    Note Note

    If your test SharePoint website is an on premise SharePoint farm instead of a Microsoft SharePoint Online Developer Site, you may need to install the language packs for the languages in which you are translating your app for SharePoint. For more information, see Install or uninstall language packs for SharePoint 2013 and Language packs in SharePoint Server 2013, and the download links in the latter.

  • The screen shots in this article are taken from the sample Localize the app web, host web, and remote components of an app on Code Gallery and the code examples are a close match for that same sample. You can download the sample to see the results of the procedures described in this article.

  • Decide which locales your app needs to support. SharePoint Online, and SharePoint on premises with Language Packs installed, enable users to create websites in a specific language and culture, and not just in a generic language. For example, a website created in English matches the en-US language and culture, but not en-GB. In the same way, a website created in Spanish matches the es-ES language and culture, but not es-MX.

  • Identify the components that you need to localize in your app.

Core concepts to know for localizing apps for SharePoint

Before you localize an app for SharePoint, you should know about the distinction between app webs and host webs, the basics of localization with .resx files, and of course, how to build apps for SharePoint.

Table 1. Core concepts for localizing apps for SharePoint

Article title

Description

Host webs, app webs, and SharePoint components in SharePoint 2013

Learn about the distinction between host webs and app webs. Learn also about which SharePoint 2013 components can be included in an app for SharePoint, which are deployed to the host web, which are deployed to the app web, and how the app web is deployed in an isolated domain.

Explore the app manifest and the package of an app for SharePoint

Learn about the manifest file in the app package of an app for SharePoint.

How to: Create a basic provider-hosted app for SharePoint

Learn how to create a basic provider-hosted app, how to interact with SharePoint 2013 sites by using the SharePoint client object model, and how to implement OAuth in an app for SharePoint.

How to: Create a basic SharePoint-hosted app

Learn how to create a basic SharePoint-hosted app.

To localize components that are deployed to an app web, you add .resx files as local resources in the Feature that contains the components, and then reference the resources in the markup of the component. (For more information about the kinds of SharePoint components that can be in an app for SharePoint, see Types of SharePoint components that can be in an app for SharePoint.) However, custom site pages in an app for SharePoint use JavaScript string variable files instead of .resx files, as described later in this section.

Note Note

Resource files cannot be shared by multiple app web Features. For each Feature in the .wsp file, you have to create separate sets of resource files.

To create the app web resource files

  1. Open the app for SharePoint project in Visual Studio. (The sample from which the screenshots in this topic were taken is a provider-hosted app with ASP.NET Web Forms as the remote web application part of the project.)

  2. In Solution Explorer, open the shortcut menu for the Feature name, and choose Add Feature Resource.

  3. In the Add Resource dialog box, choose Invariant Language (Invariant Country), and then choose the OK button. A Resources.resx file is added to the Feature's folder in Solution Explorer, and the file is opened in the Visual Studio Resource Editor.

    When edited, this "invariant language" file contains the strings that are used in the Feature gallery on all sites in languages for which you are not going to be providing a localized version of strings. So the language used for the strings in this file should be the language that is most likely to be a second language of people using SharePoint. Traditionally, English is used for this purpose, but in some scenarios another language might be a better choice. For example, in some regions, French may be a more common second language of the users than English. The continuing example in this topic uses English as the invariant language.

    Note Note

    An app for SharePoint cannot be installed on a website whose language is not listed in the Supported Locales section of the app manifest. Keep in mind that when this article discusses languages for which you are not going to be providing a localized app, you do still have to add such languages to the app manifest. See the procedure To create resource files for the host web in this article for more details about supported locales in the app manifest.

  4. In the Name column of the top row in the Resource Editor, enter a descriptive name for the string (or other resource)—for example, OrdersListInstance_Title and OrdersListInstance_Description. These names of localizable resources are not themselves localized. Each resource must have its own name.

  5. In the Value column, enter an appropriate string (or URL or other resource) in the invariant language—for example, Orders, and A list to store the orders.

  6. Repeat this process until you have rows for every localizable string and resource in any of the components in the Feature.

  7. Save the file. The following image shows the localized strings in the resource file for the invariant language.

    Figure 1. Resources.resx file for an app web Feature

    A resource file for an app web feature

  8. Add another resource file to the Feature as you did before, but select a particular language instead of Invariant Language (Invariant Country). For example, you can choose Spanish (Spain). A Resources.LL-CC.resx file (where LL and CC are Internet Engineering Task Force (IETF)-compliant language and culture codes) is added to the Feature's folder in Solution Explorer, and the file is opened in the Visual Studio Resource Editor.

  9. Using the Resource Editor, copy all the rows from Resources.resx, and paste them into the new Resources.LL-CC.resx file. (If Copy is not enabled on the context menu of the resource editor, use Ctrl-C to copy the rows into the clipboard.)

  10. In the Resources.LL-CC.resx file, replace the Value cells with translated versions of the string values. For URLs and other non-string resources, replace the value with a new value that is appropriate for the language and culture.

  11. Save the new file.

  12. Repeat the last four steps for each foreign language.

    Note Note

    You should consider adding a language-specific file for the same language as your invariant language. If you do, you can copy the rows without changing the values of the strings. In many situations, it is not necessary to have a language-specific file for the same language that is used in the resource file for the invariant language, especially when the only resources in the files are strings. But resource files can contain images, icons, files, and other kinds of resources too. Sometimes, you need the invariant language resource file to use an image or other resource that is different from the corresponding resource in any of the language-specific files.

  13. For each file, verify that the Build Action property is set to Content.

To call the localized resources in custom lists

  1. To localize the title and description properties of a custom list, open the Elements.xml file of the instance of the list.

  2. In the Title box, enter $Resources:StringName, where StringName is the name, not the value, you gave in the previous procedure to the string that names the custom list—for example, $Resources: OrdersListInstance_Title. Note that, unlike in some contexts where .resx files are used, the resource file name is not part of what you enter.

  3. Use the Description box to call the string resource of the list description in the same way—for example, $Resources:OrdersListInstance_Description. The following is the markup that uses the localized strings in the Elements.xml file of the instance of a list.

    <?xml version="1.0" encoding="utf-8"?>
    <Elements xmlns="http://schemas.microsoft.com/sharepoint/">
      <ListInstance 
          Title="$Resources:OrdersListInstance_Title" 
          OnQuickLaunch="TRUE" 
          TemplateType="10000" 
          Url="Lists/Orders" 
          Description="$Resources:OrdersListInstance_Description">
      </ListInstance>
    </Elements>
    

    The following image shows the localized custom list in English.

    Figure 2. A localized custom list

    A localized custom list

You can’t localize the column names of the custom list in the same way as you localize the title and description. To localize the column names, you have to declare the list fields in an Elements.xml file and then set the DisplayName attribute value with references in the app web resource files. You can use the Elements.xml file that Visual Studio provisions for you when you add a custom list.

To localize the column names of a custom list

  1. Open the Schema.xml file of your custom list. Locate the Fields node and copy all its Field nodes.

  2. Open the Elements.xml file of your custom list. Make sure you open the Elements.xml file of the list definition, and not of the instance of the list. Paste the nodes from the previous step as children of the Elements node.

  3. For every Field node, enter a value of $Resources:StringName in the DisplayName attribute where StringName is the name of an entry in the app web resource file.

  4. In the Schema.xml file of your custom list, remove the DisplayName attribute of every Field node that you previously copied. The following is an example markup that uses the localized strings in the Elements.xml file of the list definition.

    <?xml version="1.0" encoding="utf-8"?>
    <Elements xmlns="http://schemas.microsoft.com/sharepoint/">
        <ListTemplate
            Name="Orders"
            Type="10000"
            BaseType="0"
            OnQuickLaunch="TRUE"
            SecurityBits="11"
            Sequence="410"
            DisplayName="Orders"
            Description="My List Definition"
            Image="/_layouts/15/images/itgen.png"/>
        <Field
            Name="Bookname"
            ID="{2ef60a05-29b6-41db-9611-c0cf7d8e73c5}"
            DisplayName="$Resources:OrdersListColumn_Bookname"
            Type="Text"
            Required="TRUE" />
        <Field
            Name="Price"
            ID="{7af42815-d69e-426a-a1c8-9da5610e362c}"
            DisplayName="$Resources:OrdersListColumn_Price"
            Type="Currency"
            Required="FALSE" />
        <Field
            Name="Orderstatus"
            ID="{687ee751-2e0a-4099-966e-d2c225d48234}"
            DisplayName="$Resources:OrdersListColumn_Orderstatus"
            Type="Lookup"
            Required="FALSE"
            List="Lists/Order status"
            ShowField="Title" />
    </Elements>
    

To create JavaScript resource files for custom pages

  1. In Solution Explorer, open the shortcut menu for the Scripts node in the SharePoint app project, not the one in the web application project, if any, and add a new JavaScript file using the JavaScript file template in Visual Studio. Name the file Resources.LL-CC.js (where LL is a language code and CC is a country/region or culture code); for example, Resources.en-US.js.

  2. Repeat the preceding step for each foreign language. You should now have blank JavaScript files for every language. Do not create an invariant language file named "Resources.js". The reason is explained in a later procedure.

  3. Open the first of the new JavaScript files.

  4. For each localizable string in each of your custom pages, declare a variable in the file with a name that identifies the purpose of the string and assign it a value that is appropriate for the language. The following is the contents of the Resources.en-US.js file.

    var instructionstitle = "Instructions:";
    var step01 = "Go to any document library in the host web.";
    var step02 = "Go to the Library tab.";
    var step03 = "Click \"Request a book\" in the Settings group.";
    var step04 = "Click the contextual menu in any document.";
    var step05 = "Click \"Buy this book\" in the contextual menu.";
    var step06 = "Go to any SharePoint page in the host web and add the" +
        " Bookstore orders app part.";
    var step07 = "Review the localized <a href=\"../Lists/Orders\">Orders</a>" +
        " and <a href=\"../Lists/Order status\">Order status</a> custom lists.";
    
    
  5. Copy the contents of the file into each of the remaining JavaScript files, and then save all files.

  6. In each file, replace the value of each variable with a new value that is appropriate to the language of the file. Do not change the variable names.

To call the localized variables in custom ASPX pages

  1. In Solution Explorer, open a custom ASPX page file.

  2. You need to make sure that only one of the localized JavaScript files is loaded when your page loads, and it should be the one that is appropriate for the language of the SharePoint app web. To do this, add the following markup to the asp:content element of the page that has a ContentPlaceholderId with the value PlaceholderAdditionalPageHead. There are no placeholders in the following markup. Enter the markup exactly as it appears here.

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

    This markup loads one of your JavaScript files. It determines which language file to load by reading the SharePoint resource named "language_value." This resource resolves to a language-culture name in the pattern LL-CC that was described in an earlier procedure. Specifically, it resolves to the language of the app web.

    NoteNote

    The SharePoint resource "language_value" is never null, so a file named "Resources.js" would never be called by this script. That is why you did not make one in the preceding procedure. When the value of "language_value" is a language for which there is no .js file, this script loads nothing. The next step explains how strings get an invariant language value in that situation.

  3. For each localizable element and attribute value on the page, give it a default value in the invariant language, but then use JavaScript to assign it the appropriate variable from the Resources.LL-CC.js file. For example, if the page has a title in an h2 element, give the element an id attribute and then insert a script element below the localized elements to assign localized strings to the innerText property of the localized elements. This localization code should only run if a Resources.LL-CC.js file loaded and declared the variables. So put it in a conditional block that first tests whether one of the variables is defined. If it is not, then no resource script loaded and the default (invariant) values should remain unchanged. The following is an example.

    Tip Tip

    Note that the word "INVARIANT" has been added to the first of the invariant strings. You would not do this in a production app, but while you are testing, it is a useful way of seeing at a glance whether invariant language strings are being used or whether the Resources.LL-CC.js file for the language that happens to be your invariant language was loaded.

    <h2 id="instructionsheading">INVARIANT Instructions</h2>
    <ol>
        <li id="step01">Go to any document library in the host web.</li>
        <li id="step02">Go to the Library tab.</li>
        <li id="step03">Click "Request a book" in the Settings group.</li>
        <li id="step04">Click the contextual menu in any document.</li>
        <li id="step05">Click "Buy this book" in the contextual menu.</li>
        <li id="step06">Go to any SharePoint page in the host web and add the Bookstore orders app part.</li>
        <li id="step07">Review the localized <a href="../Lists/Orders">Orders</a> and <a href="../Lists/Order status">Order status</a> custom lists.</li>
    </ol>
    
    <!-- Use the localized strings in the resource JavaScript file -->
    <script type="text/javascript">
        window.onload = function () {
            <!-- Test whether a Resources.LL-CC.js loaded.
                 If none was, the invariant values remain unchanged. -->
            if (typeof instructionstitle != 'undefined')  
            {
                document.getElementById("instructionsheading").innerText = instructionstitle;
                document.getElementById("step01").innerText = step01;
                document.getElementById("step02").innerText = step02;
                document.getElementById("step03").innerText = step03;
                document.getElementById("step04").innerText = step04;
                document.getElementById("step05").innerText = step05;
                document.getElementById("step06").innerText = step06;
                document.getElementById("step07").innerHTML = step07;
            }
        }
    </script>
    
    

    The following image shows the page using the localized strings in English:

    Figure 3. A webpage using localized strings from a JavaScript resource file

    A SharePoint page using localized strings

You can localize the app title, which is specified in the AppManifest.xml file. This is what users see on the Your Apps page. The host web for an app for SharePoint can also include a custom action, an app part, or both. These are deployed in a host web Feature. Both of these components can have localizable strings.

The essential method for localizing host web components is the same as for localizing app web components: localized resources are itemized in a .resx file and are called from the markup files. However, Visual Studio does not have as much tooling support for the process as it applies to host web features. There is a manual process involved that is explained later in this section.

To create resource files for the host web

  1. In Solution Explorer, choose the AppManifest.xml file to open the app manifest designer tool.

  2. Open the Supported Locales tab.

  3. In the top blank cell of the Locales column, open the drop-down list and choose the first locale that you want to support. Two files are created and added to the app for SharePoint project: Resources.resx, which is the invariant language resource file, and Resources.LL-CC.resx, which will contain the localized resources. Don’t change the names of these files.

  4. Repeat the previous step for each locale you want to support with a localized version of the app. An additional Resources.LL-CC.resx file is created for each locale.

    Note Note

    The Build Action property of each of these files is set to Content, not Resource. Don’t change this setting.

  5. Also add locale entries for every locale where you want your app to be installable, but where it should use the invariant language; that is, locales for which you will not be providing a localized version of the app. Delete the .resx files that are created for these locales.

  6. Open the Resources.resx file and add resource names and values to the file just as you did for the app web resource files. At a minimum, you should have a resource for the app title. The host web Feature does not appear in the SharePoint UI anywhere, so you do not need localized strings for the host web Feature title or description. If the Feature has a custom action, you need a resource for the Title attribute of the CustomAction element, and possibly other strings in the custom action markup. If there is an app part, you need resources for the Title and Description attributes of the ClientWebPart element. If the app part has custom properties, each Property has attributes that should be localized as well. For each of these, you need a row in the resources file.

  7. Copy the contents of the Resources.resx file into each of the Resources.LL-CC.resx files.

  8. Localize each resource in each Resources.LL-CC.resx file just as you did for the app web resource files. The following image shows an example Resources.resx file.

    Figure 4. A resource file for host web features

    A resource file for host web features

To call the localized resources in the app manifest, and other XML files

  1. Open the AppManifest.xml file and replace the Title element value with a call to the appropriate resource string. For example, if you named the string App_Title, the Title element should look like the following:

    <Title>$Resources:App_Title;</Title>
    
    Caution noteCaution

    The value of Title can contain only the call to the resource. There can be no other text, symbols, or white space.

  2. To call localized resources in other XML files, such as Elements.xml for app parts and custom actions, you use the same format that you used in the app manifest file.

If the remote components are PHP or other non-Microsoft formats, see the localization guidance for the appropriate platform. When the remote componets are ASP.NET, you localize them just as you would any other ASP.NET application. For more information, see ASP.NET Globalization and Localization.

You should override the page language and the thread language to match the language of the host web. You do this by overriding the inherited InitializeCulture method in the code-behind of your ASP.NET pages. To identify the host web's language, use the SPLanguage query parameter that SharePoint passes to the remote page. The following code shows how to do this in ASP.NET. You should do something parallel in a PHP web application or other platform.

protected override void InitializeCulture()
{
    if (Request.QueryString["SPLanguage"] != null)
    {
        string selectedLanguage = Request.QueryString["SPLanguage"];
        
        // Override the page language.
        UICulture = selectedLanguage;
        Culture = selectedLanguage;

        // Reset the thread language.
        Thread.CurrentThread.CurrentCulture =
            CultureInfo.CreateSpecificCulture(selectedLanguage);
        Thread.CurrentThread.CurrentUICulture = new
            CultureInfo(selectedLanguage);
    }
    base.InitializeCulture();
}

If there are localizable string values in your web application's JavaScript, you can localize them using JavaScript resource files. An especially important example of localizable JavaScript is the SharePoint chrome control, which can be used to give remote pages the appearance of SharePoint pages. We’ll use the localization of the chrome control as an example in this section.

Note Note

This section only discusses string localization. For more powerful localization needs, such as localization of date or currency formatting, consider using a localization or globalization library, such as the Globalize add-on for jQuery.

To localize the chrome control

  1. After you have the chrome control working, return to the renderChrome method where you set the chrome options. The following is an example.

    function renderChrome() {
        var options = {
            "appIconUrl": "siteicon.png",
            "appTitle": "My SharePoint app", // Localizable string
            "appHelpPageUrl": "Help.html?"
                + document.URL.split("?")[1],
            "onCssLoaded": "chromeLoaded()",
            "settingsLinks": [
                {
                    "linkUrl": "Account.html?"
                        + document.URL.split("?")[1],
                    "displayName": "Account settings" // Localizable string
                },
                {
                    "linkUrl": "Contact.html?"
                        + document.URL.split("?")[1],
                    "displayName": "Contact us" // Localizable string
                }
            ]
        };
    
    
  2. As noted in the comments, there are at least three localizable strings. Replace each of these with a variable name that you declare in a later step. The following is an example.

    function renderChrome() {
        var options = {
            "appIconUrl": "siteicon.png",
            "appTitle": chromeAppTitle, // Localized value
            "appHelpPageUrl": "Help.html?"
                + document.URL.split("?")[1],
            "onCssLoaded": "chromeLoaded()",
            "settingsLinks": [
                {
                    "linkUrl": "Account.html?"
                        + document.URL.split("?")[1],
                    "displayName": chromeAccountLinkName // Localized value
                },
                {
                    "linkUrl": "Contact.html?"
                        + document.URL.split("?")[1],
                    "displayName": chromeContactUsLinkName // Localized value
                }
            ]
        };
    
    
  3. Add a JavaScript file named ChromeStrings.js to the web application project. It should declare the variables you used in the preceding step and assign them each a value in the invariant language. The following is an example.

    var chromeAppTitle = "My SharePoint app";
    var chromeAccountLinkName = "Account settings";
    var chromeContactUsLinkName = "Contact us";
    
    
  4. For each language for which you are localizing the app, add another JavaScript file with the name ChromeStrings.LL-CC.js, where LL-CC is the language ID. The base of the file name, in this case "ChromeStrings," must be exactly the same as you used for the invariant language file. Copy the contents of the invariant language file into each of the localized files and replace the values with translated versions. The following is an example file called ChromeStrings.es-ES.js

    var chromeAppTitle = "Mi aplicación SharePoint";
    var chromeAccountLinkName = "Preferencias";
    var chromeContactUsLinkName = "Contacto";
    
    
  5. In any page file where the script SP.UI.controls.js is called, add a call to the ChromeStrings.js above it. For example, if the call to SP.UI.controls.js is loaded in an intermediate file called ChromeLoader.js, the markup in the page at this point should look similar to the following example.

    <Scripts>
      <asp:ScriptReference Path="Scripts/ChromeStrings.js" />
      <asp:ScriptReference Path="Scripts/ChromeLoader.js" />
    </Scripts>
    
  6. Add a ResourceUICultures attribute to the ScriptReference element that calls your strings. Its value is a comma-delimited list of the languages that you are supporting. The following is an example.

    <Scripts>
      <asp:ScriptReference Path="Scripts/ChromeStrings.js" ResourceUICultures="en-US,es-ES" />
      <asp:ScriptReference Path="Scripts/ChromeLoader.js" />
    </Scripts>
    

    The effect of the ResourceUICultures attribute is that ASP.NET will look for a file with the name ChromeStrings.LL-CC.js, where LL-CC is the language of the page and load it. If it doesn't find such a file, it will load the ChromeStrings.js file.

You can test your app by deploying it to a SharePoint website that is provisioned in one of the languages supported by your app. You can test your app on a SharePoint Online website or an on-premises website.

To test your app on a SharePoint Online website

  1. Go to your Office 365 admin center.

  2. Choose service settings on the navigation menu, and then choose sites.

  3. Under site collections, choose Create site collection.

  4. Under select a language, select the language in which you want to test your app.

  5. Under select a template, choose Developer Site.

  6. In your app for SharePoint project, update the SiteUrl property with the URL of the new site collection.

  7. Press F5 to run the app.

The following image shows the create site collection page.

Figure 7. Create site collection page

Create site collection page

To test your app an on-premises website

  1. Install the language pack in which you want to test your app. For more information, see Install or uninstall language packs for SharePoint 2013 and Language packs in SharePoint Server 2013.

  2. Open Central Administration for the farm.

  3. Under Application Management, choose Create site collections.

  4. Under select a language, select the language in which you want to test your app.

  5. Under select a template, choose Developer Site.

  6. In your app for SharePoint project, update the SiteUrl to the URL of the recently created site collection.

  7. Press F5 to run the app.

Show:
© 2014 Microsoft