本地化 LookML 模型

借助模型本地化，您可以根据用户的语言区域自定义模型的标签和说明的显示方式。

本地化不一定基于地理位置或语言。您可以使用语言区域来表示其他区分因素，例如内部用户与外部用户，或经理与个人贡献者，并相应地自定义标签和说明。

注意： 您可以在导入其他项目的项目中使用模型本地化。如需了解详情，请参阅模型本地化和项目导入部分。

本页介绍了本地化项目的步骤：

1. 通过向模型添加标签、组标签和说明，确定要本地化的元素。
2. 通过创建语言区域字符串文件，为项目提供本地化定义。
3. 通过向项目的清单文件添加本地化设置，为项目启用本地化。
4. 通过将用户分配给语言区域，确定不同用户的显示方式。

模型本地化通常与指定数字格式本地化和界面语言设置的管理员一起进行。

本地化模型中的标签和说明

您可以本地化模型中的标签、组标签和说明，包括以下内容：

• label 字段、模型、探索或视图的
• label Looker 扩展程序框架中应用的
• group_label 探索的 和 group_label 字段的
• group_item_label 字段的
• description 探索的 和 description 字段的
• dimension_group 参数生成的时间范围、间隔和自定义时间范围（如需了解详情，请参阅本页的本地化维度组部分）

您还可以在项目中创建本地化的 LookML 信息中心。以下 LookML 信息中心参数可以本地化：

• title
• description
• text（它是 note 参数的子参数，可以应用于所有信息中心元素类型，但 type: text 元素除外）
• comparison_label
• single_value_title

如需查看项目中可以本地化的所有字段，您可以将项目的 本地化级别 设置为 strict。使用此设置后，对于任何可以本地化但没有标签的 LookML 元素，以及 LookML 模型中任何可以本地化但未在语言区域字符串文件中定义的字符串，Looker IDE 都会返回 LookML 验证错误。

在以下示例 LookML 中，为 flights 视图以及 id、country 和 number_of_engines 字段提供了标签。此外，还为 country 字段提供了说明。

view: flights {
  label: "flight_info"
  sql_table_name: flightstats.accidents ;;

  dimension: id {
    label: "id"
    primary_key: yes
    type: number
    sql: ${TABLE}.id ;;
  }

  dimension: country {
    label: "country"
    description: "country_of_departure"
    type: string
    map_layer_name: countries
    sql: ${TABLE}.country ;;
  }

  dimension: number_of_engines {
    label: "number_of_engines"
    type: string
    sql: ${TABLE}.number_of_engines ;;
  }

  dimension: location {
    type: string
    sql: ${TABLE}.location ;;
  }
}

在本页的后续示例中，我们将使用 permissive 本地化级别在字符串文件中本地化这些值。请注意，location 维度没有标签，因此我们可以演示如何显示没有本地化的维度。

创建语言区域字符串文件

语言区域字符串文件使用键值对来定义模型中标签和说明在每个语言区域中的显示方式。每个键值对的左侧是本地化键，即模型中的标签或说明字符串。键值对的右侧用于定义您希望该字符串在 Looker 界面中的显示方式。

对于要用于项目的每个语言区域，您都需要创建一个专用的字符串文件。为每个语言区域仅创建一个字符串文件。您必须有一个字符串文件，其名称与默认语言区域匹配。例如，如果您在项目的清单文件中指定了 default_locale: en，则必须在模型中有一个名为 en.strings.json 的文件。每个字符串都必须在默认语言区域字符串文件中定义，否则不会本地化。

提示： 模型本地化不一定基于地理位置或语言。但是，如果您使用模型本地化，并且还想使用 Looker 原生本地化的信息中心和可视化图表界面，则必须将字符串文件的标题与 Looker 的支持的语言区域代码相匹配。

此 en.strings.json 文件示例将用于所有 Locale 值为 en 的用户。在以下示例 LookML 中，en 也被指定为默认语言区域，因此必须在此文件中定义所有字符串才能进行本地化。

{
  "flight_info": "Flights",
  "id": "Identifier",
  "country_of_departure": "Country of Departure",
  "number_engines": "Number of Engines"
}

下表显示了语言区域设置为 en 的用户在 Looker 探索的数据表中看到的内容：

Flights Identifier	Flights country	Flights Location	Flights Number of Engines
493	Congo	Kisangani, Congo	3
2167	Saudi Arabia	Riyadh, Saudi Arabia	3
2657	Austria	Vienna, Austria	2
17992	United States	Kansas City, MO	2
18893	United States	Anchorage, AK	4

