Localizar o seu modelo do LookML

Com a localização de modelos, pode personalizar a forma como as etiquetas e as descrições do seu modelo são apresentadas de acordo com o local de um utilizador.

A localização não tem de se basear na localização geográfica nem no idioma. Pode usar locais para representar outros fatores distintivos, como utilizadores internos versus externos ou gestores versus colaboradores individuais, e personalizar as suas etiquetas e descrições em conformidade.

Esta página descreve os passos para localizar o seu projeto:

1. Determine que elementos vão ser localizados adicionando etiquetas, etiquetas de grupo e descrições ao seu modelo.
2. Forneça as definições de localização para o seu projeto criando ficheiros de strings locais.
3. Ative a localização para o seu projeto adicionando definições de localização ao ficheiro de manifesto do projeto.
4. Determinar a apresentação para diferentes utilizadores atribuindo utilizadores a localizações.

A localização de modelos ocorre frequentemente em conjunto com um administrador que especifica as definições de localização do formato de número e idioma da interface do utilizador.

Localizar etiquetas e descrições no seu modelo

Pode localizar etiquetas, etiquetas de grupo e descrições no seu modelo, incluindo o seguinte:

• label para campo, modelo, explorar ou ver
• label para aplicações no framework de extensão do Looker
• group_label para explorar e group_label para o campo
• group_item_label para o campo
• description para explorar e description para o campo

Também pode criar painéis de controlo do LookML localizados no seu projeto. Os seguintes parâmetros do painel de controlo 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 de controlo, além dos elementos de type: text)
• comparison_label
• single_value_title

Para ver todos os campos no seu projeto que podem ser localizados, pode definir o nível de localização do projeto como strict. Com esta definição, o IDE do Looker devolve um erro de validação do LookML para quaisquer elementos do LookML que possam ser localizados, mas que não tenham etiquetas, e para quaisquer strings no seu modelo do LookML que possam ser localizadas, mas que não estejam definidas nos seus ficheiros de strings de local.

No exemplo de LookML seguinte, são fornecidas etiquetas para a vista 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 que se seguem nesta página, vamos localizar estes valores nos ficheiros de strings usando um permissive nível de localização. Tenha em atenção que a dimensão location não tem uma etiqueta, pelo que podemos demonstrar como é apresentada uma dimensão sem localização.

Criar ficheiros de strings locais

Os ficheiros de strings de local usam pares de chaves-valores para definir como as etiquetas e as descrições no seu modelo são apresentadas para cada local. No lado esquerdo de cada par de chave-valor, encontra-se a chave de localização, que é uma etiqueta ou uma string de descrição do seu modelo. O lado direito do par chave-valor é onde define como quer que essa string seja apresentada na IU do Looker.

Para cada local que quer usar para o seu projeto, tem de criar um ficheiro de strings dedicado. Crie apenas um ficheiro de strings para cada local. Tem de ter um ficheiro de strings com um nome que corresponda ao local predefinido. Por exemplo, se tiver especificado default_locale: en no ficheiro de manifesto do seu projeto, tem de ter um ficheiro no seu modelo denominado en.strings.json. Cada string tem de ser definida no ficheiro de strings do local predefinido, caso contrário, não é localizada.

Este exemplo de um ficheiro en.strings.json vai ser usado para todos os utilizadores que tenham o valor Local de en. No exemplo de LookML seguinte, en também é especificado como o local predefinido, pelo que todas as strings têm de ser definidas neste ficheiro para serem localizadas.

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

A tabela seguinte mostra o que um utilizador com a respetiva definição regional definida como en veria na tabela de dados de uma exploração do Looker:

Tenha em conta o seguinte:

• No flights exemplo de LookML apresentado anteriormente, não fornecemos nenhuma etiqueta para a dimensão location, pelo que o Looker apresenta o nome da dimensão com a primeira letra em maiúscula: "Location" (Localização).
• Não definimos a localização para a etiqueta "country" no nosso ficheiro en.strings.json, pelo que o Looker apresenta a etiqueta tal como está definida no nosso ficheiro de visualização, sem usar letras maiúsculas: "country".

Como outro exemplo, podemos criar um ficheiro es_ES.strings.json que seja usado para todos os utilizadores com um valor de 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 seguinte mostra o que um utilizador com a respetiva definição regional definida como es_ES veria no Looker:

Tenha em conta o seguinte:

• Tal como no exemplo anterior, na visualização original com etiquetas e descrições adicionadas, não fornecemos nenhuma etiqueta para a dimensão location, pelo que o Looker apresenta o nome da dimensão em maiúsculas: "Localização".
• Não definimos a localização para a etiqueta "country" no nosso ficheiro en.strings.json, que é o nosso ficheiro de strings de local predefinido. Assim, embora tenhamos definido "country" no nosso ficheiro es_ES.strings.json, o Looker não localiza esta string e apresenta a etiqueta tal como está definida no nosso ficheiro de visualização: "country".

Adicionar definições de localização ao ficheiro de manifesto do seu projeto

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

No ficheiro de manifesto, adicione as definições de localização. Segue-se um exemplo:

localization_settings: {
  default_locale: en
  localization_level: permissive
}

default_locale

O parâmetro default_locale especifica o nome do ficheiro de strings do local predefinido no seu projeto.

O ficheiro de strings locais predefinido determina que strings do seu modelo são localizadas. Mesmo que uma etiqueta ou uma string de descrição seja definida noutro ficheiro de strings de local, se não for definida no ficheiro de strings de local predefinido, a IU do Looker apresenta a string não localizada.

