通过

Office 加载项的本地化

  • 项目

您可以实现适合 Office 外接程序的任何本地化方案。 Office 外接程序平台的 JavaScript API 和清单架构提供了一些选择。 可以使用 Office JavaScript API 根据 Office 应用程序的区域设置确定区域设置和显示字符串，或者根据数据的区域设置解释或显示数据。 可以使用清单指定区域设置特定的加载项文件位置和描述性信息。 或者，可以使用 Visual Studio 和 Microsoft Ajax 脚本来支持全球化和本地化。

使用 JavaScript API 确定区域设置特定的字符串

Office JavaScript API 提供了两个属性，这些属性支持显示或解释与 Office 应用程序和数据的区域设置一致的值。

  • Context.displayLanguage 指定 Office 应用程序用户界面的区域设置 (或语言) 。 以下示例验证 Office 应用程序是使用 en-US 还是 fr-FR 区域设置，并显示特定于区域设置的问候语。

    function sayHelloWithDisplayLanguage() {
    const 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 指定数据的区域设置（或语言）。 扩展最后一个代码示例，而不是检查 displayLanguage 属性，而是分配 myLanguagecontentLanguage 属性的值，并使用相同代码的其余部分基于数据的区域设置显示问候语。

    const myLanguage = Office.context.contentLanguage;

通过清单控制本地化

使用清单进行本地化的技术有所不同，具体取决于你使用的是仅外接程序清单还是使用 Microsoft 365 的统一应用清单。

使用 Microsoft 365 的统一应用清单时，请本地化清单中面向公众的字符串，如本地化 应用清单中的字符串中所述。 下面是 Outlook 加载项的示例。 第一个是清单中的“localizationInfo”对象。 下面是包含已翻译字符串的 fr-fr.json 文件。 加载项具有一个任务窗格 (，其中包含法语版本的主页) 、本地化的法语图标，以及一个在对话框中打开视频播放器的自定义功能区按钮。

"localizationInfo": {
  "defaultLanguageTag": "en",
  "additionalLanguages": [
    {
      "languageTag": "fr-fr",
      "file": "fr-fr.json"
    }
  ]
}

{
  "$schema": "https://developer.microsoft.com/json-schemas/teams/v1.16/MicrosoftTeams.Localization.schema.json",
  "name.short": "Lecteur vidéo",
  "name.full": "Lecteur vidéo pour Outlook",
  "description.short": "Voir les vidéos YouTube dans Outlook via les mails.",
  "description.full": "Visualisez les vidéos YouTube référencées dans vos courriers électronique directement depuis Outlook.",
  "icons.color": "https://localhost:3000/assets/fr-fr/icon-128.png",
  "extensions[0].audienceClaimUrl": "https://localhost:3000/fr-fr/taskpane.html",
  "extensions[0].ribbons[0].tabs[0].groups[0].label": "Outils de médias",
  "extensions[0].ribbons[0].tabs[0].groups[0].controls[0].icons[0].url": "https://localhost:3000/assets/fr-fr/player-icon.png",
  "extensions[0].ribbons[0].tabs[0].groups[0].controls[0].label": "Ouvrir le lecteur vidéo",
  "extensions[0].ribbons[0].tabs[0].groups[0].controls[0].supertip.description": "Cliquez pour ouvrir le lecteur vidéo.",
  "extensions[0].ribbons[0].tabs[0].groups[0].controls[0].supertip.title": "Ouvrir le lecteur vidéo",
}

将日期/时间格式与客户端区域设置匹配

可以使用 displayLanguage 属性获取 Office 客户端应用程序用户界面的区域设置。 然后，可以采用与 Office 应用程序的当前区域设置一致的格式显示日期和时间值。 执行上述操作的一种方法是准备一个指定日期/时间显示格式的资源文件以用于 Office 外界程序支持的各个区域设置。 在运行时，外接程序可以使用资源文件，并将相应的日期/时间格式与从 displayLanguage 属性获取的区域设置相匹配。

可以使用 contentLanguage 属性获取 Office 客户端应用程序数据的区域设置。 基于此值，可以正确地解读或显示日期/时间字符串。 例如，jp-JP 区域设置将数据/时间值表示为 yyyy/MM/dd，而 fr-FR 区域设置则表示为 dd/MM/yyyy。

使用 Visual Studio 创建本地化和全球化加载项

如果使用 Visual Studio 创建 Office 外接程序，.NET Framework 和 Ajax 会提供用于全球化和本地化客户端脚本文件的方法。

您可以全球化 Office 外接程序并在其 JavaScript 代码中使用 Date 和 Number JavaScript 类型扩展和 JavaScript Date 对象，以根据当前浏览器的区域设置显示值。 有关详细信息，请参阅 Walkthrough: Globalizing a Date by Using Client Script。

可将本地化的资源字符串直接包含在独立的 JavaScript 文件中，以便为不同区域设置提供客户端脚本文件，这些文件在浏览器中设置或由用户提供。 为每个受支持的区域设置创建单独的脚本文件。 在每个脚本文件中，包括一个 JSON 格式的对象，其中包含用于该区域设置的资源字符串。 在浏览器中运行脚本时，会应用本地化的值。

示例：生成本地化 Office 加载项

本节提供示例，演示如何本地化 Office 外接程序描述、显示名称和 UI。

注意

若要下载 Visual Studio，请参阅 Visual Studio IDE 页。 在安装过程中，你需要选择 Office/SharePoint 开发工作负载。

配置 Office 以使用其他语言进行显示或编辑

若要运行提供的示例代码，请将计算机上的 Office 配置为使用其他语言，以便你可以通过切换用于在菜单和命令中显示的语言、用于编辑和校对的语言来测试加载项。

可以使用 Office 语言包安装其他语言。 有关语言包以及如何获取语言包的详细信息，请参阅适用于 Office 的 Language Accessory Pack。

安装 Language Accessory Pack 后，可以将 Office 配置使用安装的语言，以便在 UI 中显示，或编辑文档内容，或者两者兼具。 在本文的示例中，所安装的 Office 应用了西班牙语语言包。

创建 Office 加载项项目

需要创建 Visual Studio Office 外接程序项目。

注意

如果尚未安装 Visual Studio，请参阅 Visual Studio IDE 页 以获取下载说明。 在安装过程中，你需要选择 Office/SharePoint 开发工作负载。 如果以前安装了 Visual Studio 2019 或更高版本，请使用Visual Studio 安装程序确保已安装 Office/SharePoint 开发工作负载。

  1. 选择“创建新项目”。

  2. 使用搜索框，输入“加载项”。 选择“Word Web 外接程序”，然后选择“下一步”。

  3. 将项目命名 为 WorldReadyAddIn ，然后选择“ 创建”。

  4. 此时，Visual Studio 创建解决方案，且它的两个项目显示在“解决方案资源管理器”中。 Home.html 文件将在 Visual Studio 中打开。

本地化加载项中使用的文本

要本地化其他语言的文本显示在两个区域中。

  • 加载项显示名称和说明 。 这是受应用程序清单文件中的条目控制的。

  • 加载项 UI。 可以通过使用 JavaScript 代码本地化在加载项 UI 中出现的字符串（例如，通过使用包含已本地化的字符串的单独资源文件）。

本地化加载项显示名称和说明

  1. 在“解决方案资源管理器”中，展开“WorldReadyAddIn”、“WorldReadyAddInManifest”，然后选择“WorldReadyAddIn.xml”。

  2. 在 WorldReadyAddInManifest.xml中，将 DisplayName 和 Description 元素替换为以下代码块。

    注意

    对于本示例中使用的西班牙语本地化字符串的DisplayName 和 Description 元素，您可以替换为任何其他语言的本地化字符串。

    <DisplayName DefaultValue="World Ready add-in">
  <Override Locale="es-es" Value="Aplicación de uso internacional"/>
</DisplayName>
<Description DefaultValue="An add-in for testing localization">
  <Override Locale="es-es" Value="Una aplicación para la prueba de la localización"/>
</Description>

  3. 例如，将 Microsoft 365 的显示语言从英语更改为西班牙语，然后运行外接程序时，外接程序显示名称和说明将带有本地化文本。

设置加载项 UI 的布局

  1. 在 Visual Studio 的“解决方案资源管理器”中，选择“Home.html”。

  2. 将 <body>Home.html 中的元素内容替换为以下 HTML，并保存该文件。

    <body>
    <!-- Page content -->
    <div id="content-header" class="ms-bgColor-themePrimary ms-font-xl">
        <div class="padding">
            <h1 id="greeting" class="ms-fontColor-white"></h1>
        </div>
    </div>
    <div id="content-main">
        <div class="padding">
            <div class="ms-font-m">
                <p id="about"></p>
            </div>
        </div>
    </div>
</body>

下图展示了在完成剩余步骤和运行加载项时显示本地化文本的 heading (h1) 元素和 paragraph (p) 元素。

具有突出显示部分的应用程序用户界面。

添加包含本地化字符串的资源文件

JavaScript 资源文件包含加载项 UI 使用的字符串。 示例加载项 UI 的 HTML 中包含用于显示问候语的 <h1> 元素以及用于向用户介绍加载项的 <p> 元素。

若要为标题和段落启用本地化字符串，您需要将字符串放在一个单独的资源文件中。 资源文件会创建一个 JavaScript 对象，对每组本地化字符串来说，它都包含一个单独的 JavaScript 对象表示法 (JSON) 对象。 资源文件也提供为给定区域设置找回适当 JSON 对象的方法。

将资源文件添加到外接程序项目

  1. 在 Visual Studio 的解决方案资源管理器中，右键单击“ (”或选择并按住“WorldReadyAddInWeb”项目) ，然后选择“添加新>项”。

  2. 在“添加新项目”对话框中，选择“JavaScript 文件”。

  3. 输入文件名 UIStrings.js，然后选择“添加”。

  4. 将以下代码添加到 UIStrings.js 文件，并保存该文件。

    /* Store the locale-specific strings */

const UIStrings = (() => {
    "use strict";

    const UIStrings = {};

    // JSON object for English strings
    UIStrings.EN = {
        "Greeting": "Welcome",
        "Introduction": "This is my localized add-in."
    };

    // JSON object for Spanish strings
    UIStrings.ES = {
        "Greeting": "Bienvenido",
        "Introduction": "Esta es mi aplicación localizada."
    };

    UIStrings.getLocaleStrings = (locale) => {
        let text;

        // Get the resource strings that match the language.
        switch (locale) {
            case 'en-US':
                text = UIStrings.EN;
                break;
            case 'es-ES':
                text = UIStrings.ES;
                break;
            default:
                text = UIStrings.EN;
                break;
        }

        return text;
    };

    return UIStrings;
})();

UIStrings.js 资源文件创建对象 UIStrings，其中包含外接程序 UI 的本地化字符串。

本地化加载项 UI 文本

若要在外接程序中使用资源文件，需要在 Home.html上为其添加脚本标记。 加载 Home.html 时， UIStrings.js 执行，并且用于获取字符串的 UIStrings 对象可用于代码。 在 Home.html 的头标记中添加以下 HTML，使 UIStrings 可用于代码。

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

现在，可以使用 UIStrings 对象，为加载项 UI 设置字符串了。

如果要根据 Office 客户端应用程序的菜单和命令中显示的语言更改加载项的本地化，请使用 Office.context.displayLanguage 属性获取该语言的区域设置。 例如，如果应用程序语言使用西班牙语在菜单和命令中显示， 则 Office.context.displayLanguage 属性将返回语言代码 es-ES。

如果要根据用于编辑文档内容的语言更改加载项的本地化，请使用 Office.context.contentLanguage 属性获取该语言的区域设置。 例如，如果应用程序语言使用西班牙语编辑文档内容， 则 Office.context.contentLanguage 属性将返回语言代码 es-ES。

知道应用程序使用的语言后，可以使用 UIStrings 获取与应用程序语言匹配的本地化字符串集。

将 Home.js 文件中的代码替换为以下代码。 该代码演示如何根据应用程序的显示语言或应用程序的编辑语言更改 Home.html 上的 UI 元素中使用的字符串。

注意

若要根据用于编辑的语言在更改加载项本地化之间切换，请取消注释代码 const myLanguage = Office.context.contentLanguage; 行并注释掉代码行 const myLanguage = Office.context.displayLanguage;

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


(() => {
    "use strict";

    // The initialize function must be run each time a new page is loaded.
    Office.onReady(() => {
        $(document).ready(() => {
            // 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.
            // const myLanguage = Office.context.contentLanguage;
    
            // Get the language setting for UI display in the Office application.
            const myLanguage = Office.context.displayLanguage;
            let 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.
            $("#greeting").text(UIText.Greeting);
            $("#about").text(UIText.Introduction);
        });
    });
})();

测试本地化的加载项

若要测试本地化加载项，请更改用于在 Office 应用程序中显示或编辑的语言，然后运行加载项。

  1. 在 Word 中，选择“文件”>“选项”>“语言”。 下图显示打开了“语言”选项卡的“Word 选项”对话框。

    “Word选项”对话框。

  2. 在“选择显示语言”下，选择想要显示的语言，例如西班牙语，然后选择向上箭头键将西班牙语移至列表中的第一个位置。 或者，若要更改用于编辑的语言，请在 “选择编辑语言”下，选择要用于编辑的语言（例如西班牙语），然后选择“ 设置为默认值”。

  3. 选择“确定”确认选择，然后关闭 Word。

  4. 在 Visual Studio 中按 F5 以运行示例加载项，或者从菜单栏中选择“调试”>“开始调试”。

  5. 在 Word 中选择“开始”>“显示任务窗格”。

运行后，外接程序 UI 中的字符串会更改，以匹配应用程序使用的语言，如下图所示。

具有本地化 UI 文本的应用。

另请参阅