为 Power BI 视觉对象添加本地语言

项目
03/23/2023

Power BI 支持一系列本地语言。你可以检索 Power BI 区域设置语言，并使用它在视觉对象中显示内容。

以下选项卡显示以不同语言显示内容的相同示例条形图视觉对象示例。每个条形图都是使用不同的区域设置语言（英语、巴斯克语和印地语）创建的，这些语言均显示在工具提示中。

Sample Bar Chart visual displaying in English.

注意

API 1.10.0 和更高版本支持视觉对象代码中的本地化管理器。
开发过程中调试视觉对象不支持本地化。

如何向视觉对象添加本地 Power BI 语言

若要向视觉对象添加本地 Power BI 语言，请执行以下步骤：

设置环境以显示非英语语言。
获取本地 Power BI 语言。
设置视觉对象显示名称
创建语言文件夹。
为每种语言添加一个资源文件。
创建新的 localizationManager 实例。
调用 getDisplayName 函数。

步骤 1 - 设置环境以显示非英语语言

若要测试视觉对象，请将 Power BI 设置为非英语语言。本节介绍了如何更改 Power BI Desktop 和 Power BI 服务的设置，使其使用非英语的本地语言。

Power BI Desktop - 从 https://powerbi.microsoft.com 下载 Power BI Desktop 的本地化版本
Power BI 服务 - 如果你使用的是 Power BI 服务（Web 门户），则在设置中更改语言：
1. 登录到 PowerBI.com。
2. 导航到“设置”>“设置”>“设置”。
3. 从“常规”选项卡中选择“语言”。在“语言设置”中，选择要让 Power BI 使用的语言，然后选择“应用”。

步骤 2 - 获取区域设置 Power BI 语言

在视觉对象初始化过程中，本地 Power BI 语言作为 locale 字符串进行传递。如果在 Power BI 中更改了区域设置语言，将使用新的语言再次生成视觉对象。

private locale: string;
...
this.locale = options.host.locale;

注意

在 Power BI Desktop 中，locale 属性包含已安装的 Power BI Desktop 的语言。

步骤 3 - 设置视觉对象显示名称

每个视觉对象都会在属性窗格中显示信息。例如，使用 pbiviz new 命令创建的未本地化的自定义视觉对象，将在属性窗格中显示“类别数据”和“度量值数据”字段。

A screenshot showing the category data and measure data fields in a newly created Power BI visual.

属性窗格显示字段是在 capabilities.json 文件中定义的。每个显示字段都是使用 displayName 属性进行定义的。将 displayNameKey 添加到你要本地化的每个显示名称中。

{
    "dataRoles": [
        {
            "displayName": "Category Data",
            "displayNameKey": "VisualCategoryDataNameKey1",
            "name": "category",
            "kind": "Grouping"
        },
        {
            "displayName": "Measure Data",
            "displayNameKey": "VisualMeasureDataNameKey2",
            "name": "measure",
            "kind": "Measure"
        }
    ]
}

步骤 4 - 创建语言文件夹

要创建本地化视觉对象，你的项目需要有一个语言文件夹。在项目中，创建一个名为“stringResources”的文件夹。此文件夹将针对你希望视觉对象支持的每个本地语言包含一个子文件夹。例如，若要支持阿拉伯语和希伯来语，请按以下方式添加两个文件夹：

A VS code screenshot of a visual project folder.The string resources folder has two sub folders, one for Arabic and one for Hebrew.

步骤 5 - 为每种语言添加一个资源文件

对于你希望视觉对象支持的每种语言，请在相应的 stringResources 子文件夹中添加 resources.resjson JSON 文件。这些文件包含区域设置语言信息，以及你要替换的每个 displayNameKey 的本地化字符串值。

A VS code screenshot of a visual project folder. Each sub-folder in the string resources folder has a resources dot resjson file.

每个 JSON 文件都定义了一个受支持的区域设置语言。在每个 resources.resjson 文件中添加你将要使用的所有本地化字符串。