请注意以下几点：

• 在本页前面显示的 flights 视图示例 LookML 中，未为 location 维度提供标签，因此 Looker 会将该维度的名称大写并显示为“Location”。
• 未在 en.strings.json 文件中定义“country”标签的本地化，因此 Looker 会按视图文件中的定义显示该标签，而不将其大写：“country”。

再举一个例子，我们可以创建一个 es_ES.strings.json 文件，该文件将用于所有 Locale 值为 es_ES 的用户：

{
  "flight_info": "Vuelos",
  "id": "Identificador",
  "country": "País",
  "country_of_departure": "País de Partida",
  "number_engines": "Número de Motores"
}

下表显示了语言区域设置为 es_ES 的用户在 Looker 中看到的内容：

Vuelos Identificador	Vuelos country	Vuelos Location	Vuelos Número de Motores
493	Congo	Kisangani, Congo	3
2167	Saudi Arabia	Riyadh, Saudi Arabia	3
2657	Austria	Vienna, Austria	2
17992	United States	Kansas City, MO	2
18893	United States	Anchorage, AK	4

请注意以下几点：

• 与上一个示例一样，在添加了标签和说明的旧版视图中，未为位置维度提供标签，因此 Looker 会将该维度的名称大写并显示为“Location”。
• 未在 en.strings.json 文件（即默认语言区域字符串文件）中为“国家/地区”标签定义本地化。这意味着，即使在 es_ES.strings.json 文件中定义了“country”，Looker 也不会本地化此字符串，而是按视图文件中的定义显示该标签：“country”。

向项目的清单文件添加本地化设置

如需为项目启用本地化，请将 localization_settings 参数添加到项目的清单文件中。

提示： 如果您的项目还没有清单文件，您可以创建一个清单文件，方法是点击 Looker IDE 中文件浏览器顶部的+图标。

在清单文件中，添加本地化设置。示例如下：

localization_settings: {
  default_locale: en
  localization_level: permissive
}

default_locale

default_locale 参数用于指定项目中默认语言区域字符串文件的名称。

默认语言区域字符串文件用于确定模型中要本地化的字符串。即使在另一个语言区域字符串文件中定义了标签或说明字符串，如果未在默认语言区域字符串文件中定义，Looker 界面也会显示未本地化的字符串。

请勿将项目的默认语言区域与 Looker 用户的默认语言区域混淆。您的 Looker 管理员可以设置默认语言区域为您的实例。如果未设置默认语言区域，Looker 会默认使用 en。如果管理员未专门为用户或用户所属的用户组输入 Locale 值，Looker 会将用户分配给默认实例语言区域。并且，如果管理员未设置默认实例语言区域，Looker 会将用户分配给 en 语言区域。

因此，除非您确定 Looker 管理员会为所有 Looker 用户设置 Locale 值，否则您应将项目的 default_locale 参数设置为实例的默认语言区域（如果未设置默认语言区域，则设置为 en），并在该语言区域的 .strings.json 文件中定义所有标签和说明的本地化。

localization_level

项目的本地化级别用于指定是否允许模型中存在未本地化的元素：

• 将本地化级别设置为 strict，以要求项目中所有模型、探索、视图和字段都使用本地化的标签。对于任何没有标签的此类元素，以及任何未在默认语言区域字符串文件中定义的标签和说明，Looker IDE 都会返回 LookML 验证错误。
• 将本地化级别设置为 permissive，以允许元素没有标签，并允许标签和说明未在默认本地化字符串文件中定义。

即使您确实需要 strict 本地化级别，在开发项目时将项目的本地化级别设置为 permissive 也有助于防止验证错误。完成所有标签和说明的本地化后，您可以将本地化级别设置为 strict 以查看任何错误。

将用户分配给语言区域

设置好语言区域字符串文件后，您可以将用户分配给与其中一个语言区域字符串文件对应的语言区域。您可以使用 Locale 字段或 locale 用户属性在 实例、用户组 或 单个用户 级别执行此操作。

例如，如果您希望用户看到在 es_ES.strings.json 文件中定义的标签和说明，Looker 管理员应将用户的 Locale 设置为 es_ES。

您可以使用字符串文件创建自定义语言区域，方法是点击 Locale 字段并输入字符串文件名，而不是从下拉菜单中选择内置语言区域。如需了解详情，请参阅用户文档页面。

注意 ：如果未在单个用户或用户组级别为用户设置语言区域，Looker 会将用户分配给实例语言区域。但是，如果未为实例语言区域设置 .strings 文件，模型本地化将不适用于这些用户。因此，应为每个实例的默认语言区域设置 .strings 文件。您可以在default_locale部分详细了解语言区域，或查看创建语言区域字符串文件。

