Internacionalização (i18n)

• Introdução
• Arquitetura
• Hooks e Funções
• Padrões de Tradução
• Namespaces
• Integração com Zod
• Pluralização e Interpolação
• Melhores Práticas de Interpolação
• Formatação HTML em Traduções
• Caching com localStorage
• Seletor de Idioma
• CLI e Extração
• Validação i18n (CI/CD)
• Testes
• Anti-patterns
• Tipagem TypeScript (Intellisense)

---

Introdução

Stack

Biblioteca	Versão	Propósito
i18next	25.x	Core de internacionalização
react-i18next	16.x	Bindings React
i18next-browser-languagedetector	8.x	Detecção automática
i18next-chained-backend	5.x	Múltiplos backends
i18next-localstorage-backend	4.x	Cache em localStorage
i18next-resources-to-backend	1.x	Converter recursos inline
i18next-cli	1.x	Extração de strings (CLI)

Idiomas Suportados

Código	Nome	Status
pt-BR	Português (Brasil)	Fonte
en	English	Tradução

Arquitetura

┌─────────────────────────────────────────────────────────────┐
│                      @gaio/i18n                             │
│  (Package dedicado para internacionalização)                │
└─────────────────────────┬───────────────────────────────────┘
                          │
          ┌───────────────┼───────────────┐
          ▼               ▼               ▼
┌─────────────────┐ ┌───────────┐ ┌───────────────┐
│   I18nProvider  │ │   useT    │ │  zodMessages  │
│  (Wrapper App)  │ │  (Hook)   │ │  (Validação)  │
└─────────────────┘ └───────────┘ └───────────────┘
          │
          ▼
┌─────────────────────────────────────────────────────────────┐
│                    locales/                                 │
│  pt-BR/common.json  │  en/common.json  │  ...               │
└─────────────────────────────────────────────────────────────┘

Imports Padrão

O package é dividido em dois módulos:

// ============================================
// @gaio/i18n/core - SEM dependência de React
// Use em: utils, services, schemas Zod, constantes
// ============================================
import {
  i18n,
  zodMessages,
  SUPPORTED_LOCALES,
  LOCALE_LABELS,
  clearI18nCache,
  getCacheVersion,
} from "@gaio/i18n/core";

// ============================================
// @gaio/i18n/react - COM dependência de React
// Use em: componentes, hooks, providers
// ============================================
import { I18nProvider, useT, useLocale, changeLocale } from "@gaio/i18n/react";

// Componente Trans (re-export do react-i18next)
import { Trans } from "@gaio/i18n/react";

Quando usar cada um:

Módulo	Uso	Exemplos
@gaio/i18n/core	Arquivos sem React	Schemas Zod, utils, services, constantes
@gaio/i18n/react	Componentes React	Hooks, Provider, componentes UI

---

Arquitetura

Estrutura do Package

packages/i18n/
├── package.json
├── tsconfig.json
├── i18next.config.ts
└── src/
    ├── core/                     # @gaio/i18n/core (sem React)
    │   ├── index.ts              # Exports: i18n, zodMessages, constantes, cache utils
    │   ├── constants.ts          # SUPPORTED_LOCALES, NAMESPACES
    │   ├── config.ts             # Setup i18next com ChainedBackend
    │   └── validation.ts         # zodMessages
    │
    ├── react/                    # @gaio/i18n/react (com React)
    │   ├── index.ts              # Exports: Provider, hooks, Trans
    │   ├── provider.tsx          # I18nProvider
    │   └── hooks.ts              # useT, useLocale, changeLocale
    │
    ├── types/                    # Tipagem TypeScript
    │   └── resources.d.ts        # Declaração para intellisense
    │
    └── locales/                  # Traduções
        ├── pt-BR/
        │   ├── index.ts
        │   ├── common.json
        │   ├── validation.json
        │   ├── errors.json
        │   ├── auth.json
        │   ├── inbox.json
        │   ├── workflows.json
        │   └── settings.json
        └── en/
            └── ... (mesmos arquivos)

Exports do Package

package.json

{
  "exports": {
    "./core": "./src/core/index.ts",
    "./react": "./src/react/index.ts"
  }
}

