Como localizar seu modelo do LookML

Com a localização de modelos, você pode personalizar a exibição dos rótulos e descrições do modelo de acordo com a localidade do usuário.

A localização não precisa ser baseada em localização geográfica ou idioma. É possível usar localidades para representar outros fatores distintivos, como usuários internos e externos, ou gerentes versus colaboradores individuais, e personalizar seus rótulos e descrições adequadamente.

Nesta página, descrevemos as etapas para localizar seu projeto:

  1. Determine quais elementos serão localizados adicionando rótulos, rótulos de grupo e descrições ao seu modelo.
  2. Forneça as definições de localização do seu projeto criando arquivos de strings de localidade.
  3. Ative a localização do seu projeto adicionando configurações de localização ao arquivo de manifesto do projeto.
  4. Atribua os usuários a localidades para determinar como eles serão exibidos.

A localização do modelo geralmente ocorre em conjunto com um administrador que especifica as configurações de localização do formato de número e idioma da interface do usuário.

Como localizar rótulos e descrições no seu modelo

É possível localizar rótulos, rótulos de grupo e descrições no seu modelo, incluindo:

Também é possível criar painéis do LookML localizados no seu projeto. Os seguintes parâmetros do painel do LookML podem ser localizados:

Para conferir todos os campos do projeto que podem ser localizados, defina o nível de localização do projeto como strict. Com essa configuração, o Looker IDE retorna um erro de validação do LookML para todos os elementos do LookML que podem ser localizados, mas não têm rótulos, e para todas as strings no modelo do LookML que podem ser localizadas, mas não são definidas nos arquivos de strings de localidade.

No LookML de amostra a seguir, são fornecidos rótulos para a visualização flights e os campos id, country e number_of_engines. Também é fornecida uma descrição para o campo 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 ;;
  }

Nos exemplos a seguir nesta página, vamos localizar esses valores nos arquivos de strings usando um nível de localização permissive. Observe que a dimensão location não tem um rótulo, então podemos demonstrar como uma dimensão sem localização é exibida.

Como criar arquivos de strings de localidade

Os arquivos de strings de localidade usam pares de chave-valor para definir como os rótulos e as descrições no modelo são mostrados para cada localidade. No lado esquerdo de cada par de chave-valor está a chave de localização, que é um rótulo ou uma string de descrição do seu modelo. No lado direito do par de chave-valor, você define como quer que essa string seja mostrada na interface do Looker.

Para cada localidade que você quer usar no projeto, é necessário criar um arquivo de strings dedicado. Crie apenas um arquivo de strings para cada localidade. Você precisa ter um arquivo de strings com um nome que corresponda à localidade padrão. Por exemplo, se você especificou default_locale: en no arquivo de manifesto do projeto, é necessário ter um arquivo no modelo chamado en.strings.json. Cada string precisa ser definida no arquivo de strings de localidade default ou não será localizada.

Este exemplo de um arquivo en.strings.json será usado para todos os usuários que tiverem o valor en de Locale. No exemplo do LookML a seguir, a en também é especificada como a localidade padrão, portanto, todas as strings precisam ser definidas nesse arquivo para serem localizadas.

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

A tabela a seguir mostra o que um usuário com a localidade definida como en veria na tabela de dados de uma análise detalhada do 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

Observe o seguinte:

  • No LookML de amostra da visualização flights mostrado anteriormente, não fornecemos um rótulo para a dimensão location. Por isso, o Looker exibe o nome da dimensão, em letras maiúsculas: "Location".
  • Não definimos a localização para o rótulo "country" no arquivo en.strings.json. Por isso, o Looker exibe o rótulo conforme definido no arquivo de visualização, sem maiúsculas: "country".

Como outro exemplo, podemos criar um arquivo es_ES.strings.json que é usado para todos os usuários com um valor Locale de es_ES:

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

A tabela a seguir mostra o que um usuário com a localidade definida como es_ES veria no 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

Observe o seguinte:

  • Como no exemplo anterior, na visualização original com rótulos e descrições adicionados, não fornecemos um rótulo para a dimensão location. Por isso, o Looker mostra o nome da dimensão, em maiúsculas: "Local".
  • Não definimos a localização do "país" no arquivo en.strings.json, que é o arquivo de strings de localidade padrão. Portanto, mesmo que temos definido "country" no arquivo es_ES.strings.json, o Looker não localiza essa string e exibe o rótulo conforme definido no arquivo de visualização: "country".

Como adicionar configurações de localização ao arquivo de manifesto do seu projeto

Para ativar a localização do seu projeto, adicione o parâmetro localization_settings ao arquivo de manifesto dele.

No arquivo de manifesto, adicione as configurações de localização. Veja um exemplo:

localization_settings: {
  default_locale: en
  localization_level: permissive
}

default_locale

O parâmetro default_locale especifica o nome do arquivo de strings de localidade padrão no projeto.

O arquivo de strings de localidade padrão determina quais strings do modelo são localizadas. Mesmo que um rótulo ou uma string de descrição seja definido em outro arquivo de strings de localidade, se ele não estiver definido no arquivo de strings de localidade padrão, a interface do Looker vai mostrar a string não localizada.

