Como localizar seu modelo do LookML

A localização de modelos geralmente ocorre em conjunto com a localização do formato de número e a seleção de idioma da interface do usuário. Para saber mais sobre esses tópicos, acesse as páginas de documentação Formatação de números de localização e Idiomas da interface do usuário compatíveis.

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

A localização não precisa ser baseada em localização geográfica ou idioma. Você pode usar localidades para representar outros fatores característicos, como usuários internos x externos, ou gerentes versus colaboradores individuais, e personalizar seus rótulos e descrições de acordo.

No momento, a localização de modelos não é compatível com a importação de projetos.

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

Para saber mais sobre como localizar a interface do usuário do Looker ou localizar a formatação de números, acesse as páginas de documentação Idiomas da interface do usuário compatíveis e Como localizar a formatação de números.

Como usar elementos localizados nos arquivos de modelo

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

Não há suporte para localização para dimension_group. Em vez disso, use group_label e group_item_label para criar seu próprio conjunto de dimensões que podem ser localizadas.

Você também pode criar painéis do LookML localizados no seu projeto. Os seguintes parâmetros do painel do LookML podem ser localizados:

Para ver 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 do Looker retorna um erro de validação do LookML para qualquer elemento LookML que possa ser localizado, mas não tenha rótulos, e para qualquer string no modelo do LookML que possa ser localizada, mas não definida nos seus arquivos de strings de localidade.

Veja um exemplo de arquivo com alguns rótulos e descrições:

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"

    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 ;;
  }

Localizaremos esses valores nos arquivos de strings usando um nível de localização permissive. A dimensão location não tem um rótulo para que possamos 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 exibidos em cada localidade. À esquerda de cada par de chave-valor está a chave de localização, que é uma string de descrição ou rótulo do seu modelo. O lado direito do par de chave-valor é onde você define como quer que a string seja exibida na IU do Looker.

Para cada localidade do projeto, crie um arquivo de strings dedicado. Crie apenas um arquivo de strings para cada localidade no seu projeto. Deve haver um arquivo de strings com o nome correspondente à localidade padrão. Por exemplo, se você tiver especificado default_locale: en no arquivo de manifesto do seu projeto, será necessário ter um arquivo no modelo chamado en.strings.json. Cada string precisa ser definida no arquivo de strings de localidade default. Caso contrário, ela não será localizada.

A localização de modelos não precisa ser baseada em localização geográfica ou idioma. No entanto, se você estiver usando a localização de modelos e também quiser usar o painel nativo e a interface do usuário de visualização localizada no Looker, será preciso corresponder o título do arquivo de strings com os códigos de localidade compatíveis do Looker.

Veja um exemplo de arquivo en.strings.json que será usado por todos os usuários com o valor Locale de en. Neste exemplo, en também é especificado como nossa localidade padrão. Portanto, todas as strings precisam ser definidas nesse arquivo para serem localizadas.

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

Um usuário do en veria isso no Looker:

Observações:

  • No arquivo de visualização acima, não fornecemos nenhum rótulo para a dimensão location. Por isso, o Looker exibe o nome da dimensão em letras maiúsculas: "Local".
  • Não definimos a localização do rótulo "country" no arquivo en.strings.json, então o Looker exibe o rótulo conforme definido no arquivo de visualização, sem colocar em letra maiúscula: "country".

Como outro exemplo, podemos criar um arquivo es_ES.strings.json que é usado para todos os usuários com o valor Locale de 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"
}

Um usuário do es_ES veria isso no Looker:

Observações:

  • Como no exemplo anterior, no arquivo de visualização acima, não fornecemos um rótulo para a dimensão location. Por isso, o Looker mostra o nome da dimensão em letras maiúsculas: "Local".
  • Não definimos a localização do rótulo "país" no arquivo en.strings.json, que é o arquivo de strings da localidade padrão. Portanto, mesmo que tenhamos 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 do projeto.

Se o projeto ainda não tiver um arquivo de manifesto, crie um no ícone + na parte superior do navegador de arquivos do 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 estão localizadas. Mesmo que uma string de rótulo ou descrição seja definida em outro arquivo de strings de localidade, se não estiver definida no arquivo de strings de localidade padrão, a IU do Looker exibirá a string não localizada. Consulte esta seção acima para mais informações sobre como configurar arquivos de strings de localidade.

A localidade padrão do seu projeto não deve ser confundida com a localidade padrão para 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 como padrão. Se o administrador não inserir um valor de Locale específico para um usuário ou um grupo de usuários ao qual o usuário pertence, o Looker atribuirá o usuário à localidade padrão da instância. Se o administrador não tiver definido uma localidade de instância padrão, o Looker atribuirá o usuário à localidade en.

Por esse motivo, a menos que você tenha certeza de que o administrador do Looker 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 seu projeto especifica se elementos não localizados são permitidos no seu modelo:

  • Defina o nível de localização como strict para exigir rótulos localizados para todos os modelos, explorações, visualizações e campos no seu projeto. O ambiente de desenvolvimento integrado do Looker retorna um erro de validação do LookML para qualquer um desses elementos que não têm rótulos e para qualquer rótulo e descrição que não esteja definido no arquivo de strings de localidade padrão.
  • Defina o nível de localização como permissive para permitir elementos sem rótulos e permitir rótulos e descrições que não estejam definidos no arquivo de strings de localização padrão.

Mesmo que você queira o nível de localização do strict, pode ser útil definir o nível de localização do projeto como permissive ao desenvolver seu projeto para evitar erros de validação. Depois de localizar todos os rótulos e descrições, é possível definir o nível de localização como strict para ver os erros.

Atribuir usuários a uma localidade

Depois de configurar os arquivos de strings de localidade, você pode 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 Local ou o atributo de 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 precisa definir a configuração de Localidade como es_ES:

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

Quando uma localidade não é definida para usuários no nível individual ou no grupo de usuários, o Looker atribui 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 funcionará para esses usuários. Por isso, um arquivo .strings precisa ser configurado para a localidade padrão de cada instância. Saiba mais nas seções default_locale ou Como criar arquivos de strings de localidade.

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

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

Como usar a localidade em variáveis Liquid

Conforme descrito acima, a localização de modelos permite personalizar a exibição dos rótulos e descrições de modelos para diferentes localidades. Também é possível incluir chaves de localização em Variáveis líquidas, que também permitem localizar valores de dados.

Por exemplo, em nosso 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 destas chaves de localização: 

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

A partir daí, podemos usar as chaves de localização domestic e international nas 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;;
  }

Agora, os usuários da localidade en veem o seguinte:

Veja o que nossos usuários da localidade es_ES veem:

Também é possível usar o filtro "Liquid" nos filtros do painel e do elemento do painel para localizar o valor padrão em um filtro. Por exemplo, se um painel do LookML tiver um bloco da guia Explorar acima e houver um filtro nesse bloco definido da seguinte maneira:

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

Veja o que os usuários da localidade en veriam ao explorar a partir do bloco no painel:

Veja o que os usuários da localidade es_ES veriam ao explorar a partir do bloco no painel:

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

Lembre-se de que as regras de localização se aplicam quando você estende visualizações, painéis de exploração ou LookML e ao refinar visualizações ou explorações.

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, precisamos definir as duas strings do 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é definirmos os novos rótulos ou descrições.