本地化 LookML 模型

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

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

注意： 模型本地化目前与项目导入不兼容。

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

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

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

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

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

• label，用于字段、模型、探索或查看
• Looker 扩展程序框架中label 的应用
• group_label 表示“探索”，group_label 表示“字段”
• 针对字段的 group_item_label
• description 表示“探索”，description 表示“字段”

提示： dimension_group 不支持本地化。请改用字段级 group_label 和 group_item_label 来创建可本地化的一组维度。

您还可以在项目中创建本地化的 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

请注意以下几点：

• 与上一个示例一样，在添加了标签和说明的原始视图中，我们根本没有为 location 维度提供标签，因此 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，以要求为项目中的所有模型、Explore、视图和字段提供本地化标签。如果上述任何元素没有标签，或者任何标签和说明未在默认语言区域字符串文件中定义，Looker IDE 都会返回 LookML 验证错误。
• 将本地化级别设置为 permissive，以允许使用没有标签的元素，并允许使用未在默认本地化字符串文件中定义的标签和说明。

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

将用户分配到相应语言区域

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

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

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

注意： 如果未在个人或用户群组级别为用户设置语言区域，Looker 会将用户分配到实例语言区域。不过，如果未为实例语言区域设置 .strings 文件，则模型本地化功能将无法为这些用户正常运行。因此，应为每个实例的默认语言区域设置一个 .strings 文件。如需了解详情，请参阅default_locale 部分或创建语言区域字符串文件部分。

为已登录的嵌入式用户设置语言区域

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

在 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”。

您还可以在 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

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

请注意，当您扩展视图、Explore 或 LookML 信息中心以及优化视图或 Explore 时，本地化规则会生效。

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

例如，如果我们有一个 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，那么在我们定义新标签或说明之前，将无法提交任何更新。