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 em localização geográfica ou idioma. É possível usar localidades para representar outros fatores distintos, como usuários internos e externos ou gerentes e colaboradores individuais, e personalizar seus rótulos e descrições de acordo com isso.

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

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. Determine a exibição para diferentes usuários atribuindo usuários a localidades.

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.

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:

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

Dica: a localização não está disponível para 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 seu 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 painel, além de elementos de type: text)
• comparison_label
• single_value_title

Para conferir todos os campos do seu 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 seu modelo do LookML que podem ser localizadas, mas 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 seu 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 padrão. Caso contrário, ela não será localizada.

Dica: a localização do modelo 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 o painel e a interface do usuário de visualização localizados nativamente do Looker, precisará 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 Locale de en. Na amostra 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, não fornecemos um rótulo para a dimensão location. Por isso, o Looker mostra o nome da dimensão em maiúsculas: "Location".
• Não definimos a localização do rótulo "country" no arquivo en.strings.json. Por isso, o Looker mostra o rótulo como ele está definido no arquivo de visualização, sem usar letras maiúsculas: "country".

Como outro exemplo, podemos criar um arquivo es_ES.strings.json 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: "Localização".
• Não definimos a localização do rótulo "country" no arquivo en.strings.json, que é o arquivo de strings de localidade padrão. Portanto, mesmo que tenhamos definido "country" no arquivo es_ES.strings.json, o Looker não localiza essa string e mostra o rótulo como está definido no arquivo de visualização: "country".

Adicionar configurações de localização ao arquivo de manifesto do projeto

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

Dica: se o projeto ainda não tiver um, crie um arquivo de manifesto usando o ícone + na parte de cima do navegador de arquivos no ambiente de desenvolvimento integrado 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 seu projeto.

O arquivo de strings de localidade padrão determina quais strings do seu 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 estiver definida 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 vai usar en. Se o administrador não inserir um valor de localidade específico para um usuário ou um grupo de usuários a que ele pertence, o Looker vai atribuir o usuário à localidade padrão da instância. Se o administrador não tiver definido uma localidade padrão para a instância, 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 Localidade para todos os usuários do Looker, defina o parâmetro default_locale do projeto como a localidade padrão da sua 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 seu 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 detalhadas, visualizações e campos no seu projeto. O IDE do Looker vai retornar um erro de validação da LookML para qualquer um desses elementos que não tiverem rótulos e para qualquer rótulo e descrição 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 e 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 localizar todos os rótulos e descrições, defina o nível de localização como strict para ver os erros.

Como atribuir usuários a uma localidade

Depois de configurar os arquivos de strings de localidade, você pode atribuir usuários a 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 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 Localidade do usuário como es_ES.

Os locais personalizados criados com arquivos de strings podem ser inseridos no campo Localidade. Para isso, clique no campo e digite 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, 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 isso, um arquivo .strings precisa ser configurado para a localidade padrão de cada instância. Saiba mais na seção default_locale ou nas seções Como criar arquivos de strings de localidade.

Definir a localidade para usuários incorporados conectados

É possível incluir o valor de localidade de um usuário em um URL de incorporação 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 do 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 assinados e ferramentas para criar seu URL de incorporação assinado.

Como usar a localidade em variáveis Liquid

Como descrito anteriormente, a localização do modelo permite personalizar a exibição dos rótulos e das descrições do modelo para diferentes localidades. Mas também é possível incluir chaves de localização em variáveis do Liquid, o que permite localizar seus valores de 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 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 ver 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 ver 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 "Doméstico" e "Internacional" localizados como "Nacional" e "Internacional", respectivamente.

Você também pode usar o Liquid em filtros do painel do LookML e filtros de elementos do painel do LookML para localizar o valor padrão em um filtro. Por exemplo, se um painel da LookML tiver um bloco usando dados desse modelo localizado e houver um filtro nesse bloco definido na LookML da seguinte maneira:

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

Quando um usuário com a localidade en faz uma análise detalhada desse bloco no painel, a análise detalhada é filtrada no valor Domestic para o campo Flights From the US?, e a tabela de dados na análise detalhada 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 acessa a análise detalhada do bloco no painel, ela é filtrada pelo valor Nacional no 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

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

As regras de localização são aplicadas quando você estende visualizações, análises detalhadas ou dashboards do LookML e quando refina visualizações ou análises detalhadas.

Se você tiver estendido ou refinado um objeto e adicionado 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, precisaríamos definir as duas strings de 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 nenhuma atualização até que os novos rótulos ou descrições sejam definidos.