Model localization often occurs in conjunction with number format localization and user-interface language selection. To learn more about those topics, visit the Localizing Number Formatting and Supported User-Interface Languages documentation pages.
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.
Model localization is not currently compatible with project import.
This page describes the steps for localizing your project:
- Determine which elements will be localized by adding labels, group labels, and descriptions to your model.
- Provide the localization definitions for your project by creating locale strings files.
- Enable localization for your project by adding localization settings to the project's manifest file.
- Determine the display for different users by assigning users to locales.
To learn more about localizing the Looker user interface or localizing number formatting, visit the Supported user-interface languages and Localizing number formatting documentation pages.
Using localized elements in your model files
You can localize labels, group labels, and descriptions in your model, including the following:
label
at the level of field, model, Explore, or viewlabel
for applications in the Looker extension frameworkgroup_label
at the level of Explore, fieldgroup_item_label
at the level of fielddescription
at the level of Explore, field
Localization is not supported for dimension_group
. Instead, use group_label
and group_item_label
to create your own set of dimensions that can be localized.
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 thenote
parameter and can be applied to all dashboard element types, besides elements oftype: 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.
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 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 you want for your project, create a dedicated strings file. You should create only one strings file for each locale in 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.json
. Each string must be defined in the default locale strings file or it won't be localized.
Model localization doesn't have to be based on geographic location or language. However, if you are using model localization and you would also like 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.
Here's an example en.strings.json
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:
- In the view file above we didn't provide a label at all for the
location
dimension, so Looker displays the dimension's name, capitalized: "Location". - We didn't define localization for the "country" label in our
en.strings.json
file, so Looker displays the label as it is defined in our 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",
"airline": "Aerolínea",
"country": "País",
"country_of_departure": "País de Partida",
"number_engines": "Número de Motores"
}
This is what an es_ES
user would see in Looker:
Note the following:
- As in the previous example, in the view file above we didn't provide a label at all for the
location
dimension, so Looker displays the dimension's name, capitalized: "Location". - We didn't define localization for the "country" label in our
en.strings.json
file, which is our default locale strings file. So even though we did define "country" in oures_ES.strings.json
file, Looker does not localize this string, and displays the label as it is defined in our 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.
If your project doesn't already have a manifest file, you can create one 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 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. Your Looker admin can set a default locale for your instance. If no default is set, Looker will default to en
. If your admin does not specifically enter a Locale value for a user or a user group the user belongs to, Looker assigns the user to the default instance locale. And, if the admin has not 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 will return a LookML validation error for any of these elements that don't have labels, and 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 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.
When a locale is not set for users at the individual or user group level, Looker will assign users to the instance locale. However, if there is no
.strings
file set up for the instance locale, model localization will not work for those users. For that reason, a.strings
file should be set up for each instance's default locale. You can learn more in thedefault_locale
or the Creating locale strings files sections.
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 the Single sign-on (SSO) embedding 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 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;;
}
Now, here is what our users with the en
locale see:
And here is what our users with the es_ES
locale see:
You can also use Liquid in dashboard and dashboard element filters to localize the default value in a filter. For example, if a LookML dashboard has a tile from the above Explore, and there is a filter on that tile defined like this:
filters:
flights.from_US: "{{ _localization['domestic'] }}"
Here is what users with the en
locale would see when they explore from that tile on the dashboard:
And here is what users with the es_ES
locale would see when they explore from that tile on the dashboard:
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.