为已签名的嵌入用户设置语言区域

您可以像任何其他用户属性一样，在已签名的嵌入网址中添加用户的语言区域值。已签名的嵌入所需的具体格式取决于用于构建已签名的嵌入网址脚本的编程语言，但用户属性的名称为 locale。如需详细了解已签名的嵌入网址以及用于构建已签名的嵌入网址的工具，请参阅已签名的嵌入文档页面。

本地化维度组

您可以将模型本地化与 dimension_group 参数搭配使用。借助此功能，LookML 开发者可以为以下内容提供自定义翻译：

• type: time 维度组的时间范围（例如 month、year 或标准时间范围选项）
• type: duration 维度组的间隔（例如 months、years 或标准间隔选项）
• type: custom_calendar 维度组的自定义时间范围（例如 custom_period 或 custom_year）。请参阅本地化自定义日历维度组。

本地化维度组对于为自定义日历维度组生成的字段提供自定义的准确名称（例如，将默认字段重命名为“Sales Period”）特别有用。

如需翻译或重命名维度组生成的时间范围和间隔值，请将时间范围、间隔或自定义时间范围字符串作为键添加到语言区域字符串文件（例如 en.strings.json 和 es_ES.strings.json），并提供翻译后的显示值。

以下是示例维度组的 LookML：

  dimension_group: created {
    type: time
    timeframes: [time, date, week, month, year]
    sql: ${TABLE}.created_at ;;
  }

以下是示例 en.strings.json 语言区域字符串文件，其中为 year 提供了键值对翻译：

{
  "year": "translated year",
}

在“探索”字段选择器中，维度组的显示方式如下：

Created Date
  Date
  Month
  Time
  translated year
  Week

注意： 翻译后的字符串也会显示在“探索”中的过滤条件下拉列表中。但是，“探索”过滤条件不会将翻译后的时间范围复数化。例如，如果您按本地化为翻译后的年份 的 year 时间范围进行过滤，过滤条件下拉列表将始终显示翻译后的年份 ，例如在过去 [数字] 翻译后的年份 的过滤条件。

本地化自定义日历维度组

对于 type: custom_calendar 的维度组，您必须将自定义时间范围（例如 custom_date 和 custom_year）作为键添加到语言区域字符串文件，并提供翻译后的显示值。

以下是示例自定义日历维度组的 LookML：

  dimension_group: cust_created_localized {
    type: custom_calendar
    custom_timeframes: [custom_date, custom_week, custom_period, custom_year]
    sql: ${TABLE}.created_at ;;
    based_on_calendar: retail_custom_calendar_v2
  }

以下是示例 en.strings.json 语言区域字符串文件，其中为 period 和 custom_week 提供了键值对翻译：

{
  "period": "translated period",
  "custom_week": "translated custom week"
}

在“探索”选择器中，自定义日历维度组的显示方式如下：

Cust Created Localized
  Fiscal Date
  Fiscal Period
  Fiscal Year
  translated custom week

请注意以下有关 Looker 在“探索”选择器中显示自定义日历维度组的方式：

• 由于 en.strings.json 语言区域字符串文件为 custom_week 指定了翻译，因此维度组的 custom_week 时间范围使用翻译值（翻译后的自定义周 ）而不是默认值（会计周 ）。
• en.strings.json 语言区域字符串文件为 period 提供了翻译，但未为 custom_period 提供翻译，因此自定义维度组的 custom_period 时段未翻译，而是使用默认标签（会计期间）显示。为了让 Looker 翻译 custom_period 时间范围，字符串文件必须具有专门针对 custom_period 的键值对翻译。
• 其余的自定义维度组时间范围未翻译。而是以会计 为前缀，如自定义日历维度组的标签中所述。

在 Liquid 变量中使用语言区域

如前所述，借助模型本地化，您可以自定义模型标签和说明在不同语言区域中的显示方式。但您也可以在 Liquid 变量中添加本地化键，这样您也可以本地化数据值。

例如，在名为 en.strings.json 的默认语言区域字符串文件中，我们可以使用以下条目创建本地化键 domestic 和 international：

{
  "domestic": "Domestic",
  "international": "International"
}

然后在 es_ES.strings.json 文件中，我们可以提供这些本地化键的西班牙语版本：

{
  "domestic": "Nacional",
  "international": "Internacional"
}

从这里开始，我们可以在 Liquid 变量中使用 domestic 和 international 本地化键来本地化维度的输出：

