1 out of 2 rated this helpful - Rate this topic

Designing an app for Office for specific locales

apps for Office

This topic describes a few ways to provide locale-specific content for an app for Office, including locale-specific user interface strings, app name, description, icon, source file, and date/time format.

Last modified: February 27, 2014

Applies to: Access app for SharePoint | apps for Office | Excel 2013 | Excel Online | Exchange Online | Exchange Server 2013 | Office 2013 | Office 365 | Outlook 2013 | Outlook Web App | OWA for Devices | PowerPoint 2013 | Project Professional 2013 | Word 2013

   Office.js: v1.0, v1.1

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

Note Note

Unless otherwise specified, references to "Outlook" apply to the Outlook rich client, Outlook Web App, and OWA for Devices.

In this article
Using JavaScript API to determine locale-specific strings
Controlling localization from the manifest
Matching date/time format with client locale
Using Ajax for globalization and localization
Additional resources

As a developer for apps for Office, you are free to implement any localization scheme that’s appropriate for your app. The JavaScript API and manifest schema of the apps for Office platform provide some choices. You can use the JavaScript API for Office to determine a locale and display strings based on the locale of the host application, or to interpret or display data based on the locale of the data. You can use the manifest to specify locale-specific app file location and descriptive information. Alternatively, you can use Microsoft Ajax script to support globalization and localization.

The JavaScript API for Office provides 2 properties that support displaying or interpreting values consistent with the locale of the host application and data respectively:

  • Context.displayLanguage specifies the locale (or language) of the user interface of the host application. The following example verifies if the host application uses the en-US or fr-Fr locale, and displays a locale-specific greeting.

    function sayHelloWithDisplayLanguage() {
        var myLanguage = Office.context.displayLanguage;
        switch (myLanguage) {
            case 'en-US':
                write('Hello!');
                break;
            case 'fr-FR':
                write('Bonjour!');
                break;
        }
    }
    // Function that writes to a div with id='message' on the page.
    function write(message){
        document.getElementById('message').innerText += message; 
    }
    
    
  • Context.contentLanguage specifies the locale (or language) of the data. Extending the last code sample, instead of checking the displayLanguage property:

    var myLanguage = Office.context.displayLanguage;
    

    assign myLanguage to the contentLanguage property, and use the rest of the same code to display a greeting based on the locale of the data:

    var myLanguage = Office.context.contentLanguage;
    

Every app for Office specifies a DefaultLocale element and a locale in its manifest. By default, the app for Office platform and Office host applications apply the values of the Description, DisplayName, IconUrl (if present), HighResolutionIconUrl (if present), and SourceLocation elements to all locales. You can optionally support specific values for specific locales, by specifying an Override child element for each additional locale, for any of these five elements. The value for the DefaultLocale element and for the Locale attribute of the Overrride element is specified according to RFC 3066, "Tags for the Identification of Languages." Table 1 describes the localizing support for these elements.

Table 1. Localization support

Element

Localization support

Description *

Users in each locale you specify can see a localized description for the app in the Office Store (or private catalog).

For mail apps, users can see the description in the Exchange Admin Center (EAC) after installation.

DisplayName *

Users in each locale you specify can see a localized description for the app in the Office Store (or private catalog).

For mail apps, users can see the display name as a label for the Outlook app button and in the EAC after installation.

For content and task pane apps, users can see the display name in the ribbon after installing the app.

IconUrl

The icon image is optional. You can use the same override technique to specify a certain image for a specific culture. If you use and localize an icon, users in each locale you specify can see a localized icon image for the app.

For mail apps, users can see the icon in the EAC after installing the app.

For content and task pane apps, users can see the icon in the ribbon after installing the app.

HighResolutionIconUrl

Important note Important

This element is available only with apps for Office manifest schema version 1.1.

The high resolution icon image is optional but if it is specified, it must occur after the IconUrl element. When HighResolutionIconUrl is specified, and the app is installed on a device that supports high dpi resolution, the HighResolutionIconUrl value is used instead of the value for IconUrl.

You can use the same override technique to specify a certain image for a specific culture. If you use and localize an icon, users in each locale you specify can see a localized icon image for the app.

For mail apps, users can see the icon in the EAC after installing the app.

For content and task pane apps, users can see the icon in the ribbon after installing the app.

SourceLocation

Users in each locale you specify can see a webpage that you specifically design for the app for that locale.

Note Note

