Where can I find resources or tutorials for i18n js?

The best JavaScript i18n tutorials live inside the library docs themselves, including i18next.com's own guides plus framework-specific docs for react-i18next, vue-i18n, and next-intl, while i18next-scanner is a separate open-source tool that extracts translation keys into locale JSON files automatically.

Onde posso encontrar tutoriais de internacionalização (i18n) em JavaScript e o que faz o i18next-scanner?

Os melhores tutoriais de internacionalização (i18n) em JavaScript estão na própria documentação da biblioteca — i18next.com. Guias próprios, além de documentação específica para os frameworks react-i18next, vue-i18n e next-intl — porque nenhum curso de terceiros cobre todas as integrações de cada framework. O i18next-scanner é uma ferramenta de linha de comando independente e de código aberto que analisa arquivos de origem JavaScript, JSX e TypeScript em busca de chamadas de funções de tradução e extrai automaticamente as chaves para arquivos JSON de localização, substituindo o hábito propenso a erros de editar esses arquivos manualmente à medida que um aplicativo cresce.

Por que o material de aprendizado sobre internacionalização (i18n) em JavaScript parece tão disperso?

A documentação da biblioteca e as ferramentas de extração ficam em locais diferentes. i18next.com's A documentação explica os hooks, a inicialização e a pluralização, mas o i18next-scanner é um projeto de código aberto separado, mantido em seu próprio repositório GitHub e pacote npm, com sua própria referência de configuração — portanto, um tutorial que cobre apenas o núcleo do i18next ignora completamente a etapa de extração.
As vinculações de frameworks fragmentam ainda mais a busca. Um desenvolvedor React que busca um tutorial sobre i18next precisa da API useTranslation baseada em hooks do react-i18next, enquanto um desenvolvedor Vue precisa do guia da API Composition do vue-i18n e um desenvolvedor Angular precisa do fluxo de trabalho baseado em compilador do @angular/localize — a mesma configuração do i18next-scanner tem uma aparência diferente dependendo da sintaxe JSX ou de template que precisa ser analisada.
A extração e a gestão da tradução são tratadas como um único tópico, quando na verdade são dois. O i18next-scanner apenas gera arquivos JSON com chaves e valores padrão em inglês; ele não envia esses arquivos para um tradutor, não rastreia o status de conclusão nem gerencia formas plurais para os idiomas de destino — essa é uma camada separada, geralmente um sistema de gerenciamento de traduções.
APIs nativas do navegador são frequentemente misturadas em buscas por bibliotecas de internacionalização (i18n). A documentação da API Intl (Internationalization API) da MDN aborda a formatação de números, datas e plurais com reconhecimento de localidade, integrada ao próprio JavaScript, uma camada diferente e complementar a uma biblioteca de tradução de strings como o i18next.
As migrações de frameworks tornam os tutoriais mais antigos obsoletos. Guia escrito para o Next.js O Pages Router (next-i18next) não é migrado corretamente para o App Router (next-intl), portanto, uma pesquisa geralmente revela instruções de configuração conflitantes, dependendo da data de publicação.

As camadas de um caminho de aprendizado de i18n em JavaScript

Conceitos básicos de biblioteca — i18next.com A documentação própria abrange inicialização, namespaces e interpolação, e é o ponto de partida ideal, independentemente da estrutura utilizada.
A integração com frameworks — react-i18next, vue-i18n, @angular/localize ou next-intl — envolve a biblioteca principal no modelo de componentes do respectivo framework; após a inicialização, utilize a documentação específica da integração, e não um tutorial genérico do i18next.
Ferramenta de extração — o i18next-scanner examina o código-fonte em busca de chamadas de tradução e gera os arquivos JSON de localização que um código-fonte realmente inclui; seu próprio arquivo README e referência de configuração são a documentação principal para esta camada.
A entrega e a gestão da tradução — incluindo o envio do JSON extraído aos tradutores, o acompanhamento da conclusão e a manutenção da correção do plural em todos os idiomas — são questões distintas das mencionadas anteriormente e geralmente são gerenciadas por um sistema de gestão de traduções.

Como configurar o i18next-scanner para extrair chaves de tradução?

O i18next-scanner é executado como uma etapa de tempo de compilação ou pré-commit, em vez de dentro do aplicativo em execução, portanto, a configuração ocorre uma única vez e permanece praticamente sem intervenção posterior.