O local predefinido do seu projeto não deve ser confundido com o local predefinido dos utilizadores do Looker. O administrador do Looker pode definir uma região predefinida para a sua instância. Se não for definida nenhuma predefinição, o Looker usa en por predefinição. Se o administrador não introduzir especificamente um valor de local para um utilizador ou um grupo de utilizadores ao qual o utilizador pertence, o Looker atribui o utilizador à definição regional predefinida da instância. Além disso, se o administrador não tiver definido um local de instância predefinido, o Looker atribui o utilizador ao local en.

Por este motivo, a menos que tenha a certeza de que o administrador do Looker vai definir o valor Locale para todos os utilizadores do Looker, deve definir o parâmetro default_locale do seu projeto para o local predefinido da sua instância (ou para en se não tiver sido definido nenhum valor predefinido) e definir a localização para todas as etiquetas e descrições no ficheiro .strings.json para esse local.

localization_level

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

• Defina o nível de localização como strict para exigir etiquetas localizadas para todos os modelos, elementos Explorar, vistas e campos no seu projeto. O IDE do Looker devolve um erro de validação do LookML para qualquer um destes elementos que não tenha etiquetas, bem como para quaisquer etiquetas e descrições que não estejam definidas no ficheiro de strings do local predefinido.
• Defina o nível de localização como permissive para permitir elementos sem etiquetas e permitir etiquetas e descrições que não estão definidas no ficheiro de strings de localização predefinido.

Mesmo que queira o nível de localização strict, pode ser útil definir o nível de localização do seu projeto como permissive quando estiver a desenvolver o projeto para evitar erros de validação. Depois de terminar a localização de todas as etiquetas e descrições, pode definir o nível de localização como strict para ver os erros.

Atribuir utilizadores a uma região

Depois de configurar os ficheiros de strings locais, pode atribuir utilizadores a uma localidade que corresponda a um dos ficheiros de strings locais. Isto pode ser feito ao nível da instância, do grupo de utilizadores ou do utilizador individual, através do campo Local ou do localeatributo do utilizador.

Por exemplo, se quiser que um utilizador veja as etiquetas e as descrições definidas no ficheiro es_ES.strings.json, o administrador do Looker deve definir a definição Localidade do utilizador como es_ES.

Pode introduzir as localidades personalizadas que criar com ficheiros de strings no campo Localidade. Para tal, clique no campo e escreva o nome do ficheiro de strings, em vez de selecionar uma localidade integrada no menu pendente. Para mais informações, consulte a página de documentação Utilizadores.

Definir a região para utilizadores incorporados com sessão iniciada

Pode incluir o valor da localização de um utilizador num URL incorporado assinado, tal como qualquer outro atributo do utilizador. O formato exato necessário para as incorporações assinadas depende da linguagem de programação usada para criar o script do URL de incorporação assinado, mas o nome do atributo do utilizador é 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 o seu URL de incorporação assinado.

Usar o local nas variáveis Liquid

Conforme descrito anteriormente, a localização de modelos permite-lhe personalizar a apresentação das etiquetas e descrições do seu modelo para diferentes locais. No entanto, também pode incluir chaves de localização em variáveis Liquid, o que lhe permite localizar também os valores dos dados.

Por exemplo, no nosso ficheiro de strings locais predefinido denominado en.strings.json, podemos criar as chaves de localização domestic e international com as seguintes entradas:

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

Depois, no nosso ficheiro 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 em variáveis Liquid para localizar o resultado 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 utilizadores com a região en veem os seguintes resultados:

Os utilizadores com a região es_ES veem os seguintes resultados:

Os utilizadores com a localidade es_ES veem os dados "Nacional" e "Internacional" localizados para "Nacional" e "Internacional", respetivamente.

Também pode usar o Liquid em filtros do painel de controlo do LookML e filtros de elementos do painel de controlo do LookML para localizar o valor predefinido num filtro. Por exemplo, se um painel de controlo do LookML tiver um mosaico que use dados deste modelo localizado e existir um filtro nesse mosaico definido no LookML da seguinte forma:

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

Quando um utilizador com a localidade en explora a partir desse mosaico no painel de controlo, a exploração é filtrada no valor Domestic para o campo Flights From the US?, e a tabela de dados na exploração inclui os seguintes resultados:

Quando um utilizador com a localidade es_ES explora a partir desse mosaico no painel de controlo, a exploração é filtrada no valor Nacional para o campo Vuelos ¿De Los Estados Unidos?, e a tabela de dados na exploração inclui os seguintes resultados:

Compreender como as regras de localização se aplicam a objetos expandidos e refinados

Tenha em atenção que as regras de localização aplicam-se quando estende vistas, explorações ou painéis de controlo do LookML e quando refina vistas ou explorações.

Se tiver expandido ou refinado um objeto e, em seguida, adicionado novas etiquetas ou descrições, deve fornecer definições de localização nos ficheiros de strings de local.

Por exemplo, se tivermos uma vista flights:

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

Em seguida, criamos uma nova visualização de propriedade que expande a visualização de propriedade flights:

include: "/views/flights.view"

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

Nos nossos ficheiros de strings de locais, teríamos de definir ambas as strings de etiquetas de visualização ("flight_info" e "enhanced_flight_info"). Se o nível de localização do projeto estiver definido como strict, não poderíamos confirmar atualizações até definirmos as novas etiquetas ou descrições.