A localidade padrão do seu projeto não deve ser confundida com a localidade padrão dos usuários do Looker. O administrador do Looker pode definir uma localidade padrão para sua instância. Se nenhum padrão for definido, o Looker usará en. Se o administrador não inserir especificamente um valor de localidade para um usuário ou um grupo de usuários ao qual o usuário pertence, o Looker vai atribuir o usuário à localidade da instância padrão. Se o administrador não tiver definido uma localidade de instância padrão, o Looker vai atribuir o usuário à localidade en.

Por isso, a menos que você tenha certeza de que o administrador do Looker vai definir o valor de Locale para todos os usuários do Looker, defina o parâmetro default_locale do projeto como a localidade padrão da instância (ou como en, se nenhum padrão tiver sido definido) e defina a localização de todos os rótulos e descrições no arquivo .strings.json dessa localidade.

localization_level

O nível de localização do projeto especifica se elementos não localizados são permitidos no modelo:

  • Defina o nível de localização como strict para exigir rótulos localizados em todos os modelos, análises detalhadas, visualizações e campos do projeto. O Looker IDE vai retornar um erro de validação do LookML para qualquer um desses elementos que não tenham rótulos e para rótulos e descrições que não estiverem definidos no arquivo de strings de localidade padrão.
  • Defina o nível de localização como permissive para permitir elementos sem rótulos, além de rótulos e descrições que não estão definidos no arquivo de strings de localização padrão.

Mesmo que você queira o nível de localização strict, pode ser útil definir o nível de localização do projeto como permissive durante o desenvolvimento para evitar erros de validação. Quando terminar de localizar todos os rótulos e descrições, defina o nível de localização como strict para conferir os erros.

Atribuir usuários a uma localidade

Depois de configurar os arquivos de strings de localidade, você pode atribuir aos usuários uma localidade que corresponda a um dos arquivos de strings de localidade. Isso pode ser feito no nível da instância, do grupo de usuários ou do usuário individual, usando o campo Locale ou o atributo de usuário locale.

Por exemplo, se você quiser que um usuário tenha acesso aos rótulos e descrições definidos no arquivo es_ES.strings.json, o administrador do Looker precisará definir a configuração Localidade do usuário como es_ES.

Para inserir localidades personalizadas criadas com arquivos de string, clique no campo Locale e digite o nome do arquivo da string em vez de selecionar uma integrada no menu suspenso. Para mais informações, consulte a página de documentação Usuários.

Como definir a localidade para usuários de incorporação assinados

É possível incluir o valor da localidade de um usuário em um URL incorporado assinado, assim como qualquer outro atributo de usuário. O formato exato necessário para incorporações assinadas depende da linguagem de programação usada para criar o script de URL de incorporação assinado, mas o nome do atributo do usuário é locale. Consulte a página de documentação Incorporação assinada para mais informações sobre URLs de incorporação assinados e ferramentas para criar seu URL de incorporação assinado.

Como usar a localidade em variáveis Liquid

Conforme descrito anteriormente, a localização de modelos permite personalizar a exibição dos rótulos e descrições do seu modelo para diferentes localidades. Mas você também pode incluir chaves de localização nas variáveis do Liquid, o que permite localizar os valores dos dados.

Por exemplo, no arquivo de strings de localidade padrão chamado en.strings.json, podemos criar as chaves de localização domestic e international com as seguintes entradas:

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

No arquivo es_ES.strings.json, podemos fornecer versões em espanhol dessas chaves de localização:

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

A partir daí, podemos usar as chaves de localização domestic e international em variáveis líquidas para identificar a saída de uma dimensão:

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

Os usuários com a localidade en vão receber os seguintes resultados:

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

Os usuários com a localidade es_ES vão encontrar os seguintes resultados:

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

Os usuários com a localidade es_ES veem os dados "Domestic" e "International" localizados como "Nacional" e "Internacional", respectivamente.

Também é possível usar o Liquid nos filtros de painel do LookML e nos filtros de elemento do painel do LookML para localizar o valor padrão em um filtro. Por exemplo, se um dashboard do LookML tiver um bloco que usa dados desse modelo localizado e houver um filtro nesse bloco definido no LookML da seguinte forma:

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

Quando um usuário com a localidade en faz análises desse bloco no painel, a Análise é filtrada com o valor Domestic no campo Flights From the US?, e a tabela de dados em "Explorar" inclui os seguintes resultados:

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

Quando um usuário com a localidade es_ES faz uma análise detalhada usando esse bloco no painel, a análise detalhada é filtrada pelo valor Nacional do campo Vuelos ¿De Los Estados Unidos?, e a tabela de dados na análise detalhada inclui os seguintes resultados:

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

Como as regras de localização se aplicam a objetos estendidos e refinados

Lembre-se de que as regras de localização se aplicam quando você está estendendo visualizações, Análises ou dashboards do LookML e quando está refinando visualizações ou Análises.

Se você estendeu ou refinou um objeto e, em seguida, adicionou novos rótulos ou descrições, deve fornecer definições de localização nos arquivos de strings de localidade.

Por exemplo, se tivermos uma visualização flights:


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

Em seguida, criamos uma nova visualização que estende a flights:

include: "/views/flights.view"

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

Nos arquivos de strings de localidade, precisamos definir as duas strings do rótulo da visualização ("flight_info" e "enhanced_flight_info"). Se o nível de localização do projeto estiver definido como strict, não será possível confirmar atualizações até que os novos rótulos ou descrições sejam definidos.