Como localizar seu modelo do LookML

Com a localização de modelos, é possível personalizar a forma como os rótulos e as descrições do modelo são exibidos de acordo com a localidade de um usuário.

A localização não precisa ser baseada na localização geográfica ou no idioma. É possível usar localidades para representar outros fatores de distinção, como usuários internos e externos ou gerentes e colaboradores individuais, e personalizar os rótulos e as descrições de acordo com esses fatores.

**Observação**: a localização de modelos não é compatível com a importação de projetos.

Esta página descreve as etapas para localizar seu projeto:

1. Determine quais elementos serão localizados adicionando rótulos, rótulos de grupo e descrições ao modelo.
2. Forneça as definições de localização do projeto por criar arquivos de strings de localidade.
3. Ative a localização do projeto adicionando configurações de localização ao arquivo de manifesto do projeto.
4. Determine a exibição para diferentes usuários por atribuindo usuários a localidades.

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

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

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

• label para campo, modelo, análise ou visualização
• label para aplicativos no framework de extensões do Looker
• group_label para análise e group_label para campo
• group_item_label para campo
• description para análise e description para campo

Dica: a localização não é compatível com dimension_group. Em vez disso, use group_label e group_item_label no nível do campo para criar seu próprio conjunto de dimensões que podem ser localizadas.

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

• title
• description
• text (que é um subparâmetro do parâmetro note e pode ser aplicado a todos os tipos de elementos do dashboard, além de elementos de type: text)
• comparison_label
• single_value_title

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 ambiente de desenvolvimento integrado (IDE, na sigla em inglês) do Looker retorna um erro de validação do LookML para todos os elementos do LookML que podem ser localizados, mas que não têm rótulos, e para todas as strings no modelo do LookML que podem ser localizadas, mas que não estão definidas nos arquivos de strings de localidade.

No exemplo de LookML a seguir, os rótulos são fornecidos para a visualização flights e os campos id, country e number_of_engines. Uma descrição também é fornecida 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. Assim, 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 exibidos para cada localidade. No lado esquerdo de cada par de chave-valor está a chave de localização, que é uma string de rótulo ou descrição do modelo. O lado direito do par de chave-valor é onde você define como quer que essa string seja exibida 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. É necessário ter um arquivo de strings com o mesmo nome da 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 padrão ou não será localizada.

Dica: a localização de modelos não precisa ser baseada na localização geográfica ou no idioma. No entanto, se você estiver usando a localização de modelos e também quiser usar a interface do usuário do painel e da visualização do Looker, que é localizada nativamente, é necessário corresponder o título do arquivo de strings aos códigos de localidade compatíveis do Looker.

Este exemplo de um arquivo en.strings.json será usado para todos os usuários que tiverem o valor Localidade de en. No exemplo de LookML a seguir, en também é especificado 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 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 exemplo de LookML da visualização flights mostrado anteriormente nesta página, nenhum rótulo foi fornecido para a dimensão location. Portanto, o Looker capitaliza o nome da dimensão e o exibe como "Location".
• A localização do rótulo "country" não foi definida no arquivo en.strings.json. Portanto, o Looker exibe o rótulo conforme definido no arquivo de visualização, sem capitalizá-lo: "country".

Como outro exemplo, podemos criar um arquivo es_ES.strings.json que é usado para todos os usuários com um valor de Localidade 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, no formato original com rótulos e descrições adicionados, nenhum rótulo foi fornecido para a dimensão de local. Portanto, o Looker capitaliza e exibe o nome da dimensão como "Location".
• A localização não foi definida para o rótulo "country" no arquivo en.strings.json, que é o arquivo de strings de localidade padrão. Isso significa que, mesmo que "country" tenha sido definido 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 projeto

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

Dica: se o projeto ainda não tiver um, você pode criar um arquivo de manifesto no ícone + na parte de cima do navegador de arquivos no ambiente de desenvolvimento integrado (IDE, na sigla em inglês) do Looker.

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 uma string de rótulo ou descrição seja definida em outro arquivo de strings de localidade, se ela não for definida no arquivo de strings de localidade padrão, a interface do Looker vai exibir a string não localizada.

Não confunda a localidade padrão do projeto com a localidade padrão para usuários do Looker. O administrador do Looker pode definir uma localidade padrão para a instância. Se nenhum padrão for definido, o Looker vai usar en. Se o administrador não inserir um valor de Localidade para um usuário ou um grupo de usuários a que ele pertence, o Looker vai atribuir o usuário à localidade da instância padrão. E, se o administrador não tiver definido uma localidade de instância padrão, o Looker vai atribuir o usuário à localidade en.

Por esse motivo, a menos que você tenha certeza de que o administrador do Looker vai definir o valor de Localidade 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 para todos os modelos, análises, visualizações e campos do projeto. O ambiente de desenvolvimento integrado (IDE, na sigla em inglês) do Looker retorna um erro de validação do LookML para todos esses elementos que não têm rótulos, bem como para todos os rótulos e descrições que não estão definidos no arquivo de strings de localidade padrão.
• Defina o nível de localização como permissive para permitir elementos sem rótulos e para permitir 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 ao desenvolver o projeto para evitar erros de validação. Depois de terminar de localizar todos os rótulos e descrições, defina o nível de localização como strict para conferir os erros.

Como atribuir usuários a uma localidade

Depois de configurar os arquivos de strings de localidade, é possível atribuir usuários a uma localidade que corresponde 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 Localidade ou o atributo do usuário locale.

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

As localidades personalizadas criadas com arquivos de strings podem ser inseridas no campo Localidade clicando no campo e digitando o nome do arquivo de strings em vez de selecionar uma localidade integrada no menu suspenso. Para mais informações, consulte a página de documentação Usuários.

Observação: quando uma localidade não é definida para usuários no nível individual ou de grupo de usuários, o Looker atribui os usuários à localidade da instância. No entanto, se não houver um arquivo .strings configurado para a localidade da instância, a localização do modelo não vai funcionar para esses usuários. Por esse motivo, um arquivo .strings precisa ser configurado para a localidade padrão de cada instância. Saiba mais sobre localidades na seção learn more about locales in the default_locale section ou consulte Como criar arquivos de strings de localidade.

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

É possível incluir o valor de localidade de um usuário em um URL de incorporação assinada, assim como qualquer outro atributo do 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 assinada, 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 assinada e ferramentas para criar o URL de incorporação assinada.

Como usar a localidade em variáveis do Liquid

Conforme descrito anteriormente, a localização de modelos permite personalizar a exibição dos rótulos e das descrições do modelo para diferentes localidades. No entanto, também é possível incluir chaves de localização em 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"
}

Em seguida, 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 do Liquid para localizar 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 encontrar estes 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 estes 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 encontram 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 elementos do painel do LookML para localizar o valor padrão em um filtro. Por exemplo, se um painel do LookML tiver um bloco usando dados desse modelo localizado e houver um filtro nesse bloco definido no LookML da seguinte maneira:

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

Quando um usuário com a localidade en explora esse bloco no painel, a análise é filtrada no valor Domestic para o campo Flights From the US?, e a tabela de dados na análise 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 explora esse bloco no painel, a análise é filtrada no valor Nacional para o campo Vuelos ¿De Los Estados Unidos?, e a tabela de dados na análise 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

As regras de localização são aplicadas quando você está estendendo visualizações, análises ou painéis do LookML e quando está refinando visualizações ou análises.

Se você estendeu ou refinou um objeto e adicionou novos rótulos ou descrições, forneça 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 visualização 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 de rótulo de 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 nenhuma atualização até que definamos os novos rótulos ou descrições.