示例

其中每个 displayNameKey 都有俄语字符串的 resources.resjson 文件。

{
    ...
    "Role_Legend": "Обозначения",
    "Role_task": "Задача",
    "Role_StartDate": "Дата начала",
    "Role_Duration": "Длительность"
    ...
}

其中每个 displayNameKey 都有希伯来语字符串的 resources.resjson 文件。

{
    ...
    "Role_Legend": "מקרא",
    "Role_task": "משימה",
    "Role_StartDate": "תאריך התחלה",
    "Role_Duration": "משך זמן"
    ...
}

步骤 6 - 创建新的 localizationManager 实例

在视觉对象的代码中创建新的 localizationManager 实例。

private localizationManager: ILocalizationManager;

constructor(options: VisualConstructorOptions) {
    this.localizationManager = options.host.createLocalizationManager();
}

步骤 7 - 调用 getDisplayName 函数

创建新的 localizationManager 实例后，可以使用在 resources.resjson 中定义的字符串键参数来调用本地化管理器的 getDisplayName 函数。

例如，对于 en-US，以下代码将返回“Legend”，对于 ru-RU，以下代码将返回“Обозначения”。

let legend: string = this.localization.getDisplayName("Role_Legend");

格式窗格和分析窗格本地化

注意

与 API 版本 5.1+ 相关

若要支持格式窗格和分析窗格组件的本地化，请将本地化字符串设置为以下内容：

displayName: this.localization.getDisplayName("Font_Color_DisplayNameKey");
description: this.localization.getDisplayName("Font_Color_DescriptionKey");

有关本地化格式设置模型，请参阅格式窗格本地化。
有关本地化格式设置模型 utils，请参阅格式设置模型 utils - 本地化。

支持的语言

下表包含 Power BI 中支持的所有语言的列表，以及 locale 变量为每个语言返回的字符串。

区域设置字符串	语言
ar-SA	العربية（阿拉伯语）
bg-BG	български（保加利亚语）
ca-ES	català（加泰罗尼亚语）
cs-CZ	čeština（捷克语）
da-DK	dansk（丹麦语）
de-DE	Deutsche（德语）
el-GR	ελληνικά（希腊语）
en-US	English（英语）
es-ES	español 服务（西班牙语）
et-EE	eesti（爱沙尼亚语）
eU-ES	Euskal（巴斯克语）
fi-FI	suomi（芬兰语）
fr-FR	français（法语）
gl-ES	galego（加利西亚语）
he-IL	עברית（希伯来语）
hi-IN	हिन्दी（印地语）
hr-HR	hrvatski（克罗地亚语）
hu-HU	magyar（匈牙利语）
id-ID	Bahasa Indonesia（印度尼西亚语）
it-IT	italiano（意大利语）
ja-JP	日本の（日语）
kk-KZ	Қазақ（哈萨克语）
ko-KR	한국의（韩语）
lt-LT	Lietuvos（立陶宛语）
lv-LV	Latvijas（拉脱维亚语）
ms-MY	Bahasa Melayu（马来语）
nb-NO	norsk（挪威语）
nl-NL	Nederlands（荷兰语）
pl-PL	polski（波兰语）
pt-BR	português（葡萄牙语）
pt-PT	português（葡萄牙语）
ro-RO	românesc（罗马尼亚语）
ru-RU	русский（俄语）
sk-SK	slovenský（斯洛伐克语）
sl-SI	slovenski（斯洛文尼亚语）
sr-Cyrl-RS	српски（塞尔维亚语）
sr-Latn-RS	srpski（塞尔维亚语）
sv-SE	svenska（瑞典语）
th-TH	ไทย（泰语）
tr-TR	Türk（土耳其语）
uk-UA	український（乌克兰语）
vi-VN	t Việt（越南语）
zh-CN	中国（简体中文）
zh-TW	中國（繁体中文）

后续步骤

格式化 utils

是否有任何问题? 在 Power BI 社区提问

通过