@intlayer/docs 9.4.2 → 9.4.3

package/blog/pt/date_time_number_formatting_locales.md

@@ -0,0 +1,216 @@
+---
+createdAt: 2026-09-02
+updatedAt: 2026-09-02
+title: "Formatando datas e números por idioma com Intl"
+description: Você provavelmente não precisa de uma biblioteca externa de formatação. Como o Intl lida com datas, números, moedas e listas por localidade, o custo de cache e o bug de timezone em produção.
+keywords:
+  - formatar data por localidade
+  - Intl.DateTimeFormat
+  - Intl.NumberFormat
+  - toLocaleDateString
+  - formato moeda locale
+  - formato tempo relativo
+slugs:
+  - blog
+  - date-time-number-formatting-locales
+author: aymericzip
+---
+
+# Formatando datas e números por idioma com Intl
+
+Traduzir strings de texto é apenas a metade visível da internacionalização. A outra metade, responsável pela maioria dos relatos de bugs, é a formatação: um usuário na Alemanha vendo `1,234.56` em vez de `1.234,56`, um usuário no Japão vendo `08/02/2026` e lendo como agosto, ou uma data que renderiza diferente no servidor e no navegador, derrubando a página na hidratação do React.
+
+Nada disso requer bibliotecas externas. A API nativa `Intl` já está presente em qualquer ambiente moderno de execução.
+
+## Sumário
+
+<TOC/>
+
+## Comece deletando suas funções helper caseiras de data
+
+Quase todo repositório possui uma função `formatDate` escrita antes de qualquer planejamento para internacionalização. Ela fixa uma ordem arbitrária, um separador e quase sempre nomes de meses em inglês.
+
+```ts
+// O código que você deve apagar:
+const formatDate = (d: Date) =>
+  `${d.getMonth() + 1}/${d.getDate()}/${d.getFullYear()}`;
+```
+
+`Intl.DateTimeFormat` a substitui por completo e entrega o resultado correto para cada localidade:
+
+```ts
+new Intl.DateTimeFormat("de-DE", { dateStyle: "long" }).format(date);
+// "2. August 2026"
+new Intl.DateTimeFormat("ja-JP", { dateStyle: "long" }).format(date);
+// "2026年8月2日"
+```
+
+O mesmo vale para valores numéricos. `toFixed(2)` produz `1234.56` em qualquer lugar, o que é incorreto na maior parte da Europa.
+
+## O que a API `Intl` engloba
+
+| API                       | Quando utilizar                                            |
+| :------------------------ | :--------------------------------------------------------- |
+| `Intl.DateTimeFormat`     | Datas e horários, com presets `dateStyle` / `timeStyle`    |
+| `Intl.NumberFormat`       | Decimais, moedas, porcentagens, unidades, notação compacta |
+| `Intl.RelativeTimeFormat` | "há 3 dias", "em 2 horas"                                  |
+| `Intl.ListFormat`         | "a, b e c" versus "a, b, and c"                            |
+| `Intl.PluralRules`        | Identificar categorias de plural para números              |
+| `Intl.Collator`           | Ordenação alfabética linguística correta de strings        |
+
+`Intl.Collator` é o mais esquecido. Um simples `array.sort()` sobre strings utiliza a ordenação de code points do Unicode, fazendo caracteres com acentos ficarem depois de `z` e colocando o `ö` sueco na posição errada. Sempre que ordenar listas visíveis para os usuários, use um collator.
+
+```ts
+["zebra", "édouard", "apple"].sort(new Intl.Collator("pt").compare);
+// ["apple", "édouard", "zebra"]
+```
+
+## Prefira presets a opções montadas manualmente
+
+`dateStyle` e `timeStyle` deixam o locale decidir a ordem e os separadores lógicos. Especificar `year`, `month` e `day` separadamente dá um controle raramente desejável, pois a ordem correta varia de acordo com a região e você acaba sobrescrevendo os dados do CLDR com suas próprias suposições.
+
+```ts
+// A localidade decide a estrutura:
+new Intl.DateTimeFormat(locale, { dateStyle: "medium" }).format(d);
+
+// Você forçou a estrutura e estará incorreto em outras regiões:
+new Intl.DateTimeFormat(locale, {
+  year: "numeric",
+  month: "2-digit",
+  day: "2-digit",
+}).format(d);
+```
+
+Defina componentes explícitos apenas quando o layout visual exigir rigorosamente uma largura fixa, como em uma coluna estreita de tabela.
+
+## Instanciar formatadores é custoso
+
+Este é o detalhe de desempenho mais crítico. Criar um `Intl.NumberFormat` carrega dados pesados de localidade na memória, sendo um processo muito mais custoso do que a chamada subsequente a `.format()`. Fazer isso em um loop de renderização sobre mil linhas cria um gargalo expressivo.
+
+```ts
+// Recria o formatador a cada linha:
+rows.map((r) => new Intl.NumberFormat(locale).format(r.total));
+
+// Cria uma única vez e reutiliza:
+const nf = new Intl.NumberFormat(locale);
+rows.map((r) => nf.format(r.total));
+```
+
+`toLocaleDateString()` e `toLocaleString()` escondem o mesmo problema: cada execução cria um novo formatador. Funcionam para um valor pontual, mas são péssimos para listas.
+
+Armazene-os em cache com base na combinação de localidade e opções:
+
+```ts
+const cache = new Map<string, Intl.NumberFormat>();
+
+const getNumberFormat = (
+  locale: string,
+  options: Intl.NumberFormatOptions = {}
+) => {
+  const key = `${locale}:${JSON.stringify(options)}`;
+  let formatter = cache.get(key);
+  if (!formatter) {
+    formatter = new Intl.NumberFormat(locale, options);
+    cache.set(key, formatter);
+  }
+  return formatter;
+};
+```
+
+## O bug de fuso horário que só surge em produção
+
+Esse problema já custou tardes inteiras de trabalho. O servidor renderiza a data no SSR, o navegador hidrata o componente no cliente, e o React acusa um erro de hydration mismatch porque os dois ambientes produziram textos conflitantes.
+
+A causa: `Intl.DateTimeFormat` assume o fuso horário padrão do sistema quando nenhum é especificado. Seu servidor de produção opera em UTC, enquanto sua máquina de desenvolvimento local está em outro fuso. Com isso, o erro fica invisível localmente e só aparece em produção.
+
+```ts
+// Servidor em UTC e navegador em UTC+9 divergem. Erro de hidratação.
+new Intl.DateTimeFormat(locale, { dateStyle: "short" }).format(d);
+
+// Ambos se alinham de forma consistente:
+new Intl.DateTimeFormat(locale, { dateStyle: "short", timeZone: "UTC" }).format(
+  d
+);
+```
+
+Três soluções viáveis:
+
+- **Fixar o fuso horário** no servidor e passá-lo explicitamente. Seguro e determinístico, mas todos veem horário em UTC.
+- **Renderizar apenas no cliente**, com um placeholder estável durante o SSR. Preciso para cada usuário, com um leve salto visual.
+- **Salvar o fuso do usuário** e passá-lo em ambos os lados. A melhor experiência, exigindo um pouco mais de infraestrutura.
+
+Qualquer que seja sua escolha, informe sempre `timeZone` de forma explícita em qualquer data renderizada tanto no servidor quanto no cliente. Uma data sem fuso explícito é uma data com dois valores contraditórios.
+
+## Moeda precisa de moeda, não de locale
+
+Localidade e moeda são conceitos independentes. `fr-FR` não significa euro: um usuário na França pode perfeitamente estar analisando uma fatura em dólares americanos.
+
+```ts
+new Intl.NumberFormat("fr-FR", { style: "currency", currency: "USD" }).format(
+  1234.5
+);
+// "1 234,50 $US"
+```
+
+O locale governa os separadores, o agrupamento de dígitos e a posição do símbolo. A moeda vem dos seus dados. Presumir uma a partir da outra gera inconsistências financeiras.
+
+Fique atento também a `currencyDisplay`. Em interfaces com múltiplas moedas que compartilham o símbolo de cifrão, `"code"` elimina a ambiguidade entre dólares americanos, canadenses e australianos.
+
+## Tempo relativo soa mais natural que tempo absoluto
+
+Para ocorrências recentes, "há 2 horas" é muito mais claro do que um timestamp bruto, e `Intl.RelativeTimeFormat` lida com isso de maneira nativa.
+
+```ts
+new Intl.RelativeTimeFormat("pt", { numeric: "auto" }).format(-1, "day");
+// "ontem"
+```
+
+`numeric: "auto"` entrega "ontem" em vez de "há 1 dia". Sem isso, você recebe a expressão puramente numérica, que soa artificial.
+
+## O que o Intlayer adiciona
+
+O Intlayer encapsula essas APIs em utilitários com cache embutido para poupar o gerenciamento manual do Map acima, e aplica a localidade ativa como padrão sem obrigar você a passá-la a cada chamada.
+
+```ts
+import {
+  number,
+  currency,
+  date,
+  relativeTime,
+  units,
+  compact,
+  list,
+} from "intlayer";
+
+number(1234.5); // "1.234,5"
+currency(1234.5, { currency: "EUR" }); // "1.234,50 €"
+date(new Date(), "short");
+relativeTime(now, twoHoursAgo, { unit: "hour", numeric: "auto" }); // "há 2 horas"
+units(5, { unit: "kilometer", unitDisplay: "long" }); // "5 quilômetros"
+compact(1200); // "1,2 mil"
+list(["maçã", "banana", "laranja"]); // "maçã, banana e laranja"
+```
+
+A função `date()` também suporta presets (`"short"`, `"long"`, `"dateOnly"`, `"timeOnly"`, `"full"`), eliminando a necessidade de objetos de opções nos casos comuns. Equivalentes para React e Vue estão disponíveis como hooks e composables, resolvendo a localidade ativa diretamente do contexto.
+
+Trata-se de uma camada ágil de cache e resolução padrão sobre as APIs da plataforma. A formatação em si continua sendo 100% `Intl`. Consulte as assinaturas completas na [documentação de formatadores](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/formatters.md).
+
+## Erros comuns
+
+- **`toLocaleDateString()` sem definir locale.** Usa o locale do ambiente hospedeiro, que no servidor reflete a imagem do contêiner.
+- **Formatar dentro de laços de repetição.** O custo reside na instanciação do formatador. Crie uma vez e reutilize.
+- **Omitir `timeZone` em datas isomórficas.** Gera erros de hidratação impossíveis de reproduzir localmente.
+- **Deduzir a moeda a partir do locale.** `fr-FR` não garante valores em euros.
+- **Chamar `sort()` simples em textos de interface.** Use sempre `Intl.Collator`.
+- **Escrever nomes de meses ou dias fixos no código.** O CLDR já armazena tudo em todas as línguas.
+- **Manter `numeric: "always"` em tempo relativo.** Gera "há 1 dia" onde todo idioma possui uma palavra como ontem.
+
+## Para se aprofundar
+
+- [Formatadores e utilitários de locale: `number`, `currency`, `date`, `relativeTime`, `list`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/formatters.md)
+- [Referência de configuração](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/configuration.md)
+- [Relatórios de benchmark entre frameworks](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/benchmark/index.md)
+- [Adaptador de compatibilidade react-intl](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/compat/react-intl.md)
+- [Formato de mensagens ICU: plurais, select e skeletons numéricos](https://github.com/aymericzip/intlayer/blob/main/docs/blog/pt/icu_message_format.md)
+- [Como testar traduções, cobrindo formatadores e plurais](https://github.com/aymericzip/intlayer/blob/main/docs/blog/pt/i18n_testing_strategies.md)
+- [O que a internacionalização realmente abrange](https://github.com/aymericzip/intlayer/blob/main/docs/blog/pt/what_is_internationalization.md)

package/blog/pt/detecting_missing_translations.md

@@ -0,0 +1,202 @@
+---
+createdAt: 2026-09-02
+updatedAt: 2026-09-02
+title: "Como detectar traduções ausentes antes dos seus usuários"
+description: Traduções ausentes falham em silêncio. Por que o fallback as esconde, as quatro camadas de detecção que funcionam e como quebrar o build em chaves não traduzidas.
+keywords:
+  - encontrar traduções ausentes
+  - chaves de tradução ausentes
+  - auditoria i18n
+  - strings não traduzidas
+  - cobertura de tradução
+  - lint i18n
+slugs:
+  - blog
+  - detecting-missing-translations
+author: aymericzip
+---
+
+# Como detectar traduções ausentes antes dos seus usuários
+
+Uma tradução ausente quase nunca lança um erro explícito. Dependendo da sua configuração, ela exibe o texto em inglês para um usuário no Japão, ou imprime `checkout.summary.total` diretamente na tela em produção. Ambas as situações chegam ao ar, passam pela revisão de código sem alertas e acabam sendo descobertas por um cliente antes de você.
+
+## Sumário
+
+<TOC/>
+
+## Isso se aplica independentemente da biblioteca que você usa
+
+Nada do que está aqui é exclusivo de uma stack específica. As camadas de detecção funcionam da mesma forma no i18next, react-i18next, next-intl, react-intl, vue-i18n, next-translate ou Lingui, porque todas resolvem chaves da mesma forma e falham pelo mesmo motivo.
+
+As ferramentas também são portáveis. Se suas mensagens estão hoje em catálogos JSON, o [plugin Sync JSON](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/plugins/sync-json.md) aponta o Intlayer para esses arquivos, disponibilizando comandos de auditoria, preenchimento e teste sem exigir migração de conteúdo ou alteração de imports:
+
+```ts fileName="intlayer.config.ts"
+import { syncJSON } from "@intlayer/sync-json-plugin";
+
+const config = {
+  plugins: [
+    syncJSON({
+      source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
+      format: "i18next", // ou "icu" para next-intl / react-intl
+    }),
+  ],
+};
+
+export default config;
+```
+
+Se desejar manter a API em tempo de execução inalterada, os [adaptadores de compatibilidade](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/compat/index.md) criam aliases para `useTranslation`, `$t` e funções correspondentes no nível do empacotador. Em qualquer caso, encare os comandos abaixo como uma implementação prática do conceito, não como uma obrigatoriedade.
+
+## Por que elas são invisíveis
+
+Toda biblioteca de i18n resolve chaves pela mesma cadeia: busca no locale ativo, recorre ao locale padrão por fallback e, se isso falhar, retorna a própria chave literal. Essa última etapa é onde mora o perigo. Não há erro, não há aviso em produção e nenhum teste falha, porque nada no pipeline considera uma chave ausente como um evento anormal.
+
+O fallback piora o cenário em vez de ajudar. Uma página que renderiza silenciosamente em inglês parece perfeita para um desenvolvedor anglófono e para todos os testes automatizados. O bug só é perceptível para o usuário que não compreende o resultado.
+
+Assim, a questão não é "como lidar com traduções ausentes em tempo de execução". É "como tornar impossível fazer o merge de uma tradução ausente".
+
+## As quatro camadas onde você pode pegá-las
+
+Cada camada detecta o que as outras deixam passar. Você vai querer usar mais de uma.
+
+| Camada         | Detecta                                       | Deixa passar                                  |
+| :------------- | :-------------------------------------------- | :-------------------------------------------- |
+| Tipos          | Chaves que não existem de forma alguma        | Chave existente, mas sem tradução em `ja`     |
+| Linter         | Strings literais nunca enviadas para tradução | Chaves ausentes em um catálogo                |
+| Auditoria      | Cobertura de idiomas em cada chave declarada  | Textos que nunca foram marcados para tradução |
+| Testes de tela | Chaves resolvidas mas renderizadas errado     | Tudo que não for coberto por um teste         |
+
+A lacuna mais comum nas equipes está na terceira linha: elas sabem que suas chaves são válidas, mas nada confere se todos os dezoito idiomas possuem valor atribuído.
+
+## Camada 1: torne a chave um tipo, não uma string solta
+
+`t("checkout.summry.total")` é um erro de digitação que compila normalmente. Se as chaves forem strings puras, cada renomeação representa um risco em produção e cada exclusão deixa chaves órfãs.
+
+Chaves tipadas transformam isso em erro de compilação. O `react-i18next` oferece suporte via declaration merging, o `next-intl` infere da estrutura de mensagens, o Lingui gera IDs do texto original e o Intlayer cria tipos estritos dos arquivos de declaração. Todos cumprem o papel; o que muda é a complexidade de configuração.
+
+Essa camada é necessária, mas não suficiente. Os tipos descrevem a estrutura do catálogo padrão. Eles não garantem se o coreano possui valor preenchido para aquela chave.
+
+## Camada 2: faça lint das strings que nunca viraram chaves
+
+A tradução que você não encontra frequentemente é aquela que nunca foi externalizada. Um texto hardcoded em um componente é invisível para qualquer auditoria de catálogo, porque para as ferramentas essa string simplesmente não existe.
+
+O plugin ESLint do Intlayer resolve isso com `no-raw-text`, acompanhado de `no-unused-content` para a situação inversa: conteúdo declarado que não é mais lido por nada.
+
+```js fileName="eslint.config.mjs"
+import intlayer from "@intlayer/eslint-plugin";
+
+export default [
+  intlayer.configs.recommended,
+  {
+    rules: {
+      "@intlayer/no-raw-text": "error",
+      "@intlayer/no-unused-content": "warn",
+    },
+  },
+];
+```
+
+`no-unused-content` evita que catálogos cresçam descontroladamente. Chaves mortas não quebram o código, mas inflam desnecessariamente os custos com agências de tradução. Confira a lista completa na [documentação do plugin ESLint](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/eslint.md).
+
+## Camada 3: auditar a cobertura de idiomas
+
+Esta é a camada que responde à pergunta central. O Intlayer a fornece como um comando de CLI:
+
+```bash packageManager="npm"
+npx intlayer content test
+```
+
+Ele examina os idiomas configurados e os dicionários declarados, relatando quais chaves estão ausentes em quais idiomas e em qual arquivo.
+
+Um detalhe indispensável antes de conectar em suas esteiras: **a CLI imprime um relatório mas finaliza com código zero.** Se você colocar isso na esteira esperando que quebre a compilação, terá um build verde com um bloco de texto que ninguém lerá. Para bloqueio real, utilize a API programática mostrada abaixo.
+
+## Camada 4: asserções explícitas na suíte de testes
+
+`listMissingTranslations()` retorna a mesma auditoria em formato de dados, ideal para construir um gate de build.
+
+```ts fileName="i18n.test.ts"
+/* @vitest-environment node */
+import { listMissingTranslations } from "intlayer/cli";
+import { describe, expect, it } from "vitest";
+
+describe("translations", () => {
+  it("não possui locales obrigatórios ausentes", async () => {
+    const result = await listMissingTranslations();
+
+    if (result.missingRequiredLocales.length > 0) {
+      console.log(result.missingTranslations);
+    }
+
+    expect(result.missingRequiredLocales).toHaveLength(0);
+  });
+});
+```
+
+Três campos são retornados com distinções fundamentais:
+
+- `missingTranslations`: detalhamento por chave sobre quais idiomas faltam e em qual arquivo. É isso que você exibe se o teste falhar.
+- `missingLocales`: a união de idiomas faltantes em todas as chaves.
+- `missingRequiredLocales`: restrito às `requiredLocales` da sua configuração, ou todos os idiomas caso não tenha definido o parâmetro.
+
+## `requiredLocales` é o ajuste que torna o gate sustentável
+
+Oferecer suporte a dezoito idiomas não significa que todos os dezoito precisem estar 100% prontos para você realizar um deploy. A maioria das equipes possui uma camada crítica que impede o lançamento e uma camada flexível que é completada gradualmente.
+
+```ts fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [
+      Locales.ENGLISH,
+      Locales.FRENCH,
+      Locales.JAPANESE,
+      Locales.POLISH,
+    ],
+    requiredLocales: [Locales.ENGLISH, Locales.FRENCH],
+    defaultLocale: Locales.ENGLISH,
+  },
+};
+
+export default config;
+```
+
+Sem `requiredLocales`, todo idioma configurado é obrigatório e seu build permanecerá vermelho até que a última tradução seja entregue. É assim que as equipes acabam desligando a checagem por completo, o que é pior do que não tê-la.
+
+## Encontrando as omissões já em produção
+
+As camadas acima previnem novos problemas. Para uma aplicação já lançada, duas táticas funcionam muito bem.
+
+**Pseudolocalização.** Utilize um idioma fictício no qual todas as strings sejam modificadas, por exemplo `[!!! Ĉĥéçķöũţ !!!]`. Qualquer elemento que continue em inglês normal está hardcoded. Isso revela em dez minutos o que uma auditoria de catálogo não consegue ver por projeto.
+
+**Rastrear o próprio site.** Se você serve URLs localizadas, faça requisições a uma amostra de páginas por idioma e busque no HTML strings do idioma padrão. Uma página sob `/ja/` contendo "Add to cart" indica uma tradução ausente ou um fallback inesperado.
+
+```bash
+curl -s https://example.com/ja/checkout | grep -c "Add to cart"
+```
+
+## Preenchendo as lacunas
+
+Após localizar os pontos faltantes, `intlayer fill` preenche as entradas vazias, e a opção `autoFill` pode gerar arquivos por idioma conforme o conteúdo é declarado. Veja [autoFill](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/autoFill.md).
+
+Sejamos claros: traduções preenchidas automaticamente transformam uma falta _visível_ em uma falta _invisível_. A chave agora possui valor, o teste fica verde, mas nenhum humano leu aquele texto. Use isso para desbloquear entregas e direcione os textos importantes para revisão humana. É um suporte inicial, não um resultado definitivo.
+
+## Erros comuns
+
+- **Tratar fallback como garantia de segurança.** É apenas uma saída de emergência para renderização, não uma proteção. Uma página silenciosamente em inglês é um bug que não emite alertas.
+- **Confiar no relatório da CLI para barrar a CI.** `intlayer content test` sai com código zero. Use asserções em testes automatizados.
+- **Exigir todos os idiomas como obrigatórios.** O controle é desativado na primeira vez que atrasar um lançamento.
+- **Auditar catálogos mas ignorar a tela renderizada.** Textos hardcoded são invisíveis em catálogos por definição.
+- **Testar somente o idioma padrão.** O único idioma que com certeza nunca estará ausente.
+- **Concluir o fluxo apenas com IA.** Auditoria no verde com textos crus jamais revisados.
+
+## Para se aprofundar
+
+- [Testar seu conteúdo: auditoria CLI, API programática e asserções de UI](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/testing.md)
+- [Regras do plugin ESLint, incluindo `no-raw-text` e `no-unused-content`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/eslint.md)
+- [autoFill: geração de arquivos de declaração por locale](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/autoFill.md)
+- [Referência de configuração: `locales`, `requiredLocales`, `defaultLocale`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/configuration.md)
+- [Relatórios de benchmark entre frameworks](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/benchmark/index.md)
+- [Adaptador de compatibilidade i18next](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/compat/i18next.md)
+- [O que a internacionalização realmente engloba](https://github.com/aymericzip/intlayer/blob/main/docs/blog/pt/what_is_internationalization.md)
+- [i18n por componente vs centralizada](https://github.com/aymericzip/intlayer/blob/main/docs/blog/pt/per-component_vs_centralized_i18n.md)

package/blog/pt/i18n_in_ci_cd_pipelines.md

@@ -0,0 +1,247 @@
+---
+createdAt: 2026-09-02
+updatedAt: 2026-09-02
+title: "Automatizando traduções em CI/CD sem entregar textos ruins"
+description: Três locais para automatizar i18n, pre-push, pull request e runtime. Como barrar um build por cobertura, preencher com segurança e evitar o loop de commits no CI.
+keywords:
+  - automatizar traduções ci
+  - i18n ci cd
+  - github actions traduções
+  - husky pre-push
+  - localização contínua
+  - pipeline de tradução
+slugs:
+  - blog
+  - i18n-in-ci-cd-pipelines
+author: aymericzip
+---
+
+# Automatizando traduções em CI/CD sem entregar textos ruins
+
+A tradução manual não resiste ao ritmo acelerado de lançamentos. Alguém adiciona uma string na sexta-feira, a exportação só ocorre no próximo sprint, e três outros idiomas já estão defasados. Automatizar o fluxo é simples. Automatizar sem publicar silenciosamente conteúdo gerado por máquina para seus usuários é a parte que realmente exige atenção.
+
+## Sumário
+
+<TOC/>
+
+## Você não precisa migrar para automatizar
+
+Os formatos de pipeline descritos abaixo são independentes de biblioteca, assim como as ferramentas. Se suas mensagens residem em catálogos JSON para i18next, next-intl, react-intl, vue-i18n ou next-translate, o [plugin Sync JSON](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/plugins/sync-json.md) lê e escreve esses arquivos diretamente no local:
+
+```ts fileName="intlayer.config.ts"
+import { syncJSON } from "@intlayer/sync-json-plugin";
+
+const config = {
+  plugins: [
+    syncJSON({
+      source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
+      format: "i18next", // ou "icu" para next-intl / react-intl
+    }),
+  ],
+};
+
+export default config;
+```
+
+Sua aplicação continua importando o que sempre importou. Os jobs de CI então preenchem e protegem seus catálogos existentes, e o diff exibido ao revisor é uma simples alteração em `locales/fr/checkout.json`, e não uma migração estrutural. Há também o [plugin Sync PO](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/plugins/sync-po.md) para fluxos gettext e [adaptadores de compatibilidade](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/compat/index.md) para manter sua API em tempo de execução inalterada.
+
+## Separe o bloqueio (gate) do preenchimento (fill)
+
+Duas tarefas distintas são constantemente confundidas.
+
+Um **gate** é uma verificação que falha. Ele determina que esta compilação não deve ser lançada porque idiomas obrigatórios estão ausentes. Ele não escreve nenhum arquivo.
+
+Um **fill** é uma mutação. Ele gera as traduções ausentes e realiza o commit delas. Ele nunca quebra um build.
+
+Executar apenas o fill significa que nada é bloqueado e textos gerados por máquina chegam à produção sem revisão. Executar apenas o gate faz com que o build fique vermelho e um humano precise intervir a cada push. A maioria das equipes precisa de ambos acionados em momentos distintos: fill em pull requests, gate ao realizar o merge na branch de lançamento.
+
+## Onde a automação pode residir
+
+| Etapa          | Gatilho   | Indicado para                          | Custo                                            |
+| :------------- | :-------- | :------------------------------------- | :----------------------------------------------- |
+| Hook pre-push  | Git local | Feedback rápido, zero minutos de CI    | Roda na máquina do dev com sua própria chave API |
+| Pull request   | Job de CI | Revisão pré-merge, segredos protegidos | Minutos de CI mais chamadas de modelo por PR     |
+| Branch release | Job de CI | Bloqueio estrito de cobertura          | Econômico, sem chamadas a modelos                |
+| Runtime        | CMS       | Mudanças de texto sem recompilar       | Dependência de serviço hospedado                 |
+
+## Pre-push: o ciclo mais ágil
+
+O Husky executa o preenchimento antes do código sair da máquina local, fazendo com que as traduções cheguem no mesmo push em que as novas strings foram adicionadas.
+
+```bash fileName=".husky/pre-push"
+npx intlayer build
+npx intlayer fill --unpushed --mode complete
+```
+
+`--unpushed` restringe a execução ao conteúdo que ainda não foi enviado ao repositório remoto, evitando lentidão a cada push. `--mode complete` preenche apenas o que está faltando sem reescrever entradas que já possuem valor, assegurando que uma tradução revisada nunca seja sobrescrita.
+
+Em um monorepo, delimite o escopo de cada aplicação:
+
+```bash fileName=".husky/pre-push"
+npx intlayer build --base-dir ./app1
+npx intlayer fill --base-dir ./app1 --unpushed --mode complete
+npx intlayer build --base-dir ./app2
+npx intlayer fill --base-dir ./app2 --unpushed --mode complete
+```
+
+A desvantagem é evidente: cada desenvolvedor precisa de uma chave de API, e o custo recai sobre quem faz o push. Por isso, a maioria dos times migra essa etapa para o CI à medida que a equipe cresce.
+
+## Pull request: preencher onde a revisão acontece
+
+O mesmo fluxo no GitHub Actions, delimitado pelo diff:
+
+```yaml fileName=".github/workflows/intlayer-translate.yml"
+name: Intlayer Auto-Fill
+on:
+  pull_request:
+    branches: ["main"]
+
+permissions:
+  contents: write
+  pull-requests: write
+
+concurrency:
+  group: "autofill-${{ github.ref }}"
+  cancel-in-progress: true
+
+jobs:
+  autofill:
+    runs-on: ubuntu-latest
+    env:
+      AI_PROVIDER: openai
+      AI_MODEL: gpt-5-mini
+      AI_API_KEY: ${{ secrets.AI_API_KEY }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: true
+          fetch-depth: 0
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - run: npm install
+      - run: npx intlayer build
+      - run: npx intlayer fill --git-diff --mode complete --provider $AI_PROVIDER --model $AI_MODEL --api-key $AI_API_KEY
+      - name: Commit
+        run: |
+          if [ -n "$(git status --porcelain)" ]; then
+            git config --local user.email "action@github.com"
+            git config --local user.name "GitHub Action"
+            git add .
+            git commit -m "chore: auto-fill missing translations [skip ci]"
+            git push origin HEAD:${{ github.head_ref }}
+          fi
+```
+
+Quatro detalhes são cruciais aqui:
+
+- **`fetch-depth: 0`** é indispensável para o funcionamento de `--git-diff`. Um clone raso não possui base de comparação e nada é preenchido silenciosamente.
+- **`[skip ci]` na mensagem de commit** impede que o workflow entre em loop infinito. Sem isso, o job commita, aciona uma nova execução, que commita novamente, esgotando o limite de CI durante a noite.
+- **`concurrency` com `cancel-in-progress`** impede que pushes simultâneos tentem alterar os mesmos arquivos ao mesmo tempo.
+- **`--git-diff`** restringe o preenchimento às alterações do PR. Se for omitido, todo o catálogo será retraduzido em cada execução.
+
+As traduções chegam como um commit na branch do PR, permitindo que o revisor inspecione o diff. Essa é a grande vantagem em relação a rodar o preenchimento após o merge.
+
+## Branch de release: o gate de validação
+
+O gate não requer acesso a modelos de IA e deve ser rápido.
+
+```yaml fileName=".github/workflows/ci.yml"
+- run: npm run test:i18n
+```
+
+Apoiado por um teste com asserções explícitas de cobertura em vez de simples relatórios no terminal:
+
+```ts fileName="i18n.test.ts"
+import { listMissingTranslations } from "intlayer/cli";
+
+test("não possui locales obrigatórios ausentes", async () => {
+  const result = await listMissingTranslations();
+  if (result.missingRequiredLocales.length > 0) {
+    console.log(result.missingTranslations);
+  }
+  expect(result.missingRequiredLocales).toHaveLength(0);
+});
+```
+
+`npx intlayer content test` imprime um relatório mas sai com código zero, portanto apenas informa sem interromper a esteira. Use-o localmente; use a asserção no CI. Mais detalhes em [detectar traduções ausentes](https://github.com/aymericzip/intlayer/blob/main/docs/blog/pt/detecting_missing_translations.md).
+
+## `requiredLocales` torna o gate sustentável
+
+Um gate que exija todas as dezoito línguas completas trava qualquer entrega até que o idioma mais lento fique pronto, acabando por ser desativado em menos de um mês.
+
+```ts fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    requiredLocales: [Locales.ENGLISH],
+    defaultLocale: Locales.ENGLISH,
+  },
+};
+
+export default config;
+```
+
+Declare as línguas atendidas e defina como obrigatórias apenas as que realmente devem bloquear um deploy. O restante é completado de modo assíncrono sem reter os lançamentos.
+
+## Gerenciando traduções fora do repositório
+
+A outra abordagem consiste em manter um idioma base no código e administrar os demais remotamente via CMS com Live Sync. As alterações de texto não exigem novo build, separando o ciclo de edição do ritmo de deploys de código.
+
+```ts fileName="intlayer.config.ts"
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.SPANISH, Locales.FRENCH],
+    requiredLocales: [Locales.ENGLISH],
+    defaultLocale: Locales.ENGLISH,
+  },
+  editor: {
+    clientId: process.env.INTLAYER_CLIENT_ID,
+    clientSecret: process.env.INTLAYER_CLIENT_SECRET,
+    liveSync: true,
+  },
+};
+
+export default config;
+```
+
+Essa solução é ideal para equipes onde profissionais não técnicos cuidam dos textos. Trata-se de uma troca: ganha-se autonomia editorial mas perde-se a propriedade de que um checkout do git reflete fielmente o que o app renderiza. Detalhes na [documentação do CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/intlayer_CMS.md).
+
+Lembre-se de que `clientSecret` é uma credencial do servidor. Deve permanecer nos segredos do CI e nas variáveis de ambiente do backend, nunca exposta em bundles de cliente.
+
+## A limitação real
+
+Tudo o que foi exposto automatiza a _cobertura_, não a _qualidade_. Um preenchimento automático transforma uma ausência explícita em um texto presente sem revisão: o teste passa porque a chave tem valor, mas ninguém o leu.
+
+Isso é admissível em ferramentas internas, changelogs ou idiomas em fase beta. Não é tolerável em páginas de preços, termos legais ou avisos de falha no pagamento. Encaminhe essas áreas para revisão humana e utilize `--mode complete` para nunca sobrescrever strings já revisadas.
+
+Forneça contexto ao modelo para que o resultado mantenha a coerência:
+
+```ts
+ai: {
+  applicationContext: "App de faturamento B2B. Tom formal. Nunca traduzir o nome do produto.",
+}
+```
+
+## Erros comuns
+
+- **Esquecer `[skip ci]` no auto-commit.** O job se reexecuta em loop indefinidamente.
+- **Clone raso com `--git-diff`.** Sem base de diff, nada é preenchido e nenhum erro é emitido.
+- **Preencher todo o catálogo a cada execução.** Limite com `--git-diff` ou `--unpushed` para controlar a conta.
+- **Usar o relatório da CLI como gate.** Ele encerra sempre com código 0.
+- **Tornar todas as línguas obrigatórias.** O gate é desativado no primeiro deploy bloqueado.
+- **Um job de fill sem gate em lugar nenhum.** Nada falha e textos crus de IA vão direto para a produção.
+- **Chaves de API de modelos no repositório.** Devem ficar nos segredos do CI, assim como o `clientSecret`.
+
+## Para se aprofundar
+
+- [CI/CD: autogeração de traduções com Husky, GitHub Actions e o CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/CI_CD.md)
+- [Testando seu conteúdo e bloqueando builds por cobertura](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/testing.md)
+- [autoFill: geração de arquivos de declaração por locale](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/autoFill.md)
+- [Referência de configuração: `locales`, `requiredLocales`, `editor`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/configuration.md)
+- [Relatórios de benchmark entre frameworks](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/benchmark/index.md)
+- [Adaptador de compatibilidade i18next](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/compat/i18next.md)
+- [Como detectar traduções ausentes](https://github.com/aymericzip/intlayer/blob/main/docs/blog/pt/detecting_missing_translations.md)
+- [Como testar traduções sem testes frágeis](https://github.com/aymericzip/intlayer/blob/main/docs/blog/pt/i18n_testing_strategies.md)