將 LookML 模型本地化

透過模型本地化功能，您可以根據使用者的語言代碼，自訂模型標籤和說明的顯示方式。

本地化不一定需要依據地理位置或語言。您可以使用語言代碼代表其他區隔因素，例如內部和外部使用者，或管理員和個別內容提供者，並據此自訂標籤和說明。

本頁面說明將專案本地化的步驟：

1. 在模型中新增標籤、群組標籤和說明，判斷要將哪些元素本地化。
2. 建立語言代碼字串檔案，為專案提供本地化定義。
3. 在專案的資訊清單檔案中新增本地化設定，為專案啟用本地化功能。
4. 將使用者指派給語言代碼，藉此決定不同使用者的顯示內容。

模型本地化通常會與管理員指定的數字格式本地化和使用者介面語言設定搭配使用。

在模型中將標籤和說明本地化

您可以在模型中本地化標籤、群組標籤和說明，包括：

• label (適用於欄位、模型、探索或檢視畫面)
• Looker 擴充功能架構中的 label 應用程式
• group_label 用於探索，group_label 用於欄位
• group_item_label 欄位
• description 用於探索，description 用於欄位

您也可以在專案中建立本地化的 LookML 資訊主頁。下列 LookML 資訊主頁參數可進行本地化：

• title
• description
• text (這是 note 參數的子參數，可套用至所有資訊主頁元素類型 (除了 type: text 的元素)。
• comparison_label
• single_value_title

如要查看專案中可進行本地化的所有欄位，您可以將專案的本地化層級設為 strict。在這個設定下，Looker IDE 會針對任何可進行本地化的 LookML 元素 (但沒有標籤)，以及 LookML 模型中可進行本地化但未在語言代碼字串檔案中定義的任何字串，傳回 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 UI 中的顯示方式。

針對您想在專案中使用的每個語言代碼，都必須建立專屬的字串檔案。請為每個語言代碼建立一個字串檔案。您必須有一個字串檔案，其名稱與預設語言代碼相符。舉例來說，如果您在專案的資訊清單檔案中指定 default_locale: en，則模型中必須有名為 en.strings.json 的檔案。每個字串都必須在預設語言代碼字串檔案中定義，否則無法進行本地化。

此範例的 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 Explore 的資料表中會看到的內容：

注意事項：

• 在先前顯示的 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 中看到的內容：

注意事項：

• 如同前述範例，在已加入標籤和說明的原始檢視畫面中，我們並未提供 location 維度的標籤，因此 Looker 會顯示維度的名稱 (大寫)：「Location」。
• 我們並未在 en.strings.json 檔案 (預設語言代碼字串檔案) 中定義「country」標籤的本地化項目。因此，即使我們在 es_ES.strings.json 檔案中已定義「country」，Looker 也不會將這個字串本地化，而是會根據我們在 View 檔案中定義的標籤顯示「country」。

在專案的資訊清單檔案中新增本地化設定

如要為專案啟用本地化功能，請在專案的資訊清單檔案中新增 localization_settings 參數。

在資訊清單檔案中新增本地化設定。範例如下：

localization_settings: {
  default_locale: en
  localization_level: permissive
}

default_locale

default_locale 參數會指定專案中預設語言代碼字串檔案的名稱。

預設語言代碼字串檔案會決定模型中哪些字串會本地化。即使標籤或說明字串是在其他語言代碼字串檔案中定義，如果未在預設語言代碼字串檔案中定義，Looker UI 就會顯示未經本地化的字串。

請勿將專案的預設語言代碼與 Looker 使用者的預設語言代碼混淆。Looker 管理員可以為執行個體設定預設語言代碼。如果未設定預設值，Looker 會預設為 en。如果管理員未為使用者或使用者所屬的使用者群組，特別輸入語言代碼值，Looker 會將使用者指派給預設的執行個體語言代碼。如果管理員未設定預設的例項語言代碼，Looker 會將使用者指派給 en 語言代碼。

因此，除非您確定 Looker 管理員會為所有 Looker 使用者設定語言代碼值，否則請將專案的 default_locale 參數設為執行個體的預設語言代碼 (如果尚未設定預設值，則設為 en)，並在該語言代碼的 .strings.json 檔案中定義所有標籤和說明的本地化設定。

localization_level

專案的本地化層級可指定模型是否允許未本地化的元素：

• 將本地化層級設為 strict，即可要求為專案中的所有模型、探索、檢視畫面和欄位提供本地化標籤。對於沒有標籤的元素，以及在預設語言代碼字串檔案中未定義的標籤和說明，Looker IDE 會傳回 LookML 驗證錯誤。
• 將本地化層級設為 permissive，即可允許元素不含標籤，並允許標籤和說明未在預設本地化字串檔案中定義。

即使您想要使用 strict 本地化層級，在開發專案時將專案的本地化層級設為 permissive 可能會很方便，這樣可以避免驗證錯誤。完成所有標籤和說明的本地化作業後，您可以將本地化層級設為 strict，查看是否有任何錯誤。

將使用者指派給語言代碼

設定完語言代碼字串檔案後，您可以將使用者指派給與其中一個語言代碼字串檔案相對應的語言代碼。您可以使用語言代碼欄位或 locale 使用者屬性，在執行個體、使用者群組或個別使用者層級執行這項操作。

舉例來說，如果您希望使用者看到 es_ES.strings.json 檔案中定義的標籤和說明，Looker 管理員應將使用者的語言代碼設定設為 es_ES。

您可以透過點選欄位並輸入字串檔案名稱，在「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 語言代碼的使用者會看到下列結果：

使用 es_ES 語言代碼的使用者會看到下列結果：

使用 es_ES 語言代碼的使用者會看到「國內」和「國際」資料分別對應至「Nacional」和「Internacional」。

您也可以在 LookML 資訊主頁篩選器和 LookML 資訊主頁元素篩選器中使用 Liquid，將篩選器中的預設值本地化。舉例來說，如果 LookML 資訊主頁含有使用此本地化模型資料的資訊方塊，且該資訊方塊在 LookML 中定義了篩選器，如下所示：

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

當使用者透過資訊主頁上的資訊方塊進行探索時，系統會根據 Flights From the US? 欄位的值 Domestic 篩選「探索」結果，而「探索」中的資料表會包含下列結果：en

當使用者透過資訊主頁上的資訊方塊進行探索時，系統會根據 Vuelos ¿De Los Estados Unidos? 欄位的值 Nacional 篩選「探索」功能，而「探索」中的資料表會包含下列結果：es_ES

瞭解本地化規則如何套用至擴充和精緻物件

請注意，當您擴充檢視畫面、探索或 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，則必須定義新的標籤或說明，才能提交任何更新。