Localizing your LookML model

With model localization, you can customize how your model's labels and descriptions display according to a user's locale.

Localization doesn't have to be based on geographic location or language. You can use locales to represent other distinguishing factors, such as internal versus external users, or managers versus individual contributors, and customize your labels and descriptions accordingly.

Note: Model localization is not compatible with project import.

This page describes the steps for localizing your project:

1. Determine which elements will be localized by adding labels, group labels, and descriptions to your model.
2. Provide the localization definitions for your project by creating locale strings files.
3. Enable localization for your project by adding localization settings to the project's manifest file.
4. Determine the display for different users by assigning users to locales.

Model localization often occurs in conjunction with an admin who specifies number format localization and user-interface language settings.

Localizing labels and descriptions in your model

You can localize labels, group labels, and descriptions in your model, including the following:

• label for field, model, Explore, or view
• label for applications in the Looker extension framework
• group_label for Explore and group_label for field
• group_item_label for field
• description for Explore and description for field
• Timeframes, intervals, and custom timeframes generated by dimension_group parameters (for more information, see the Localizing dimension groups section on this page)

You can also create localized LookML dashboards in your project. The following LookML dashboard parameters can be localized:

• title
• description
• text (which is a subparameter of the note parameter and can be applied to all dashboard element types, besides elements of type: text)
• comparison_label
• single_value_title

To see all fields in your project that can be localized, you can set your project's localization level to strict. With this setting, the Looker IDE returns a LookML validation error for any LookML elements that can be localized but that don't have labels, and for any strings in your LookML model that can be localized but that aren't defined in your locale strings files.

In the following sample LookML, labels are provided for the flights view and the id, country, and number_of_engines fields. A description is also provided for the country field.

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 ;;
  }
}

In the examples that follow on this page, we'll localize these values in the strings files using a permissive localization level. Notice that the location dimension does not have a label, so we can demonstrate how a dimension with no localization is displayed.

Creating locale strings files

The locale strings files use key-value pairs to define how the labels and descriptions in your model are displayed for each locale. On the left side of each key-value pair is the localization key, which is a label or description string from your model. The right side of the key-value pair is where you define how you want that string to be displayed in the Looker UI.

For each locale that you want to use for your project, you need to create a dedicated strings file. Create only one strings file for each locale. You must have a strings file that is named to match the default locale. For example, if you have specified default_locale: en in your project's manifest file, you must have a file in your model called en.strings.json. Each string must be defined in the default locale strings file or it won't be localized.

Tip: Model localization doesn't have to be based on geographic location or language. However, if you are using model localization and you also want to use Looker's natively localized dashboard and visualization user interface, you must match the title of the strings file with Looker's supported locale codes.

This example of an en.strings.json file will be utilized for all users who have the Locale value of en. In the following sample LookML, en is also specified as the default locale, so all strings must be defined in this file in order to be localized.

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

The following table shows what a user with their locale set to en would see in the data table of a Looker Explore:

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

Note the following:

• In the flights view sample LookML that's shown earlier on this page, no label was provided for the location dimension, so Looker capitalizes the dimension's name and displays it as "Location".
• Localization for the "country" label wasn't defined in the en.strings.json file, so Looker displays the label as it is defined in the view file, without capitalizing it: "country".

As another example, we can create an es_ES.strings.json file that is utilized for all users with a Locale value of es_ES:

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

The following table shows what a user with their locale set to es_ES would see in 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

Note the following:

• As in the previous example, in the original view with labels and descriptions added, no label was provided for the location dimension, so Looker capitalizes and displays the dimension's name as "Location".
• Localization was not defined for the "country" label in the en.strings.json file, which is the default locale strings file. This means that, even though "country" was defined in the es_ES.strings.json file, Looker doesn't localize this string and displays the label as it's defined in the view file: "country".

Adding localization settings to your project's manifest file

To enable localization for your project, add the localization_settings parameter to your project's manifest file.

Tip: If your project doesn't already have one, you can create a manifest file from the + icon at the top of the file browser in the Looker IDE.

In the manifest file, add your localization settings. Here's an example:

localization_settings: {
  default_locale: en
  localization_level: permissive
}

default_locale

The default_locale parameter specifies the name of the default locale strings file in your project.

The default locale strings file determines which strings from your model are localized. Even if a label or description string is defined in another locale strings file, if isn't defined in the default locale strings file, then the Looker UI displays the unlocalized string.

Don't confuse the default locale for your project with the default locale for Looker users. Your Looker admin can set a default locale for your instance. If no default is set, Looker defaults to en. If your admin doesn't specifically enter a Locale value for a user or a user group that the user belongs to, Looker assigns the user to the default instance locale. And, if the admin hasn't set a default instance locale, Looker assigns the user to the en locale.

For this reason, unless you are sure your Looker admin will be setting the Locale value for all your Looker users, you should set your project's default_locale parameter to the default locale for your instance (or to en if no default has been set), and define the localization for all your labels and descriptions in the .strings.json file for that locale.

localization_level

The localization level of your project specifies whether unlocalized elements are allowed in your model:

• Set the localization level to strict to require localized labels for all models, Explores, views, and fields in your project. The Looker IDE returns a LookML validation error for any of these elements that don't have labels as well as for any labels and descriptions that aren't defined in the default locale strings file.
• Set the localization level to permissive to allow elements without labels, and to allow labels and descriptions that aren't defined in the default localization strings file.