Integração com Console

O I18nProvider deve ser o provider mais externo na aplicação:

packages/console/src/providers.tsx

import { I18nProvider } from "@gaio/i18n/react";

export function AppProviders({ children }: { children: ReactNode }) {
  return (
    <I18nProvider>
      <TrackingProvider>
        <QueryClientProvider client={queryClient}>
          {children}
        </QueryClientProvider>
      </TrackingProvider>
    </I18nProvider>
  );
}

---

Hooks e Funções

useT

Hook principal para acessar traduções. Wrapper do useTranslation do react-i18next.

import { useT } from '@gaio/i18n/react';

function MyComponent() {
  const { t } = useT();

  return <Button>{t('common:actions.save')}</Button>;
}

Com Namespace Específico

// Namespace único
const { t } = useT("validation");
t("required"); // validation:required

// Múltiplos namespaces
const { t } = useT(["common", "validation"]);
t("common:actions.save");
t("validation:required");

Retorno do useT

Propriedade	Tipo	Descrição
t	(key, options?) => string	Função de tradução
i18n	i18n	Instância i18next
ready	boolean	Se traduções estão prontas

useLocale

Hook para obter o idioma atual.

Localização: @gaio/i18n/react

import { useLocale } from '@gaio/i18n/react';

function LanguageIndicator() {
  const locale = useLocale(); // 'pt-BR' | 'en-US'

  return <span>Idioma: {locale}</span>;
}

changeLocale

Função para trocar o idioma programaticamente.

Localização: @gaio/i18n/react

import { changeLocale } from "@gaio/i18n/react";
import type { SupportedLocale } from "@gaio/i18n/core";

function handleLanguageChange(locale: SupportedLocale) {
  changeLocale(locale); // Atualiza i18n + cookie
}

---

Padrões de Tradução

Convenção de Keys

IMPORTANTE: Todas as keys devem estar em inglês usando snake_case:

// ✅ CORRETO - keys em inglês, descritivas
t("validation:required");
t("validation:invalid_email");
t("common:actions.save");
t("common:messages.success.saved");

// ❌ ERRADO - keys em português
t("validation:campo_obrigatorio");
t("validation:email_invalido");
t("common:acoes.salvar");

Texto Simples

import { useT } from "@gaio/i18n/react";

function SaveButton() {
  const { t } = useT();

  return <Button>{t("common:actions.save")}</Button>;
}

locales/pt-BR/common.json

{
  "actions": {
    "save": "Salvar",
    "cancel": "Cancelar",
    "confirm": "Confirmar"
  }
}

Com Interpolação

const { t } = useT();

// Simples
t("welcome", { name: "João" }); // "Olá, João!"

// Múltiplas variáveis
t("summary", { count: 5, total: 100 }); // "5 de 100 itens"

{
  "welcome": "Olá, {{name}}!",
  "summary": "{{count}} de {{total}} itens"
}

JSX Complexo (Trans)

Use o componente Trans quando precisar de JSX dentro da tradução:

import { Trans } from "@gaio/i18n/react";

<Trans i18nKey="terms">
  Ao continuar, você aceita os <Link to="/terms">Termos de Uso</Link>
</Trans>;

{
  "terms": "Ao continuar, você aceita os <1>Termos de Uso</1>"
}

Toast Notifications

import { useT } from "@gaio/i18n/react";
import { toast } from "sonner";

function MyComponent() {
  const { t } = useT();

  const handleSave = async () => {
    try {
      await saveData();
      toast.success(t("common:messages.success.saved"));
    } catch {
      toast.error(t("common:messages.error.save"));
    }
  };
}

Fora de Componentes React

Para usar traduções fora de componentes (utils, services), importe a instância i18n do módulo core:

import { i18n } from "@gaio/i18n/core";

export function formatError(code: string): string {
  return i18n.t(`errors:${code}`);
}

---

Namespaces

Os namespaces organizam traduções por domínio/feature:

Namespace	Conteúdo	Uso
common	Botões, labels, status	UI compartilhada
validation	Mensagens de validação	Schemas Zod
errors	Erros HTTP/API	Error handlers
auth	Login, registro	screens/auth/
inbox	Chat, mensagens	screens/dashboard/inbox/
workflows	Editor de automação	screens/dashboard/workflows/
settings	Configurações	screens/dashboard/settings/

Vocabulário Padrão

O namespace common contém elementos reutilizáveis em toda a aplicação. Sempre use essas keys ao invés de criar duplicatas.

Ações (Botões)

common.json

{
  "actions": {
    "save": "Salvar",
    "cancel": "Cancelar",
    "confirm": "Confirmar",
    "create": "Criar",
    "edit": "Editar",
    "delete": "Excluir",
    "remove": "Remover",
    "add": "Adicionar",
    "send": "Enviar",
    "back": "Voltar",
    "next": "Próximo",
    "previous": "Anterior",
    "close": "Fechar",
    "open": "Abrir",
    "search": "Buscar",
    "filter": "Filtrar",
    "clear": "Limpar",
    "copy": "Copiar",
    "paste": "Colar",
    "duplicate": "Duplicar",
    "refresh": "Atualizar",
    "load_more": "Carregar mais",
    "view_more": "Ver mais",
    "view_less": "Ver menos",
    "expand": "Expandir",
    "collapse": "Recolher",
    "export": "Exportar",
    "import": "Importar",
    "download": "Baixar",
    "upload": "Enviar arquivo"
  }
}

Uso:

t("common:actions.save"); // "Salvar"
t("common:actions.cancel"); // "Cancelar"

Status

common.json

{
  "status": {
    "active": "Ativo",
    "inactive": "Inativo",
    "pending": "Pendente",
    "approved": "Aprovado",
    "rejected": "Rejeitado",
    "completed": "Concluído",
    "in_progress": "Em andamento",
    "paused": "Pausado",
    "canceled": "Cancelado",
    "archived": "Arquivado",
    "draft": "Rascunho",
    "published": "Publicado",
    "scheduled": "Agendado",
    "expired": "Expirado",
    "error": "Erro",
    "success": "Sucesso",
    "loading": "Carregando...",
    "processing": "Processando..."
  }
}

Uso:

t("common:status.active"); // "Ativo"
t("common:status.pending"); // "Pendente"

Labels de Campos

common.json

{
  "fields": {
    "name": "Nome",
    "email": "E-mail",
    "phone": "Telefone",
    "password": "Senha",
    "confirm_password": "Confirmar senha",
    "description": "Descrição",
    "title": "Título",
    "date": "Data",
    "time": "Hora",
    "start_date": "Data de início",
    "end_date": "Data de término",
    "address": "Endereço",
    "city": "Cidade",
    "state": "Estado",
    "country": "País",
    "zip_code": "CEP",
    "cpf": "CPF",
    "cnpj": "CNPJ",
    "notes": "Observação",
    "attachment": "Anexo",
    "file": "Arquivo",
    "image": "Imagem",
    "link": "Link",
    "url": "URL",
    "quantity": "Quantidade",
    "value": "Valor",
    "price": "Preço",
    "total": "Total"
  }
}

Uso:

t("common:fields.name"); // "Nome"
t("common:fields.email"); // "E-mail"

Placeholders

common.json

{
  "placeholders": {
    "search": "Buscar...",
    "select": "Selecione...",
    "type": "Digite...",
    "email": "exemplo@email.com",
    "phone": "(00) 00000-0000",
    "date": "DD/MM/AAAA"
  }
}

Uso:

<Input placeholder={t("common:placeholders.search")} />

Mensagens Genéricas

common.json

{
  "messages": {
    "success": {
      "saved": "Salvo com sucesso",
      "created": "Criado com sucesso",
      "updated": "Atualizado com sucesso",
      "deleted": "Excluído com sucesso",
      "sent": "Enviado com sucesso",
      "copied": "Copiado para a área de transferência"
    },
    "error": {
      "generic": "Ocorreu um erro. Tente novamente.",
      "connection": "Erro de conexão. Verifique sua internet.",
      "load": "Erro ao carregar dados",
      "save": "Erro ao salvar",
      "delete": "Erro ao excluir",
      "permission": "Você não tem permissão para esta ação"
    },
    "confirmation": {
      "delete": "Tem certeza que deseja excluir?",
      "cancel": "Tem certeza que deseja cancelar?",
      "exit": "Tem certeza que deseja sair?",
      "discard": "Descartar alterações não salvas?"
    },
    "empty": {
      "list": "Nenhum item encontrado",
      "search": "Nenhum resultado para sua busca",
      "data": "Sem dados para exibir"
    }
  }
}

