將 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 UI 中顯示該字串的方式。

如要為專案使用特定語言代碼，請為每個語言代碼建立專屬的字串檔案。每個語言代碼只能建立一個字串檔案。您必須擁有與預設語言代碼相符的字串檔案名稱。舉例來說，如果您在專案的資訊清單檔案中指定 default_locale: en，模型中就必須有名為 en.strings.json 的檔案。每個字串都必須在預設語言代碼字串檔案中定義，否則不會本地化。

提示： 模型本地化不一定要以地理位置或語言為依據。不過，如果您使用模型本地化功能，且想使用 Looker 原生本地化的資訊主頁和資料視覺化使用者介面，就必須將字串檔案的標題與 Looker 的支援的語言代碼相符。

如果使用者的「語言代碼」值為 en，系統就會使用這個 en.strings.json 檔案範例。在下列 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 檔案中定義「country」標籤的本地化，這是我們的預設語言代碼字串檔案。因此，即使我們確實在 es_ES.strings.json 檔案中定義了「country」，Looker 也不會將這個字串本地化，而是會顯示在檢視檔案中定義的標籤：「country」。

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

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

提示： 如果專案還沒有資訊清單檔案，您可以在 Looker IDE 的檔案瀏覽器頂端，按一下「+」圖示來建立資訊清單檔案。

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

localization_settings: {
  default_locale: en
  localization_level: permissive
}

default_locale

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

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

請勿將專案的預設語言代碼與 Looker 使用者的預設語言代碼混淆。Looker 管理員可以為執行個體設定預設語言代碼。如果未設定預設值，Looker 會預設為 en。如果管理員未為使用者或使用者群組輸入 Locale 值，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。

如要使用字串檔案建立自訂語言代碼，請點選「語言代碼」欄位，然後輸入字串檔案名稱，而非從下拉式選單選取內建語言代碼。詳情請參閱「使用者」說明文件頁面。

注意： 如果未在個別或使用者群組層級為使用者設定語言代碼，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

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

請注意，擴充檢視區塊、探索或 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，我們就無法提交任何更新，直到定義新的標籤或說明為止。