Even if you do want the strict localization level, it may be handy to set your project's localization level to permissive when you're developing your project to prevent validation errors. Once you've finished localizing all your labels and descriptions, you can set the localization level to strict to see any errors.

Assigning users to a locale

Once you have your locale strings files set up, you can assign users to a locale that corresponds to one of the locale strings files. This can be done at the instance, user group, or individual user level, using the Locale field or locale user attribute.

For example, if you want a user to see the labels and descriptions that are defined in the es_ES.strings.json file, your Looker admin should set the user's Locale setting to es_ES.

Custom locales you create with string files can be entered in the Locale field by clicking the field and typing the string filename rather than selecting a built-in locale from the drop-down menu. For more information, see the Users documentation page.

Note: When a locale isn't set for users at the individual or user group level, Looker assigns users to the instance locale. However, if there is no .strings file set up for the instance locale, model localization won't work for those users. For that reason, a .strings file should be set up for each instance's default locale. You can learn more about locales in the default_locale section or see Creating locale strings files.

Setting locale for signed embed users

You can include a user's locale value in a signed embed URL just like any other user attribute. The exact format required for signed embeds depends on the programming language that is used to build your signed embed URL script, but the name of the user attribute is locale. See the Signed embedding documentation page for more information on signed embed URLs and tools for building your signed embed URL.

Localizing dimension groups

You can use model localization with the dimension_group parameter. This feature lets LookML developers provide custom translations for the following:

• The timeframes of type: time dimension groups (such as month, year, or standard timeframe options)
• The intervals of type: duration dimension groups (such as months, years, or standard interval options)
• Custom timeframes of type: custom_calendar dimension groups (such as custom_period or custom_year). See Localizing custom calendar dimension groups.

Localizing dimension groups is particularly useful for providing custom, accurate names for fields that are generated by custom calendar dimension groups (for example, renaming a default field to "Sales Period").

To translate or rename timeframe and interval values that are generated by a dimension group, add the timeframe, interval, or custom timeframe string as a key in your locale strings files (such as en.strings.json and es_ES.strings.json) and provide the translated display value.

Here is the LookML for an example dimension group:

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

Here is an example en.strings.json locale strings file that provides a key-value pair translation for year:

{
  "year": "translated year",
}

In the Explore field picker, the dimension group is displayed like this:

Created Date
  Date
  Month
  Time
  translated year
  Week

Note: Translated strings also appear in the filter dropdowns in the Explore. However, Explore filters don't pluralize translated timeframes. For example, if you filter on the year timeframe that is localized to translated year, the filter drop-down will always display translated year, such as a filter for is in the last [number] translated year.

Localizing custom calendar dimension groups

For dimension groups of type: custom_calendar, you must add the custom timeframe (such as custom_date and custom_year) as a key in your locale strings files and provide the translated display value.

Here is the LookML for an example custom calendar dimension group:

  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
  }

Here is an example en.strings.json locale strings file that provides key-value pair translations for period and custom_week:

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

In the Explore picker, the custom calendar dimension group is displayed like this:

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

Note the following about how Looker displays the custom calendar dimension group in the Explore picker:

• Because the en.strings.json locale strings file specifies a translation for custom_week, the dimension group's custom_week timeframe uses the translation value (translated custom week) instead of the default (Fiscal Week).
• The en.strings.json locale strings file provides a translation for period but not custom_period, so the custom_period timeframe of the custom dimension group is not translated and is displayed using the default label (Fiscal Period). In order for Looker to translate the custom_period timeframe, the strings file must have a key-value pair translation specifically for custom_period.
• The rest of the custom dimension group timeframes are not translated. Instead they are prepended with Fiscal, as described in Labels for custom calendar dimension groups.

Using locale in Liquid variables

As described previously, model localization lets you customize the display of your model's labels and descriptions for different locales. But you can also include localization keys in Liquid variables, which lets you localize your data values as well.

For example, in our default locale strings file named en.strings.json, we can create the localization keys domestic and international with the following entries:

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

And then in our es_ES.strings.json file, we can provide Spanish versions of these localization keys:

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

From there, we can use the domestic and international localization keys in Liquid variables to localize the output of a dimension:

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

Users with the en locale will see the following results:

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

Users with the es_ES locale will see the following results:

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

The users with the es_ES locale see the "Domestic" and "International" data localized to "Nacional" and "Internacional", respectively.

You can also use Liquid in LookML dashboard filters and LookML dashboard element filters to localize the default value in a filter. For example, if a LookML dashboard has a tile using data from this localized model, and there is a filter on that tile defined in LookML as follows:

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

When a user with the en locale explores from that tile on the dashboard, the Explore will be filtered on the value Domestic for the Flights From the US? field, and the data table in the Explore will include the following results:

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

When a user with the es_ES locale explores from that tile on the dashboard, the Explore be filtered on the value Nacional for the Vuelos ¿De Los Estados Unidos? field, and the data table in the Explore will include the following results:

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

Understanding how localization rules apply to extended and refined objects

Be aware that localization rules apply when you are extending views, Explores, or LookML dashboards, and when you are refining views or Explores.

If you have extended or refined an object and then added new labels or descriptions, you should provide localization definitions in the locale strings files.

For example, if we have a flights view:

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

And then we create a new view that extends the flights view:

include: "/views/flights.view"

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

In our locale strings files we would need to define both of the view label strings ("flight_info" and "enhanced_flight_info"). If the project's localization level is set to strict, we wouldn't be able to commit any updates until we defined the new labels or descriptions.