本地化 LookML 模型

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

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

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

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

模型本地化通常由管理员完成,管理员需要指定数字格式本地化界面语言设置。

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

您可以本地化模型中的标签、分组标签和说明,包括:

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

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

在以下示例 LookML 中,为 flights 视图以及 idcountrynumber_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 的文件。每个字符串都必须在 default 语言区域字符串文件中定义,否则将无法本地化。

en.strings.json 文件示例将用于所有语言区域值为 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 文件,供所有语言区域值为 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”(位置)。
  • 我们没有针对“country”定义本地化内容标签,这也是默认的语言区域字符串文件。en.strings.json因此,虽然我们定义了“country”,,Looker 不会本地化此字符串,而是按照视图文件中定义的标签“country”显示标签。es_ES.strings.json

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

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

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

localization_settings: {
  default_locale: en
  localization_level: permissive
}

default_locale

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

默认的语言区域字符串文件决定了模型中的哪些字符串已本地化。即使在其他语言区域字符串文件中定义了标签或说明字符串,如果未在默认语言区域字符串文件中定义,Looker 界面将显示未本地化的字符串。

请不要将项目的默认语言区域与 Looker 用户的默认语言区域混淆。Looker 管理员可以为您的实例设置默认语言区域。如果未设置默认值,Looker 将默认为 en。如果您的管理员未为用户或用户所属的用户群组明确输入语言区域值,Looker 会将用户分配到默认实例语言区域。如果管理员未设置默认实例语言区域,Looker 会将用户分配到 en 语言区域。

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

localization_level

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

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

即使您确实需要 strict 本地化级别,在开发项目时将项目的本地化级别设为 permissive 也非常有用,这样可以防止出现验证错误。本地化完所有标签和说明后,您可以将本地化级别设置为 strict,以便查看任何错误。

将用户分配到语言区域

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

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

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

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

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

在 Liquid 变量中使用语言区域

如前所述,通过模型本地化,您可以针对不同语言区域自定义模型标签和说明的显示。不过,您也可以在 Liquid 变量中添加本地化键,以便本地化数据值。

例如,在我们的名为 en.strings.json 的默认语言区域字符串文件中,我们可以创建包含以下条目的本地化键 domesticinternational

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

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

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

然后,我们可以在 Liquid 变量中使用 domesticinternational 本地化键来本地化维度的输出:

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

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

请注意,当您扩展视图、探索或 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,那么在定义新标签或说明之前,我们将无法提交任何更新。