User Guide Getting Started Help Center Documentation Community Training
Looker
Localizing Labels and Descriptions

New in Looker 6.2, you can localize labels, group labels, and descriptions in your model.

Localization is a Looker beta feature.

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.

This page describes the steps for localizing your project:

Adding Labels and Descriptions to Your View Files

You can localize the labels, group labels, and descriptions in your project. Localization is not supported for LookML dashboards, so neither reference line labels nor dashboard descriptions can be localized.

Here is an example view file with some labels and descriptions:

view: flights { label: "flight_info" sql_table_name: flightstats.accidents ;; dimension: id { label: "id" primary_key: yes type: number sql: ${TABLE}.id ;; } dimension: air_carrier { label: "airline" type: string sql: ${TABLE}.air_carrier ;; } 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 ;; }

We’ll localize these values in the following section 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.

Create a .strings file for each locale you want for your project.

There must be 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. Each string must be defined in the default locale strings file or it won’t be localized.

Here’s an example en.strings file that will be utilized for all users with the Locale value of “en”. In this example, “en” is also specified as our default locale, so all strings must be defined in this file in order to be localized.

"flight_info" = "Flights"; "id" = "Identifier"; "airline" = "Air Carrier"; "country_of_departure" = "Country of Departure"; "number_engines" = "Number of Engines";

This is what an “en” user would see in Looker:

Note the following:

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

"flight_info" = "Vuelos"; "id" = "Identificador"; "airline" = "Aerolínea"; "country" = "País"; "country_of_departure" = "País de Partida"; "number_engines" = "Número de Motores";

This is what an “espanol” user would see in Looker:

Note the following:

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. If your project doesn’t already have a manifest file, you can create one:

  1. Verify that Development Mode is set to ON.
  2. In the IDE, click the + icon next to Add Files.
  3. Select Create Project Manifest.

This will add a new file called manifest.lkml to the sidebar.

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 it is not defined in the default locale strings file then the Looker UI will display the unlocalized string. See this section above for more information on setting up locale strings files.

The default locale for your project is not to be confused with the default locale for Looker users. For the Locale user setting, Looker has an instance-wide default setting of “en”. If a Looker admin does not explicitly assign a user a Locale value, Looker automatically 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 of your Looker users, you should set your project’s default_locale to en and define the localization for all of your labels and descriptions in the en.strings file.

localization_level

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

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 of 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. For example, if you want a user to see the labels and descriptions defined in the espanol.strings file, your Looker admin should set the user’s Locale setting to “espanol”:

The user’s Locale setting is saved as a user attribute:

For all Looker instances, “en” is the default value for the Locale user setting. This means that if your admin does not specifically enter a Locale value for a user, Looker assigns the user to the “en” locale. For this reason, you might want to also set your project’s default_locale to en to ensure that you have an en.strings file to define localization for any users whose Locale value is not specified.

Setting Locale for SSO Embed Users

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

Using Locale in Liquid Variables

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

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

"domestic" = "Domestic"; "international" = "International";

And then in our espanol.strings 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;; }

Now, here is what our users with the “en” locale see:

And here is what our users with the “espanol” locale see:

Top