Export (0) Print
Expand All

How to: Build a localized app for Office

apps for Office

How to

This topic walks through how to localize the app description and display name for an app for Office. It also describes how to localize the text displayed in the user interface (UI) by using a resource file that is stored separately from your main program logic. The resource file contains localized text strings for the languages that your app supports.

Last modified: February 27, 2014

Applies to: Excel 2013 | Excel 2013 RT | Excel 2013 SP1 | Excel Online | PowerPoint 2013 | PowerPoint 2013 RT | PowerPoint 2013 SP1 | PowerPoint Online | Project 2013 | Project 2013 SP1 | Word 2013 | Word 2013 RT | Word 2013 SP1

   Office.js: v1.0, v1.1

   Apps for Office manifests schema: v1.0, v1.1

In this article

Before you begin
Localize the text used in your app
Test your localized app
Additional resources

To run the sample code provided in this article, you need to configure Microsoft Office 2013 on your computer to use additional languages so that you can test your app by switching the language used for display in menus and commands, switching the language used for editing and proofing, or both.

Also, you'll need to create a Microsoft Visual Studio 2013 or Visual Studio 2012 app for Office project so that you can run the sample code provided.

Note Note

To download the Microsoft Office Developer Tools for Visual Studio 2012, see "Tools" on the Download page.

To download Visual Studio 2013, see the Visual Studio Downloads page.

Configure Office 2013 to use additional languages for display or editing

You can use an Office 2013 Language pack to install an additional language. For more information about Language Packs and where to get them, see Office 2013 Language Options.

Note Note

If you are an MSDN Subscriber, you may have the Office 2013 Language Packs available to you as part of your subscription. To see if your subscription offers Office 2013 Language Packs for download, go to MSDN Subscriptions Home, enter Office 2013 Language Pack in Software downloads, choose Search, and then select Products available with my subscription. Under Language, select the check box for the Language Pack you want to download, and then choose Go.

Once you install the Language Pack, you can configure Office 2013 to use the installed language for display in the UI, for editing document content, or both. The example in this article uses an installation of Office 2013 that has the Spanish Language Pack applied.

Create the sample app for Office project

To complete these steps, you need to create an app for Office in Visual Studio. You create a taskpane app for Office that runs in Word 2013.

To create the sample app for Office in Visual Studio

  1. In Visual Studio, choose File, New Project.

  2. In the New Project dialog box, under Templates, expand Visual Basic or Visual C#, expand Office\SharePoint, and then choose Apps.

  3. Choose App for Office 2013, and then name your app, for example WorldReadyApp. Choose OK.

  4. In the Create app for Office dialog box, select Task pane app in: and then clear the check boxes for all host applications except Word. Choose Finish to create the project.

You use this project to complete all the steps in this topic.

Usually, in an app for Office, the text that you want to localize for another language is the text that appears in two areas:

  • App display name and description. The text for the app display name and description is controlled by entries in the app manifest file.

  • App UI. You can localize the strings that appear in your app UI by using JavaScript code—for example, by using a separate resource file that contains the localized strings.

Localize the text used for the app display name and description

To localize the app display name and description, you use the app manifest. Complete the following steps to add localized versions of the app display name and description.

To localize the app display name and description

  1. In Solution Explorer, expand WorldReadyApp, WorldReadyAppManifest, and then choose WorldReadyApp.xml.

  2. In the XML for WorldReadyAppManifest.xml, add the following block of code immediately after the DefaultLocale element:

    Note Note

    You can replace the Spanish language localized strings used in this example for the DisplayName and Description elements with the localized strings for whatever language you are using for your app.

    <DisplayName DefaultValue="World Ready App">
        <Override Locale="es-es" Value="Aplicación de uso internacional"/>
      <Description DefaultValue="An app for testing localization">
        <Override Locale="es-es" Value="Una aplicación para la prueba de la localización"/>
  3. When you change the display language for Office 2013 from English to Spanish, for example, and then run the app, the app display name and description are shown with localized text, as shown in figures 1 and 2.

    Figure 1. Non-localized app display name and description

    App display name and description in the Ribbon.

    Figure 2. Localized app display name and description

    App display name and description in the Ribbon-ES.

The next section walks through creating the layout for the app UI.

Lay out the sample app UI

The app UI includes the controls such as buttons, labels, headings, and so on. Complete the following steps to lay out the UI for the sample app.

To lay out the sample app UI

  1. In Visual Studio, in Solution Explorer, choose Home.html.

  2. Replace the HTML in Home.html with the following HTML.

    <!DOCTYPE html>
        <meta charset="UTF-8" />
        <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
        <script src="../../Scripts/jquery-1.8.2.js" type="text/javascript"></script>
        <link href="../../Content/Office.css" rel="stylesheet" type="text/css" />
        <script src="https://appsforoffice.microsoft.com/lib/1.0/hosted/office.js" type="text/javascript"></script>
        <!-- To enable offline debugging using a local reference to Office.js, use:                        -->
        <!-- <script src="../../Scripts/Office/MicrosoftAjax.js" type="text/javascript"></script>          -->
        <!--    <script src="../../Scripts/Office/1.0/office.js" type="text/javascript"></script>          -->
        <link href="../App.css" rel="stylesheet" type="text/css" />
        <script src="../App.js" type="text/javascript"></script>
        <link href="Home.css" rel="stylesheet" type="text/css" />
        <script src="Home.js" type="text/javascript"></script> <body>
        <!-- Page content -->
        <div id="content-header">
            <div class="padding">
                <h1 id="greeting"></h1>
        <div id="content-main">
            <div class="padding">
                    <p id="about"></p>
  3. In Visual Studio, choose File, Save App\Home\Home.html.

