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 的统一清单（仅在 Outlook 上受支持）。
每个 Office 外接程序在其清单中指定一个 DefaultLocale 元素和区域设置。 默认情况下，Office 外接程序平台和 Office 客户端应用程序将 Description、 DisplayName、 IconUrl、 HighResolutionIconUrl 和 SourceLocation 元素的值应用于所有区域设置。 可以通过为每个其他区域设置的上述五个元素中的任意一个指定 Override 子元素来选择支持将特定值用于特定的区域设置。
DefaultLocale 元素的值和 LocaleOverride 元素的 属性的值根据 RFC 3066“用于语言标识的标记”进行指定。下表介绍了对这些元素的本地化支持。
| 元素 | 本地化支持 |
|---|---|
| 说明 | 指定的每个区域设置中的用户都可以在 AppSource（或专有目录）中看到本地化的加载项说明。 对于 Outlook 加载项，在安装后，用户可以在 Exchange 管理中心 (EAC) 中看到说明。 |
| DisplayName | 指定的每个区域设置中的用户都可以在 AppSource（或专有目录）中看到本地化的加载项说明。 对于 Outlook 加载项，在安装后，用户可以看到显示名称为 Outlook 加载项按钮标签，也可以在 EAC 中看到显示名称。 对于内容和任务窗格加载项，用户可以在安装加载项后在功能区上看到显示名称。 |
| IconUrl | 图标图像是可选的。 可以使用相同的替代方法为特定区域性指定特定图像。 如果使用并本地化图标，则您指定的每个区域设置中的用户均可看到该加载项的本地化图标图像。 对于 Outlook 外接程序，安装外接程序后，用户可以在 EAC 中看到该图标。 对于内容和任务窗格加载项，用户可以在安装加载项后在功能区上看到图标。 |
| HighResolutionIconUrl重要说明：此元素仅适用于使用加载项清单版本 1.1 的情况。 | 高分辨率图标图像是可选的，但如果指定，它必须出现在 IconUrl 元素之后。 指定 HighResolutionIconUrl 且在支持高 DPI 分辨率的设备上安装了加载项后，将使用 HighResolutionIconUrl 值而不是 IconUrl 值。 可以使用相同的替代方法为特定区域性指定特定图像。 如果使用并本地化图标，则您指定的每个区域设置中的用户均可看到该加载项的本地化图标图像。 对于 Outlook 外接程序，安装外接程序后，用户可以在 EAC 中看到该图标。 对于内容和任务窗格加载项，用户可以在安装加载项后在功能区上看到图标。 |
| Resources重要说明：此元素仅适用于使用加载项清单版本 1.1 的情况。 | 指定的每个区域设置中的用户都可以看到专门针对相应区域设置为加载项创建的字符串和图标资源。 |
| SourceLocation | 指定的每个区域设置中的用户都可以看到专门针对该区域设置为该加载项设计的网页。 |
注意
可以仅为 Office 支持的语言环境对说明和显示名称进行本地化。 有关当前版本的 Office 的语言和区域设置列表，请参阅 为 Microsoft 365 应用部署语言的概述 。
示例
例如，Office 外接程序可以将 DefaultLocale 指定为 en-us。 对于 DisplayName 元素，外接程序可以为区域fr-fr设置 指定 Override 子元素，如下所示。
<DefaultLocale>en-us</DefaultLocale>
...
<DisplayName DefaultValue="Video player">
<Override Locale="fr-fr" Value="Lecteur vidéo" />
</DisplayName>
注意
如需针对一个语系内的多个区域进行本地化，例如 de-de 和 de-at，则建议对各个区域使用独立的 Override 元素。 在本例中， de不支持在 Office 客户端应用程序和平台的所有组合中使用语言名称。
这意味着外接程序默认采用 en-us 区域设置。 除非客户端计算机的区域设置为 fr-fr（此时用户将看到法语的显示名称“Lecteur vidéo”），否则对于所有区域设置，用户都将看到英文显示名称“Video player”。
注意
每种语言只可指定单一的覆盖，包括对于默认区域设置的覆盖。 例如，如果默认区域设置为 en-us ，则不能同时指定 en-us 替代。
以下示例对 Description 元素应用区域设置替代。 它首先指定的默认区域en-us设置和英语说明，然后指定带有区域设置法语说明的 fr-frOverride 语句。
<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."/>
</Description>
这意味着外接程序默认采用 en-us 区域设置。 除非客户端计算机的区域设置为 DefaultValue（此时用户将看到法语说明），否则对于所有区域设置，用户都将看到 fr-fr 属性中的英文说明。
在以下示例中，外接程序指定更适合区域设置和区域性的 fr-fr 单独图像。 默认情况下，用户会看到图像 DefaultLogo.png，客户端计算机的区域设置为 fr-fr 时除外。 此时，用户将看到图像 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"/>
以下示例演示如何在 节中 Resources 本地化资源。 它为更适合 ja-jp 区域性的图像应用区域设置替代。
<Resources>
<bt:Images>
<bt:Image id="icon1_16x16" DefaultValue="https://www.contoso.com/icon_default.png">
<bt:Override Locale="ja-jp" Value="https://www.contoso.com/ja-jp16-icon_default.png" />
</bt:Image>
...
对于 SourceLocation 元素，支持其他区域设置意味着为每个指定的区域设置提供单独的源 HTML 文件。 您指定的每个区域设置中的用户可以看到您为该区域设置设计的自定义网页。
对于 Outlook 外接程序， SourceLocation 元素也与外形规格保持一致。 这使您可为每个对应的设备类型提供单独的本地化源 HTML 文件。 可在每个适用的设置元素（ DesktopSettings、 TabletSettings 或 PhoneSettings）中指定一个或多个 Override 子元素。 以下示例显示用于台式机、平板电脑和 Smartphone 设备的设置元素，每个元素分别具有一个用于默认区域设置的 HTML 文件和一个用于法语区域设置的 HTML 文件。
<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>
本地化扩展替代
注意
如果使用统一清单，则本部分不适用。
当外接程序使用仅外接程序清单时，Office 外接程序的某些扩展性功能（如键盘快捷方式）使用托管在服务器上的 JSON 文件进行配置，而不是使用外接程序的 XML 格式清单。 本部分假定你熟悉扩展替代。 请参阅使用清单和 ExtendedOverrides 元素的扩展重写。
ResourceUrl使用 ExtendedOverrides 元素的 属性将 Office 指向本地化的资源文件。 示例如下。
...
</VersionOverrides>
<ExtendedOverrides Url="https://contoso.com/addin/extended-overrides.json"
ResourceUrl="https://contoso.com/addin/my-resources.json">
</ExtendedOverrides>
</OfficeApp>
然后，扩展重写文件使用标记而不是字符串。 资源文件中的标记名称字符串。 下面是一个示例，该示例将键盘快捷方式分配给在其他地方定义的函数 (，) 显示外接程序的任务窗格。 有关此标记的注意事项：
- 该示例不太有效。 (下面添加了所需的附加属性。)
- 令牌的格式必须为 ${resource。name-of-resource}。
{
"actions": [
{
"id": "SHOWTASKPANE",
"type": "ExecuteFunction",
"name": "${resource.SHOWTASKPANE_action_name}"
}
],
"shortcuts": [
{
"action": "SHOWTASKPANE",
"key": {
"default": "${resource.SHOWTASKPANE_default_shortcut}"
}
}
]
}
资源文件也采用 JSON 格式，具有按区域设置划分为子属性的顶级 resources 属性。 对于每个区域设置，都会向扩展重写文件中使用的每个令牌分配一个字符串。 下面是一个包含 和 fr-fr的en-us字符串的示例。 在此示例中，键盘快捷方式在两个区域设置中是相同的，但情况并不总是如此，尤其是在本地化具有不同字母或书写系统的区域设置时，因此键盘也不同。
{
"resources":{
"en-us": {
"SHOWTASKPANE_default_shortcut": {
"value": "CTRL+SHIFT+A",
},
"SHOWTASKPANE_action_name": {
"value": "Show task pane for add-in",
},
},
"fr-fr": {
"SHOWTASKPANE_default_shortcut": {
"value": "CTRL+SHIFT+A",
},
"SHOWTASKPANE_action_name": {
"value": "Afficher le volet de tâche pour add-in",
}
}
}
}
文件中没有default与 和 fr-fr 节对等的属性en-us。 这是因为，在 Office 主机应用程序的区域设置与资源文件中的任何 ll-cc 属性不匹配时使用的默认字符串 必须在扩展重写文件本身中定义。 直接在扩展重写文件中定义默认字符串可确保当 Office 应用程序的区域设置与清单) 中指定的外接程序 (的默认区域设置匹配时，Office 不会下载资源文件。 下面是使用资源令牌的扩展替代文件的前面示例的更正版本。
{
"actions": [
{
"id": "SHOWTASKPANE",
"type": "ExecuteFunction",
"name": "${resource.SHOWTASKPANE_action_name}"
}
],
"shortcuts": [
{
"action": "SHOWTASKPANE",
"key": {
"default": "${resource.SHOWTASKPANE_default_shortcut}"
}
}
],
"resources": {
"default": {
"SHOWTASKPANE_default_shortcut": {
"value": "CTRL+SHIFT+A",
},
"SHOWTASKPANE_action_name": {
"value": "Show task pane for add-in",
}
}
}
}
将日期/时间格式与客户端区域设置匹配
可以使用 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 开发工作负载。
选择“创建新项目”。
使用搜索框，输入“加载项”。 选择“Word Web 外接程序”，然后选择“下一步”。
将项目命名 为 WorldReadyAddIn ，然后选择“ 创建”。
此时，Visual Studio 创建解决方案，且它的两个项目显示在“解决方案资源管理器”中。 Home.html 文件将在 Visual Studio 中打开。
本地化加载项中使用的文本
要本地化其他语言的文本显示在两个区域中。
加载项显示名称和说明 。 这是受应用程序清单文件中的条目控制的。
加载项 UI。 可以通过使用 JavaScript 代码本地化在加载项 UI 中出现的字符串（例如，通过使用包含已本地化的字符串的单独资源文件）。
本地化加载项显示名称和说明
在“解决方案资源管理器”中，展开“WorldReadyAddIn”、“WorldReadyAddInManifest”，然后选择“WorldReadyAddIn.xml”。
在 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>例如，将 Microsoft 365 的显示语言从英语更改为西班牙语，然后运行外接程序时，外接程序显示名称和说明将带有本地化文本。
设置加载项 UI 的布局
在 Visual Studio 的“解决方案资源管理器”中，选择“Home.html”。
在 Home.html 中，将
<body>元素替换为以下 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 对象的方法。
将资源文件添加到外接程序项目
在 Visual Studio 中的“解决方案资源管理器”中 ，右键单击“ (”或选择并按住“ WorldReadyAddInWeb ”项目) ，然后选择“ 添加新>项”。
在“添加新项目”对话框中，选择“JavaScript 文件”。
输入文件名 UIStrings.js，然后选择“添加”。
将以下代码添加到 UIStrings.js 文件，然后保存文件。
/* Store the locale-specific strings */ const UIStrings = (function () { "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 = function (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" />
(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.
// 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 应用程序中显示或编辑的语言，然后运行加载项。
在 Word 中，选择“文件”>“选项”>“语言”。 下图显示打开了“语言”选项卡的“Word 选项”对话框。
图 2. “Word 选项”对话框中的语言选项
在“选择显示语言”下，选择想要显示的语言，例如西班牙语，然后选择向上箭头键将西班牙语移至列表中的第一个位置。 或者，若要更改用于编辑的语言，请在 “选择编辑语言”下，选择要用于编辑的语言（例如西班牙语），然后选择“ 设置为默认值”。
选择“确定”确认选择，然后关闭 Word。
在 Visual Studio 中按 F5 以运行示例加载项，或者从菜单栏中选择“调试”>“开始调试”。
在 Word 中选择“开始”>“显示任务窗格”。
运行后，外接程序 UI 中的字符串会更改，以匹配应用程序使用的语言，如下图所示。