Uso:

toast.success(t("common:messages.success.saved"));
toast.error(t("common:messages.error.generic"));

Tempo e Datas

common.json

{
  "time": {
    "today": "Hoje",
    "yesterday": "Ontem",
    "tomorrow": "Amanhã",
    "now": "Agora",
    "just_now": "Há pouco",
    "seconds": "{{count}} segundo",
    "seconds_plural": "{{count}} segundos",
    "minutes": "{{count}} minuto",
    "minutes_plural": "{{count}} minutos",
    "hours": "{{count}} hora",
    "hours_plural": "{{count}} horas",
    "days": "{{count}} dia",
    "days_plural": "{{count}} dias",
    "weeks": "{{count}} semana",
    "weeks_plural": "{{count}} semanas",
    "months": "{{count}} mês",
    "months_plural": "{{count}} meses"
  }
}

Uso:

t("common:time.days", { count: 5 }); // "5 dias"
t("common:time.today"); // "Hoje"

Paginação e Listas

common.json

{
  "pagination": {
    "page": "Página {{current}} de {{total}}",
    "items": "{{count}} item",
    "items_plural": "{{count}} itens",
    "showing": "Mostrando {{from}} a {{to}} de {{total}}",
    "per_page": "Por página",
    "first": "Primeira",
    "last": "Última"
  }
}

Regra de Ouro

// ❌ ERRADO - Criar key específica para algo comum
t("workflows:save");
t("inbox:cancel_button");
t("settings:delete_account");

// ✅ CORRETO - Usar vocabulary padrão
t("common:actions.save");
t("common:actions.cancel");
t("common:actions.delete");

// ✅ CORRETO - Key específica apenas para contexto único
t("settings:account.delete_permanently"); // Ação específica com consequência diferente

Criar Novo Namespace

Guia passo a passo para adicionar um novo escopo de tradução.

Criar Arquivos JSON

# Estrutura de arquivos
packages/i18n/src/locales/
├── pt-BR/
│   └── campaigns.json    # NOVO
└── en/
    └── campaigns.json    # NOVO

packages/i18n/src/locales/pt-BR/campaigns.json

{
  "title": "Campanhas",
  "create": "Criar campanha",
  "edit": "Editar campanha",
  "delete": "Excluir campanha",
  "status": {
    "active": "Ativa",
    "paused": "Pausada",
    "finished": "Finalizada"
  },
  "messages": {
    "created_success": "Campanha criada com sucesso",
    "updated_success": "Campanha atualizada com sucesso",
    "deleted_success": "Campanha excluída com sucesso",
    "error_create": "Erro ao criar campanha"
  }
}

packages/i18n/src/locales/en/campaigns.json

{
  "title": "Campaigns",
  "create": "Create campaign",
  "edit": "Edit campaign",
  "delete": "Delete campaign",
  "status": {
    "active": "Active",
    "paused": "Paused",
    "finished": "Finished"
  },
  "messages": {
    "created_success": "Campaign created successfully",
    "updated_success": "Campaign updated successfully",
    "deleted_success": "Campaign deleted successfully",
    "error_create": "Error creating campaign"
  }
}

Registrar no Index de Locales

packages/i18n/src/locales/pt-BR/index.ts

import auth from "./auth.json";
import campaigns from "./campaigns.json";
import common from "./common.json";
import errors from "./errors.json";
import inbox from "./inbox.json";
import settings from "./settings.json";
import validation from "./validation.json";
import workflows from "./workflows.json";

export default {
  auth,
  campaigns,
  common,
  errors,
  inbox,
  settings,
  validation,
  workflows,
};

Adicionar nas Constantes

packages/i18n/src/core/constants.ts