Figure 3 shows the heading (<h1>) element and the paragraph (<p>) element that will display localized text when your sample app runs.

Figure 3. The app UI

App user interface with sections highlighted.

Add the resource file that contains the localized strings

The JavaScript resource file contains the strings used for the app UI. The sample app UI has an <h1> element that displays a greeting, and a <p> element that introduces the app to the user.

To enable localized strings for the heading and paragraph, you place the strings in a separate resource file. The resource file creates a JavaScript object that contains a separate JavaScript Object Notation (JSON) object for each set of localized strings. The resource file also provides a method for getting back the appropriate JSON object for a given locale. The following procedure walks through adding the JavaScript resource file to the app project.

To add the resource file to the sample app project

  1. In Solution Explorer in Visual Studio, choose the App folder in the web project for the sample app, and choose Add, JavaScript file.

  2. In the Specify Name for Item dialog box, enter UIStrings.js.

  3. Add the following code to the UIStrings.js file.

    /* Store the locale-specific strings */
    var UIStrings = (function ()
        "use strict";
        var UIStrings = {};
        // JSON object for English strings
        UIStrings.EN =
            "Greeting": "Welcome",
            "Introduction": "This is my localized app."        
        // JSON object for Spanish strings
        UIStrings.ES =
            "Greeting": "Bienvenido",
            "Introduction": "Esta es mi aplicación localizada."
        UIStrings.getLocaleStrings = function (locale)
            var text;
            // Get the resource strings that match the language.
            switch (locale)
                case 'en-US':
                    text = UIStrings.EN;
                case 'es-ES':
                    text = UIStrings.ES;
                    text = UIStrings.EN;
            return text;
        return UIStrings;

The UIStrings.js resource file creates an object, UIStrings, which contains the localized strings for your app UI. The next section shows how to use UIStrings to apply the localized strings to your app.

Localize the text used for the app UI

To use the resource file in your app, you'll need to add a script tag for it on Home.html. When Home.html is loaded, UIStrings.js executes and the UIStrings object that you use to get the strings is available to your code. Add the following HTML in the head tag for Home.html to make UIStrings available to your code.

<!-- Resource file for localized strings:                                                          -->
<script src="../UIStrings.js" type="text/javascript"></script>

Now you can use the UIStrings object to set the strings for the UI of your app.

If you want to change the localization for your app based on what language is used for display in menus and commands in the host application, you use the Office.context.displayLanguage property to get the locale for that language. For example, if the host application language uses Spanish for display in menus and commands, the Office.context.displayLanguage property will return the language code es-ES.

If you want to change the localization for your app based on what language is being used for editing document content, you use the Office.context.contentLanguage property to get the locale for that language. For example, if the host application language uses Spanish for editing document content, the Office.context.contentLanguage property will return the language code es-ES.

Once you know the language the host application is using, you can use UIStrings to get the set of localized strings that matches the host application language.

Replace the code in the Home.js file with the following code. The code shows how you can change the strings used in the UI elements on Home.html based on either the display language of the host application or the editing language of the host application.


To switch between changing the localization of the app based on the language used for editing, uncomment the line of code var myLanguage = Office.context.contentLanguage; and comment out the line of code var myLanguage = Office.context.displayLanguage;

/// <reference path="../App.js" />
/// <reference path="../UIStrings.js" />

(function () {
    "use strict";

    // The initialize function must be run each time a new page is loaded.
    Office.initialize = function (reason)
        $(document).ready(function () {

            // Get the language setting for editing document content.
            // To test this, uncomment the following line and then comment out the
            // line that uses Office.context.displayLanguage.
            // var myLanguage = Office.context.contentLanguage;

            // Get the language setting for UI display in the host application.
            var myLanguage = Office.context.displayLanguage;            
            var UIText;

            // Get the resource strings that match the language.
            // Use the UIStrings object from the UIStrings.js file
            // to get the JSON object with the correct localized strings.
            UIText = UIStrings.getLocaleStrings(myLanguage);            

            // Set localized text for UI elements.

To test your localized app, change the language used for display or for editing in the host application and then run your app. Use the following steps to change the language used in the host application.

To change the language used for display or editing in your app

  1. In Word 2013, choose File, Options, Language. Figure 4 shows the Word Options dialog box opened to the Language tab.

    Figure 4. Language options in the Word 2013 Options dialog box

    Word 2013 Options dialog.
  2. Under Choose Display and Help Languages, select the language that you want for display, for example Spanish, and then choose the up arrow to move the Spanish language to the first position in the list. Alternatively, to change the language used for editing, under Choose editing languages, choose the language you want to use for editing, for example, Spanish, and then choose Set as Default.

  3. Choose OK to confirm your selection, and then close Word.

Run the sample app. The taskpane app loads in Word 2013, and the strings in the app UI change to match the language used by the host application, as shown in Figure 5.

Figure 5. App UI with localized text

App with localized UI text.
© 2014 Microsoft