Internacionalização (i18n)

Internacionalização e localização, em informática, são processos de desenvolvimento e/ou adaptação de um produto, em geral softwares de computadores, para uma língua e cultura de um país. A internacionalização de um produto não recria o produto novamente, somente adapta as mensagens do sistema à língua e à cultura locais. Isto é importante porque permite que o programador respeite as particularidades de cada língua e cultura de cada país.

Preparar uma aplicação para a sua internacionalização é vital para que seja possível a escalar a um nível global. Nesse sentido foi criada uma ferramenta para facilitar a globalização do front-end em soluções athena.

Configuração do módulo

A configuração da internacionalização num módulo está separada em três passos: 1. Pastas e ficheiros de resources; 2. Distribuição de resources; 3. Configuração.

No final de efetuar estes três passos, as resources serão distribuidas de forma correcta para o projecto principal, o ORINOCO irá proceder às traduções para as linguas necessárias e o serviço I18nService terá acesso a estas resources para serem usadas no módulo.

Pastas e ficheiros de resources

Na pasta do módulo deve ser criada a seguinte estrutura de pastas:

|--src
   |-- i18n
       |-- en-us

Na pasta en-us devem ser colocados todos os ficheiros de resources em inglês com o nome [module].[internacionalization_resource_group].lang.json. Como exemplo, para as resources dos componentes do módulo NgCore, o nome do ficheiro é ngcore.components.lang.json.

Os ficheiros devem conter um objecto json válido com o formato:

    {
        "RES_[resource_key_1]" : "[resource_value_1]",
        "RES_[resource_key_2]" : "[resource_value_2]",
        "RES_[resource_key_3]" : "[resource_value_3]"
    }

Distribuição de resources

O package que é distribuido com o módulo deve conter todos os ficheiros de resources disponívels. Depois de compilado o módulo, os ficheiros de resources devem estar na pasta dist/assets/i18n/[locale]. Usando o exemplo do módulo NgCore, a estrutura de pastas fica a seguinte:

|--dist
   |--assets
      |--i18n
         |--en-us
            |-- ngcore.components.lang.json
         |--es-es
            |-- ngcore.components.lang.json
         |--pt-pt
            |-- ngcore.components.lang.json

Para distribuir os ficheiros de forma automática sempre que se faça build do módulo, deve-se adicionar o seguinte snipet ao ficheiro Gulp que trata da compilação do módulo.

gulp.task('copy:languageresources', function () {
  let dirnameParts = __dirname.split('\\');
  let moduleName = dirnameParts[dirnameParts.length - 1];

  return gulp.src(`${srcFolder}/i18n/**/*.lang.json`)
    .pipe(gulp.dest(`${distFolder}/assets/i18n`));
});

Esta task deve ser executada depois da task de build, para garantir que a pasta /dist já se encontra criada.

Configuração

Para o serviço i18n estar disponível num módulo é necessário adicionar o módulo i18n à lista de imports do módulo

@NgModule({
  imports: [
    ...
    PrimaveraI18nModule.forRoot(i18nConfig),
    ...
  ]})

passando a configuração com o locale e a lista de resources deste módulo

let i18nConfig : I18nConfig = {
  locale: '[locale]', // 'pt-PT' p.e.
  sources: ['[module].[internacionalization_resource_group].lang', '...'] // ['ngcore.components.lang'] p.e.
}

Como utilizar resources

As resources localizadas podem ser usadas de três formas - Serviço I18nService - Directiva PriI18N - Filtro PriI18n

Serviço I18nService

Para usar o serviço I18nService é necessário adicionar o serviço ao construtor da class, e invocar o método get do serviço, passando a chave da resource.

let title = this.i18nService.get('ngcore.components.RES_PriImagePicker_RemovePhotoPopupTitle')

Caso a resource não exista, é retornada a chave da resource.

Directiva PriI18n

Para usar a directiva PriI18n basta adicionar a directiva ao elemento do DOM que pretende traduzir, passando a respectiva chave da resource.

<span priI18n="ngcore.components.RES_PriImagePicker_Placeholder_LabelTwo"></span>

Caso a resource não exista, é retornada a chave da resource.

Filtro PriI18n

Para usar o filtro PriI18n basta adicionar a chave da resource a uma expressão angular e adicionar o filtro PriI18n.

{{"ngcore.components.RES_PriImagePicker_Placeholder_LabelTwo" | PriI18n}}

Caso a resource não exista, é retornada a chave da resource.