dimension: from_US {
    label: "from_us"
    type: string
    sql: CASE
         WHEN ${TABLE}.country = 'United States' THEN '{{ _localization['domestic'] }}'
         ELSE '{{ _localization['international'] }}'
         END;;
  }

语言区域为 en 的用户将看到以下结果：

Flights Identifier	Flights country	Flights From the US?
289	United States	Domestic
400	Canada	International
493	Congo	International
936	United States	Domestic

语言区域为 es_ES 的用户将看到以下结果：

Vuelos Identificador	Vuelos País	Vuelos ¿De Los Estados Unidos?
289	United States	Nacional
400	Canada	Internacional
493	Congo	Internacional
936	United States	Nacional

语言区域为 es_ES 的用户会看到本地化为“Nacional”和“Internacional”的“Domestic”和“International”数据。

您还可以在 LookML 信息中心过滤条件和 LookML 信息中心元素过滤条件中使用 Liquid，以本地化过滤条件中的默认值。例如，如果 LookML 信息中心有一个图块使用此本地化模型中的数据，并且该图块上有一个过滤条件在 LookML 中定义如下：

filters:
  flights.from_US: "{{ _localization['domestic'] }}"

当语言区域为 en 的用户从信息中心内的该图块进行探索时，“探索”将按 Flights From the US? 字段的值 Domestic 进行过滤，并且“探索”中的数据表将包含以下结果：

Flights Identifier	Flights country	Flights From the US?
289	United States	Domestic
936	United States	Domestic

当语言区域为 es_ES 的用户从信息中心内的该图块进行探索时，“探索”将按 Vuelos ¿De Los Estados Unidos? 字段的值 Nacional 进行过滤，并且“探索”中的数据表将包含以下结果：

Vuelos Identificador	Vuelos País	Vuelos ¿De Los Estados Unidos?
289	United States	Nacional
936	United States	Nacional

了解本地化规则如何应用于扩展和优化的对象

请注意，当您扩展视图、探索或 LookML 信息中心，以及当您优化视图或探索时，本地化规则适用。

如果您已扩展或优化对象，然后添加了新标签或说明，则应在语言区域字符串文件中提供本地化定义。

例如，如果我们有一个 flights 视图：

view: flights {
  label: "flight_info"
  sql_table_name: flightstats.accidents ;;
  ...
}

然后，我们创建一个新视图，用于扩展 flights 视图：

include: "/views/flights.view"

view: flights_enhanced {
  extends: [flights]
  label: "enhanced_flight_info"
}

在语言区域字符串文件中，我们需要定义两个视图标签字符串（"flight_info" 和 "enhanced_flight_info"）。如果项目的本地化级别设置为 strict，则在我们定义新标签或说明之前，我们将无法提交任何更新。

模型本地化和项目导入

预览版：在同一项目中使用项目导入和模型本地化功能受服务专用条款的“通用服务条款”部分中的“正式发布前产品条款”的约束。正式发布前产品和功能按“原样”提供，并且可能支持有限。如需了解详情，请参阅发布阶段说明。

如果您在 Looker 与分析模型互操作性的公开预览期间遇到问题，请向 [e-mail] 报告。

您可以在导入其他项目的项目中使用模型本地化。默认行为是，如果导入项目具有语言区域定义，Looker 将仅使用导入项目中的语言区域定义。但是，如果您想将导入项目的语言区域定义与导入项目的语言区域定义合并，可以在导入项目的清单 (manifest.lkml) 文件中向 localization_settings 参数添加 import_locale_defs: yes 语句：

project_name: "my_project"

localization_settings: {
  default_locale: en
  localization_level: permissive
  import_locale_defs: yes
}

当 import_locale_defs 设置为 yes 时，Looker 会合并每个项目中与每个语言区域对应的一个字符串文件。

重复键的优先规则

如果导入项目和导入项目中的不同字符串文件中定义了相同的键，Looker 在合并语言区域定义时会应用以下优先规则：

• 导入项目键优先 ：在导入项目的语言区域文件中定义的键始终会替换任何导入项目的语言区域文件中的重复键。
• 导入顺序决定优先级 ：如果重复键仅存在于导入项目的语言区域文件中，Looker 会根据项目在导入项目的清单文件中导入的顺序来解决冲突。在清单文件中稍后导入的项目中的键值定义优先于较早导入的项目中的键值定义。
• 使用导入项目设置 ：导入项目的本地化设置（例如 default_locale 和 localization_level）将应用于所有合并的文件，并替换在导入项目的清单文件中定义的任何本地化设置。