* You can localize the description and display name for only the locales that Office supports. See Language identifiers and OptionState Id values in Office 2013 for a list of languages and locales for the current release of Office.

Examples

For example, an app for Office can specify the DefaultLocale as en-us. For the DisplayName element, the app can specify an Override child element for the locale fr-fr, as shown below.

<DefaultLocale>en-us</DefaultLocale>
…
<DisplayName DefaultValue="Video player">
    <Override Locale="fr-fr" Value="Lecteur vidéo" />
</DisplayName>

This means that the app assumes the en-us locale by default. Users see the English display name of "Video player" for all locales unless the client computer’s locale is fr-fr, in which case users would see the French display name "Lecteur vidéo".

The following example applies a locale override for the Description element. It first specifies a default locale of en-us and an English description, and then specifies an Override statement with a French description for the fr-fr locale:

    <DefaultLocale>en-us</DefaultLocale>
…
    <Description DefaultValue=
      "Watch YouTube videos referenced in the emails you receive 
      without leaving your email client.">
      <Override Locale="fr-fr" Value=
      "Visualisez les vidéos YouTube référencées dans vos courriers 
      électronique directement depuis Outlook et Outlook Web App."/>
    </Description>

This means that the app assumes the en-us locale by default. Users would see the English description in the DefaultValue attribute for all locales unless the client computer’s locale is fr-fr, in which case they would see the French description.

In the following example, the app specifies a separate image that’s more appropriate for the fr-fr locale and culture. Users see the image DefaultLogo.png by default, except when the locale of the client computer is fr-fr. In this case, users would see the image FrenchLogo.png.

<!-- Replace "domain" with a real web server name and path. -->
<IconUrl DefaultValue="https://<domain>/DefaultLogo.png"/>
    <Override Locale="fr-fr" Value="https://<domain>/FrenchLogo.png"/>

For the SourceLocation element, supporting additional locales means providing a separate source HTML file for each of the specified locales. Users in each locale you specify can see a customized webpage that you design for that them.

For mail apps, the SourceLocation element also aligns to the form factor. This allows you to provide a separate, localized source HTML file for each corresponding form factor. You can specify one or more Override child elements in each applicable settings element (DesktopSettings, TabletSettings, or PhoneSettings). The following example shows settings elements for the desktop, tablet, and smartphone form factors, each with one HTML file for the default locale and another for the French locale.

<DesktopSettings>
   <SourceLocation DefaultValue="https://contoso.com/Desktop.html">
      <Override Locale="fr-fr" Value="https://contoso.com/fr/Desktop.html" />
   </SourceLocation>
   <RequestedHeight>250</RequestedHeight>
</DesktopSettings>
<TabletSettings>
   <SourceLocation DefaultValue="https://contoso.com/Tablet.html">
      <Override Locale="fr-fr" Value="https://contoso.com/fr/Tablet.html" />
   </SourceLocation>
   <RequestedHeight>200</RequestedHeight>
</TabletSettings>
<PhoneSettings>
   <SourceLocation DefaultValue="https://contoso.com/Mobile.html">
      <Override Locale="fr-fr" Value="https://contoso.com/fr/Mobile.html" />
   </SourceLocation>

</PhoneSettings>

You can get the locale of the user interface of the hosting application by using the displayLanguage property. You can then display date and time values in a format consistent with the current locale of the host application. One way to do that is to prepare a resource file that specifies the date/time display format to use for each locale that your app for Office supports. At run time, your app can use the resource file and match the appropriate date/time format with the locale obtained from the displayLanguage property.

You can get the locale of the data of the hosting application by using the contentLanguage property. Based on this value, you can then appropriately interpret or display date/time strings. For example, the jp-JP locale expresses data/time values as yyyy/MM/dd, and the fr-FR locale, dd/MM/yyyy.

If you use Visual Studio to create apps for Office, the .NET Framework and Ajax provide ways to globalize and localize client script files.

You can globalize and use the Date and Number JavaScript type extensions and the JavaScript Date object in the JavaScript code for an app for Office to display values based on the locale settings on the current browser. For more information, see Walkthrough: Globalizing a Date by Using Client Script.

You can include localized resource strings directly in standalone JavaScript files to provide client script files for different locales, which are set on the browser or provided by the user. Create a separate script file for each supported locale. In each script file, include an object in JSON format that contains the resource strings for that locale. The localized values are applied when the script runs in the browser. See How to: Build a localized app for Office for an example.

Community Additions

ADD
Show:
© 2014 Microsoft. All rights reserved.