@intlayer/docs 9.4.1 → 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)