Uma instrução prática passo a passo sobre como fixar a localização dinâmica (a capacidade de selecionar idiomas) em um aplicativo Web Angular 4+ usando @ ngx-translate / core .
Em princípio, você pode encontrar publicações sobre um tópico semelhante; a documentação desta biblioteca pode ser suficiente, mas eu queria sistematizar esta instrução para uma aplicação mais conveniente. Esse marcador está no cofrinho de um desenvolvedor Angular novato. No final do artigo, há um link para um repositório aberto com um exemplo.
Por que exatamente ngx-translate
Quero fazer uma reserva imediatamente, esta é uma instrução para usar uma biblioteca específica. Não falaremos sobre alternativas, que o angular tem sua própria localização i18n. Se apenas porque, com uma mudança dinâmica de linguagem, há perguntas.
O que temos na saída
- Aplicativo angular, na pasta
assets/locale há arquivos *.json com chaves e seus valores localizados, um arquivo para cada idioma suportado no aplicativo Web. - Mudança dinâmica de idioma
- Armazenar chaves em uma estrutura de objeto, ou seja, tem algo como isto:
// en.json { Common: { Yes: "Yes" } }
Isso permitirá que você agrupe chaves / valores e, de alguma forma, organize um arquivo json com localização. Para projetos grandes, é bastante útil.
- Automação mínima e verificação de idiotas. E se você esqueceu de adicionar a chave no json?
- Aplicação de localização nos modelos html e no código ts
Personalizar
Criamos ou aceitamos um projeto angular pronto. A versão do angular é 4+, mas é melhor, naturalmente, o mais atualizado possível.
Instale as bibliotecas necessárias:
npm install @ngx-translate/core --save npm install @ngx-translate/http-loader --save @biesbjerg/ngx-translate-extract --saveDev
A @ngx-translate/http-loader é necessária para que possamos ler os dados de localização dos arquivos *.json . Você pode viver sem ele, mas precisará gravar o armazenamento e o carregamento dos dados de localização de maneira totalmente independente. Essa abordagem é adequada para aqueles que possuem dados de localização (ou simplesmente todos os textos traduzidos) já armazenados em algum lugar.
A @biesbjerg/ngx-translate-extract é opcional, mas bastante útil. Ele permite que você colete chaves de localização esquecidas pelo código do aplicativo e atualize os arquivos de localização. É muito conveniente usá-lo para processar esse cenário: adicione um novo idioma e apenas execute o comando nesta biblioteca. Como resultado, o arquivo vazio para o novo idioma será preenchido com toda a estrutura das chaves e alguns valores padrão. Um exemplo estará abaixo.
- Importe a biblioteca no módulo principal:
@NgModule({ imports: [ TranslateModule.forRoot({ loader: { provide: TranslateLoader, useFactory: HttpLoaderFactory, deps: [HttpClient], }, useDefaultLang: false, }) ], }) export class AppModule { }
O HttpLoaderFactory presente nas HttpLoaderFactory da biblioteca, pode ser descrito diretamente no mesmo arquivo, é de tamanho modesto.
export function HttpLoaderFactory(http: HttpClient): TranslateLoader { return new TranslateHttpLoader(http, './assets/locale/', '.json'); }
É aqui que indicamos o caminho para os arquivos de localização. Se eles são armazenados de alguma forma separadamente, ou mesmo de maneira diferente em ambientes diferentes - altere esse código para usar environment.ts por exemplo.
- Em princípio, isso é suficiente para as configurações básicas, mas daremos outra etapa adicional - tratamento de erros quando a chave não for encontrada.
Para fazer isso, adicione mais um campo à configuração (imediatamente após a especificação do carregador):
missingTranslationHandler: { provide: MissingTranslationHandler, useClass: MissingTranslationService },
E, é claro, você precisa criar a implementação desse manipulador em um arquivo separado:
export class MissingTranslationService implements MissingTranslationHandler { handle(params: MissingTranslationHandlerParams) { return `WARN: '${params.key}' is missing in '${params.translateService.currentLang}' locale`; } }
- Adicione armazenamento dos idiomas disponíveis. No caso simples, é conveniente colocá-los no
environment.ts
locales: ['en', 'ru'], defaultLocale: 'en',
- Para que o serviço comece a funcionar, ele deve ser inicializado no arquivo AppComponent ao carregar o aplicativo:
@Component({...}) export class AppComponent implements OnInit { constructor(private translateService: TranslateService) {} ngOnInit(): void { this.translateService.use(environment.defaultLocale); } }
- Adicione os arquivos
en.json e ru.json (de acordo com o que é indicado na lista de idiomas disponíveis). Adicione algum campo base para que seja válido json.
Quando essas etapas são executadas, o serviço começará a funcionar.
Nós usamos o serviço
Marcação HTML
Tudo é simples aqui. A biblioteca oferece translate pipe, apenas aplicamos na marcação para determinadas chaves.
<label>{{ 'LANGUAGES.TITLE' | translate }}</label>
Observe que eu uso as propriedades anexadas aqui, a estrutura json da qual falei no início.
Os parâmetros também são suportados, veja-os na documentação @ ngx-translate / core . Usando parâmetros, você pode implementar algo como interpolação de string.
No código do componente
this.translateService.get(['KEY1', 'KEY2'])) .subscribe(translations => { console.log(translations['KEY1']) console.log(translations['KEY2']) });
Essa é uma maneira confiável se você é normal com Observable e RxJs.
Caso contrário, existe uma maneira:
this.translateService.instant('Key')
Esse método funciona bem, mas no estágio de inicialização do aplicativo (por exemplo, ngOnInit AppComponent), os dados para ele ainda não podem ser carregados. Tome cuidado.
Suporte para arquivos .json
No final, quero mostrar como usar o ngx-translate-extract . Basta executar o comando ngx-translate-extract -i ./src -o src/assets/locale/*.json --sort --format namespaced-json no console. Este comando iniciará a análise dos arquivos do aplicativo, código de marcação e timecode. Todas as chaves encontradas na marcação e em outro código cairão em .json para todos os idiomas; as chaves existentes e seus valores permanecerão intocados, exceto que a ordem pode mudar.
Por conveniência, estou adicionando isso como um script no package.json
"scripts": { "ng": "ng", "start": "ng serve", "update-locale": "ngx-translate-extract -i ./src -o src/assets/locale/*.json --sort --format namespaced-json" },
Tudo o que descrevi pode ser encontrado reunido em um repositório aberto: valentinkononov / ngx-translate-angular
Espero que o material seja útil! Escreva código com prazer, escolha bibliotecas convenientes e faça projetos úteis!