export const NAMESPACES = [
  "auth",
  "campaigns",
  "common",
  "errors",
  "inbox",
  "settings",
  "validation",
  "workflows",
] as const;

Atualizar Tipagem TypeScript

packages/i18n/src/types/resources.d.ts

import "i18next";

import auth from "../locales/pt-BR/auth.json";
import campaigns from "../locales/pt-BR/campaigns.json";
import common from "../locales/pt-BR/common.json";
import errors from "../locales/pt-BR/errors.json";
import inbox from "../locales/pt-BR/inbox.json";
import settings from "../locales/pt-BR/settings.json";
import validation from "../locales/pt-BR/validation.json";
import workflows from "../locales/pt-BR/workflows.json";

declare module "i18next" {
  interface CustomTypeOptions {
    defaultNS: "common";
    resources: {
      auth: typeof auth;
      campaigns: typeof campaigns;
      common: typeof common;
      errors: typeof errors;
      inbox: typeof inbox;
      settings: typeof settings;
      validation: typeof validation;
      workflows: typeof workflows;
    };
  }
}

Usar o Novo Namespace

packages/console/src/screens/dashboard/campaigns/index.tsx

import { useT } from "@gaio/i18n/react";

function CampaignsPage() {
  const { t } = useT("campaigns");

  return (
    <div>
      <h1>{t("title")}</h1>
      <Button>{t("create")}</Button>
    </div>
  );
}

// Acesso a keys aninhadas
t("campaigns:status.active"); // "Ativa"
t("campaigns:messages.created_success"); // "Campanha criada com sucesso"

Checklist Novo Namespace

• Criar pt-BR/{namespace}.json
• Criar en/{namespace}.json
• Adicionar import em locales/pt-BR/index.ts
• Adicionar import em locales/en/index.ts
• Adicionar em NAMESPACES em constants.ts
• Adicionar em resources.d.ts para intellisense
• Testar com useT('namespace') no componente

---

Integração com Zod

O zodMessages fornece mensagens de validação traduzidas para schemas Zod.

Mensagens Disponíveis

Função	Exemplo de Uso	Key
required()	.min(1, zodMessages.required())	validation:required
minLength(n)	.min(3, zodMessages.minLength(3))	validation:min_length
maxLength(n)	.max(100, zodMessages.maxLength(100))	validation:max_length
invalidEmail()	.email(zodMessages.invalidEmail())	validation:invalid_email
invalidUrl()	.url(zodMessages.invalidUrl())	validation:invalid_url
invalidPhone()	Custom validator	validation:invalid_phone
passwordMismatch()	Refine de confirmação	validation:password_mismatch
passwordMinLength()	.min(8, ...)	validation:password_min_length
passwordUppercase()	Regex validator	validation:password_uppercase
passwordLowercase()	Regex validator	validation:password_lowercase
passwordNumber()	Regex validator	validation:password_number
passwordSpecial()	Regex validator	validation:password_special

Exemplo de Schema

import { z } from "zod";
import { zodMessages } from "@gaio/i18n/core";

export const RegisterSchema = z
  .object({
    name: z
      .string()
      .min(1, zodMessages.required())
      .max(100, zodMessages.maxLength(100)),

    email: z
      .string()
      .min(1, zodMessages.required())
      .email(zodMessages.invalidEmail()),

    password: z
      .string()
      .min(8, zodMessages.passwordMinLength())
      .regex(/[A-Z]/, zodMessages.passwordUppercase())
      .regex(/[a-z]/, zodMessages.passwordLowercase())
      .regex(/[0-9]/, zodMessages.passwordNumber()),

    confirmPassword: z.string(),
  })
  .refine((data) => data.password === data.confirmPassword, {
    message: zodMessages.passwordMismatch(),
    path: ["confirmPassword"],
  });

Mensagens Customizadas

Para mensagens específicas de um form, use i18n.t() diretamente:

import { i18n, zodMessages } from "@gaio/i18n/core";

const WorkflowSchema = z.object({
  name: z
    .string()
    .min(1, zodMessages.required())
    .max(50, () => i18n.t("workflows:name_max_50")),
});

---

Pluralização e Interpolação