Instale o scanner como uma dependência de desenvolvimento - adicione o i18next-scanner via npm ou yarn junto com os pacotes i18next e react-i18next (ou vue-i18n) já presentes no projeto.
Crie um arquivo de configuração do scanner - i18next-scanner.config.js define os padrões glob do arquivo de entrada, o caminho de saída para o JSON gerado e os separadores de chave e namespace que o projeto utiliza.
Configure o analisador léxico para a sintaxe do seu framework - um analisador léxico JSX é necessário para analisar corretamente o componente Trans do React e as chamadas useTranslation; os templates do Vue e do Angular precisam de suas próprias configurações de analisador léxico para que as chaves dentro de diretivas e pipes não sejam perdidas.
Execute o scanner e revise o JSON gerado - cada chave extraída é armazenada em um arquivo JSON de localidade com a string de origem capturada como seu valor padrão (defaultValue), que se torna o valor padrão em inglês até que uma tradução seja encontrada.
Adicione a verificação ao CI para que a extração nunca se desvie do código - executar o i18next-scanner como um gancho de pré-commit ou etapa de CI mantém os arquivos JSON sincronizados com as novas chamadas t() e Trans automaticamente, em vez de depender de alguém se lembrar de verificar novamente.

Essa abordagem é adequada para equipes que...

Você está configurando a extração de chaves de tradução pela primeira vez em um código React, Vue ou Angular que já utiliza o i18next ou uma vinculação específica do framework?
Atualmente, mantemos manualmente os arquivos JSON de configuração de localização e desejamos uma verificação automatizada para substituir a entrada manual de chaves.
É necessário estabelecer uma convenção consistente para nomenclatura de chaves e espaços de nomes antes que uma base de código seja escalada para além de uma ou duas linguagens de destino.
Estamos integrando novos engenheiros que precisam de um ponto de partida padrão que abranja a documentação principal do i18next, uma estrutura de integração e ferramentas de extração.

Lista de verificação para avaliação: perguntas a fazer antes de criar um fluxo de trabalho de extração.

O analisador léxico do seu scanner é compatível com a sintaxe JSX ou de modelo do seu framework?
Um projeto React precisa de um analisador léxico compatível com JSX que reconheça o componente Trans, e não apenas chamadas simples a t(); Vue e Angular precisam de suas próprias configurações equivalentes.

O scanner mantém uma versão alternativa em inglês para cada chave extraída?
Confirme se o valor padrão (defaultValue) foi preenchido com a string de origem, em vez de ficar em branco, pois um valor de fallback em branco significa que a ausência de tradução será exibida como nada em vez de inglês.

A remoção de chaves não utilizadas alguma vez excluirá uma chave que esteja em processo de tradução?
A opção removeUnusedKeys do i18next-scanner pode remover chaves que não são mais referenciadas no código — verifique se essa configuração não está apagando chaves que um tradutor ainda não terminou de processar.

Para onde vão os arquivos JSON extraídos após a execução da verificação?
Antes de automatizar essa etapa na CI, decida se os arquivos gerados serão enviados diretamente para o repositório ou encaminhados por meio de um conector para uma plataforma de tradução.

Como o Smartling se encaixa depois que as chaves i18n do JavaScript são extraídas?

O i18next-scanner e suas bibliotecas de integração resolvem a extração — transformando o código-fonte em arquivos JSON de localização —, mas nenhuma delas traduz esses arquivos ou mantém as formas plurais corretas em todos os idiomas. O analisador JSON do Smartling lê diretamente as chaves e matrizes aninhadas geradas pelo i18next-scanner, sem exigir que o arquivo seja achatado primeiro. Especificamente para plurais, o formato de chave de plural do i18next não é lido nativamente por ferramentas baseadas em ICU. Por isso, a Smartling criou uma extensão ICU MessageFormat para i18next que resolve esse problema sem a necessidade de uma conversão manual (Central de Ajuda da Smartling, ICU MessageFormat). Assim que o JSON extraído chega a um repositório, o conector GitHub da Smartling pode monitorar esse branch e iniciar automaticamente um fluxo de trabalho de tradução em chaves novas ou alteradas, retornando o JSON traduzido como uma solicitação pull em vez de um upload manual de arquivo.