Pluralização

i18next usa sufixos para pluralização:

locales/pt-BR/common.json

{
  "message": "{{count}} mensagem",
  "message_plural": "{{count}} mensagens",
  "message_zero": "Nenhuma mensagem"
}

t("message", { count: 0 }); // "Nenhuma mensagem"
t("message", { count: 1 }); // "1 mensagem"
t("message", { count: 5 }); // "5 mensagens"

Regras de Sufixos

Sufixo	Quando usado
(nenhum)	count === 1
_plural	count !== 1
_zero	count === 0 (opcional)

Interpolação com Formatação

{
  "price": "R$ {{value, number}}",
  "date": "{{date, datetime}}"
}

t("price", { value: 1234.56 }); // "R$ 1.234,56" (formatado pelo locale)

Context (Gênero)

{
  "user_updated": "Usuário atualizado",
  "user_updated_male": "Usuário atualizado",
  "user_updated_female": "Usuária atualizada"
}

t("user_updated", { context: "female" }); // "Usuária atualizada"

---

Melhores Práticas de Interpolação

Quando Usar Interpolação

Use interpolação apenas para valores dinâmicos que só podem ser conhecidos em runtime:

// ✅ CORRETO - valor dinâmico (nome do usuário vem do banco)
t("welcome", { name: user.name });

// ✅ CORRETO - valores numéricos dinâmicos
t("items_count", { count: items.length });

// ✅ CORRETO - timestamps e datas
t("last_updated", { date: formatDate(updatedAt) });

Quando NÃO Usar Interpolação

Evite interpolação para valores conhecidos no momento da tradução. Use chaves separadas:

// ❌ ERRADO - concatenação de strings
t("error_prefix") + errorType + t("error_suffix");

// ❌ ERRADO - interpolação para valores conhecidos
t("file_type_error", { type: "PDF" });

// ✅ CORRETO - chaves separadas e autocontidas
t("errors.invalid_pdf_file");
t("errors.invalid_image_file");
t("errors.invalid_document_file");

Tabela de Decisão

Cenário	Abordagem	Exemplo
Nome de usuário	Interpolação	Olá, {{name}}
Contagens	Interpolação + Pluralização	{{count}} mensagem / {{count}} mensagens
Tipos de arquivo conhecidos	Chaves separadas	invalid_pdf_file, invalid_image_file
Status conhecidos	Chaves separadas	status.active, status.inactive
Mensagens de erro específicas	Chaves separadas	errors.network_error, errors.auth_error
Métodos de pagamento	Chaves separadas	payment.credit_card, payment.paypal

---

Formatação HTML em Traduções

Quando traduções precisam conter formatação (negrito, itálico, links), use o componente Trans do react-i18next em vez de dangerouslySetInnerHTML.

defaultTransComponents

Use o helper defaultTransComponents para elementos HTML padrão:

import { defaultTransComponents } from "@gaio/i18n/react";

// Elementos suportados:
// <b> e <strong> → <strong className="font-semibold" />
// <i> e <em> → <em className="italic" />
// <br> → <br />
// <highlight> → <span className="font-medium text-primary" />

Exemplo Completo

import { Trans, defaultTransComponents } from "@gaio/i18n/react";

export const InviteDialog = () => {
  return (
    <p className="text-muted-foreground text-xs">
      <Trans
        components={defaultTransComponents}
        i18nKey="settings:collaboration_invite.invites_count"
        values={{ current: fields.length, max: 20 }}
      />
    </p>
  );
};

Quando Usar Trans vs t()

Cenário	Use	Exemplo
Texto simples sem formatação	t()	t('common:labels.save')
Texto com interpolação simples	t()	t('messages.hello', { name })
Texto com negrito, itálico, etc.	Trans	<Trans i18nKey="key" components={defaultTransComponents} />
Texto com links	Trans + createLinkComponent	Ver exemplo acima

---

Seletor de Idioma

Componente de Seleção

import { useT, useLocale, changeLocale } from "@gaio/i18n/react";
import { LOCALE_LABELS, SUPPORTED_LOCALES } from "@gaio/i18n/core";

export function LanguageSelector() {
  const { t } = useT();
  const currentLocale = useLocale();

  return (
    <Field>
      <Label>{t("settings:language")}</Label>
      <Select value={currentLocale} onValueChange={changeLocale}>
        {SUPPORTED_LOCALES.map((code) => (
          <SelectItem key={code} value={code}>
            {LOCALE_LABELS[code]}
          </SelectItem>
        ))}
      </Select>
    </Field>
  );
}

Persistência

A preferência de idioma é salva automaticamente em um cookie ga:i18n (duração: 1 ano).

Ordem de detecção:

1. cookie (preferência salva)
2. navigator.language (idioma do navegador)
3. pt-BR (fallback)

---

CLI e Extração

Comandos

# Extrair strings do código para os JSONs
npm run i18n:extract -w @gaio/i18n

# Verificar se há strings não extraídas (CI)
npm run i18n:check -w @gaio/i18n

Workflow de Tradução

1. Desenvolver feature com strings usando t('key')
2. Rodar npm run i18n:extract -w @gaio/i18n
3. Preencher traduções em pt-BR/*.json

---

Validação i18n (CI/CD)

Comandos da CLI Gaio

gaio i18n validate          # Validação completa (usado no CI)
gaio i18n validate --fix    # Validação com auto-fix de chaves órfãs
gaio i18n extract           # Extrair chaves de tradução do código
gaio i18n status            # Ver status das traduções (completude)
gaio i18n lint              # Detectar hardcoded strings

O que é Validado

1. Chaves Órfãs - Chaves que existem nos JSONs mas não são usadas no código
2. Hardcoded Strings - Strings visíveis ao usuário que não usam t()
3. Status das Traduções - Chaves faltantes entre idiomas

Workflow de Desenvolvimento

1. gaio i18n extract - Extrair novas chaves
2. Preencher traduções em ambos idiomas
3. gaio i18n validate - Validar localmente
4. Corrigir problemas com --fix se necessário

---

Testes

Test Provider

import { I18nProvider } from "@gaio/i18n/react";

export function TestI18nWrapper({ children }: { children: ReactNode }) {
  return <I18nProvider>{children}</I18nProvider>;
}

render(
  <TestI18nWrapper>
    <MyComponent />
  </TestI18nWrapper>,
);

Mock de Traduções

vi.mock("@gaio/i18n/react", () => ({
  useT: () => ({
    t: (key: string) => key,
  }),
}));

---

Anti-patterns

// ❌ ERRADO - Strings hardcoded
<Button>Salvar</Button>;

// ✅ CORRETO
const { t } = useT();
<Button>{t("common:actions.save")}</Button>;

// ❌ ERRADO - Concatenação de strings
t("you_have") + count + t("messages");

// ✅ CORRETO - Interpolação
t("you_have_messages", { count });

// ❌ ERRADO - Keys em português
t("validation:campo_obrigatorio");

// ✅ CORRETO
t("validation:required");

// ❌ ERRADO - useT em loops
{
  items.map((item) => {
    const { t } = useT(); // Hook em cada iteração!
    return <span>{t("item")}</span>;
  });
}

// ✅ CORRETO
const { t } = useT();
{
  items.map((item) => <span key={item.id}>{t("item")}</span>);
}

---

TypeScript

Para ter intellisense das variáveis de interpolação em cada tradução, configure os tipos:

packages/i18n/src/types/resources.d.ts

import "i18next";
import common from "../locales/pt-BR/common.json";
// ... outros imports

declare module "i18next" {
  interface CustomTypeOptions {
    defaultNS: "common";
    resources: {
      common: typeof common;
      // ... outros namespaces
    };
  }
}

Benefícios

// ✅ Autocomplete de keys
t("welcome"); // Sugere todas as keys disponíveis

// ✅ Erro se key não existe
t("key_inexistente"); // TypeScript error!

// ✅ Autocomplete de variáveis de interpolação
t("welcome", { name: "João" }); // TypeScript sabe que 'name' é obrigatório

---

Referências

• i18next: https://www.i18next.com
• react-i18next: https://react.i18next.com
• TypeScript setup: https://www.i18next.com/overview/typescript