Localização com Lingui.js: Arquivos PO, React i18n e Automação

Lingui.js é um framework de internacionalização (i18n) leve e poderoso para aplicações JavaScript e React. Ele usa arquivos PO (Portable Object) padrão da indústria para catálogos de tradução, macros poderosas em tempo de compilação para uma experiência de desenvolvedor limpa e produz bundles otimizados com menos de 2 kB. Este guia cobre tudo, desde a configuração do projeto até fluxos de trabalho de arquivos PO, pluralização e automação de traduções com o l10n.dev.

Por que Lingui.js para i18n?

O Lingui.js se destaca entre as bibliotecas de i18n JavaScript por sua combinação de experiência do desenvolvedor, desempenho e fluxos de trabalho de tradução profissionais:

• Limpo e Legível: Escreva traduções naturalmente usando macros JSX - a biblioteca as compila para ICU MessageFormat nos bastidores.
• Universal: @lingui/core funciona em qualquer projeto JavaScript, enquanto @lingui/react adiciona componentes específicos do React, incluindo suporte a React Server Components (RSC).
• Suporte Completo a Rich-Text: Use componentes React dentro de mensagens traduzíveis perfeitamente - links, texto em negrito, ícones e qualquer JSX são totalmente suportados.
• Formato de Arquivo PO: Usa o formato PO padrão da indústria, suportado por praticamente todas as ferramentas de tradução, TMS e fluxos de trabalho de tradutores profissionais.
• Leve e Otimizado: A biblioteca principal tem menos de 2 kB gzipped, os componentes React adicionam apenas 1,3 kB. Dados não essenciais são removidos no momento da compilação.
• Pronto para Traduções por IA: As descrições de mensagens e comentários de contexto do Lingui fornecem aos tradutores de IA as informações necessárias para produzir traduções precisas e conscientes do contexto.

Instalação

Instale os pacotes principais e as ferramentas de desenvolvimento do Lingui. Os pacotes de tempo de execução (@lingui/core e @lingui/react) são necessários em produção, enquanto a CLI, o plugin Vite e a macro Babel são apenas para desenvolvimento:

npm install @lingui/core @lingui/react
npm install --save-dev @lingui/cli @lingui/vite-plugin @lingui/babel-plugin-lingui-macro

Configuração

O Lingui requer dois arquivos de configuração: a configuração do Lingui (definindo locais e caminhos de catálogo) e a configuração da sua ferramenta de build (para habilitar macros em tempo de compilação).

Configuração do Lingui

Crie um arquivo lingui.config.js na raiz do seu projeto. Isso define seu local de origem, locais de destino, onde armazenar catálogos PO e o formato do catálogo. O formato PO é a escolha padrão e recomendada:

// lingui.config.js
import { defineConfig } from "@lingui/cli";
import { formatter } from "@lingui/format-po";

export default defineConfig({
  sourceLocale: "en",
  locales: ["en", "fr", "de", "ja", "es", "zh-CN"],
  catalogs: [
    {
      path: "<rootDir>/src/locales/{locale}/messages",
      include: ["src"],
    },
  ],
  format: formatter({ lineNumbers: false }),
});

Configuração do Vite

Se você usa Vite, adicione o plugin Lingui ao lado do plugin React com a macro Babel. Isso permite a transformação de mensagens em tempo de compilação e a compilação de catálogo em tempo real:

// vite.config.ts
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import { lingui } from "@lingui/vite-plugin";

export default defineConfig({
  plugins: [
    react({
      babel: {
        plugins: ["@lingui/babel-plugin-lingui-macro"],
      },
    }),
    lingui(),
  ],
});

O Formato de Arquivo PO

PO (Portable Object) é o formato de arquivo de tradução padrão da indústria, originado do sistema GNU gettext. O Lingui usa PO como seu formato de catálogo padrão porque é amplamente suportado por ferramentas de tradução, plataformas TMS e tradutores profissionais em todo o mundo.

• Legível: Mesmo arquivos de tradução grandes permanecem legíveis por humanos com pares msgid/msgstr claros.
• Comentários do Tradutor: Suporta comentários #. que levam descrições de contexto diretamente aos tradutores.
• Referências de Origem: Cada mensagem inclui comentários #: file:line mostrando exatamente onde ela é usada em sua base de código.
• Suporte a Contexto: Use msgctxt para desambiguar strings idênticas que têm significados diferentes em contextos diferentes.
• Suporte Universal a Ferramentas: Compatível com praticamente todos os sistemas de gerenciamento de tradução (TMS), ferramentas CAT e plataformas de localização.

Arquivo PO extraído (mensagens de origem)

#: src/components/WelcomeBanner.js:6
msgid "Welcome to our platform"
msgstr ""

#: src/components/WelcomeBanner.js:8
msgid "Hello {userName}, check out your <0>dashboard</0> to get started."
msgstr ""

#: src/components/CartSummary.js:5
msgid "{itemCount, plural, =0 {Your cart is empty} one {You have # item in your cart} other {You have # items in your cart}}"
msgstr ""

Arquivo PO traduzido (Francês)

Após a tradução, cada msgstr é preenchido com a versão localizada. O Lingui preserva a sintaxe ICU MessageFormat, tags indexadas para componentes React e variáveis de placeholder em todas as traduções.

#: src/components/WelcomeBanner.js:6
msgid "Welcome to our platform"
msgstr "Bienvenue sur notre plateforme"

#: src/components/WelcomeBanner.js:8
msgid "Hello {userName}, check out your <0>dashboard</0> to get started."
msgstr "Bonjour {userName}, consultez votre <0>tableau de bord</0> pour commencer."

#: src/components/CartSummary.js:5
msgid "{itemCount, plural, =0 {Your cart is empty} one {You have # item in your cart} other {You have # items in your cart}}"
msgstr "{itemCount, plural, =0 {Votre panier est vide} one {Vous avez # article dans votre panier} other {Vous avez # articles dans votre panier}}"

Estrutura do Projeto

Organize seus catálogos PO dentro de um diretório locales com uma subpasta por local. A CLI do Lingui cria e atualiza automaticamente esses arquivos durante a extração. Módulos JS compilados são gerados no momento do build e não devem ser editados manualmente.

src/
├── locales/
│   ├── en/
│   │   └── messages.po       ← Source (English)
│   ├── fr/
│   │   └── messages.po       ← French
│   ├── de/
│   │   └── messages.po       ← German
│   ├── ja/
│   │   └── messages.po       ← Japanese
│   ├── es/
│   │   └── messages.po       ← Spanish
│   └── zh-CN/
│       └── messages.po       ← Chinese Simplified
├── components/
├── i18n.ts
├── App.tsx
└── ...

Traduzindo Componentes React

O Lingui oferece duas abordagens principais para marcar mensagens: macros JSX para conteúdo de componentes e o hook useLingui para strings imperativas. Ambas são macros de tempo de compilação que produzem saída otimizada.

A Macro Trans

Envolva qualquer conteúdo JSX na macro Trans para torná-lo traduzível. Variáveis, elementos HTML e componentes React são totalmente suportados - a macro os transforma automaticamente em ICU MessageFormat com tags indexadas.

import { Trans } from "@lingui/react/macro";

function WelcomeBanner({ userName }) {
  return (
    <div>
      <h1>
        <Trans>Welcome to our platform</Trans>
      </h1>
      <p>
        <Trans>
          Hello {userName}, check out your <a href="/dashboard">dashboard</a> to
          get started.
        </Trans>
      </p>
    </div>
  );
}

O Hook useLingui

Para strings fora do JSX - mensagens de alerta, rótulos aria, valores de atributos ou qualquer código imperativo - use o hook de macro useLingui com template literals marcados:

import { useLingui } from "@lingui/react/macro";

function NotificationButton() {
  const { t } = useLingui();

  const showAlert = () => {
    alert(t`Your changes have been saved.`);
  };

  return (
    <button onClick={showAlert} aria-label={t`Save changes`}>
      <Trans>Save</Trans>
    </button>
  );
}

IDs de Mensagem e Descrições

O Lingui suporta duas abordagens para identificação de mensagens: IDs gerados automaticamente (derivados do conteúdo da mensagem de origem) e IDs explícitos (chaves definidas pelo desenvolvedor). Ambas as abordagens funcionam com arquivos PO.

import { Trans } from "@lingui/react/macro";

// Auto-generated ID (from message content)
<Trans>Welcome to our platform</Trans>

// Explicit ID (developer-defined key)
<Trans id="nav.welcome">Welcome to our platform</Trans>

Adicionando Contexto para Tradutores e IA

Use a propriedade comment em qualquer macro para adicionar uma descrição. Este comentário é extraído para o arquivo PO como uma nota do tradutor, fornecendo contexto crítico sobre onde e como a mensagem aparece.

import { Trans } from "@lingui/react/macro";

<Trans comment="Shown on the homepage hero section above the fold">
  Start building with confidence
</Trans>

Pluralização

O Lingui usa ICU MessageFormat para pluralização, que suporta todas as categorias de plural do CLDR. A macro Plural facilita o tratamento de diferentes formas plurais diretamente no JSX:

• Use o componente Plural com value, one, other e formas exatas opcionais (_0, _2, etc.).
• O placeholder # é substituído automaticamente pelo valor plural.
• O l10n.dev gera todas as formas plurais necessárias para cada idioma de destino - incluindo idiomas com regras complexas como árabe (6 formas), russo e polonês - sem intervenção manual.

import { Plural } from "@lingui/react/macro";

function CartSummary({ itemCount }) {
  return (
    <p>
      <Plural
        value={itemCount}
        _0="Your cart is empty"
        one="You have # item in your cart"
        other="You have # items in your cart"
      />
    </p>
  );
}

Inicialização em Tempo de Execução

Após extrair e compilar suas mensagens, configure a instância i18n e envolva seu aplicativo no I18nProvider.

Configuração do Módulo i18n

Crie um módulo i18n que carrega catálogos de mensagens compilados dinamicamente. O plugin Lingui Vite permite importações diretas de arquivos PO, que são compilados em tempo real durante o desenvolvimento:

// src/i18n.ts
import { i18n } from "@lingui/core";

export async function loadCatalog(locale: string) {
  const { messages } = await import(`./locales/${locale}/messages.po`);
  i18n.load(locale, messages);
  i18n.activate(locale);
}

// Initialize with default locale
loadCatalog("en");

export default i18n;

Configuração do I18nProvider

Envolva todo o seu aplicativo com I18nProvider para disponibilizar traduções para todos os componentes via contexto React:

// src/App.tsx
import { I18nProvider } from "@lingui/react";
import { i18n } from "./i18n";

function App() {
  return (
    <I18nProvider i18n={i18n}>
      <YourAppContent />
    </I18nProvider>
  );
}

Troca de Idioma em Tempo de Execução

Trocar de idioma é simples: carregue o novo catálogo, ative o local e o React renderiza automaticamente todo o conteúdo traduzido. Aqui está um componente de troca de idioma completo:

import { useState } from "react";
import { loadCatalog } from "./i18n";
import { Trans } from "@lingui/react/macro";

const LANGUAGES = {
  en: "English",
  fr: "Français",
  de: "Deutsch",
  ja: "日本語",
  es: "Español",
};

function LanguageSwitcher() {
  const [currentLocale, setCurrentLocale] = useState("en");

  const handleChange = async (locale: string) => {
    await loadCatalog(locale);
    setCurrentLocale(locale);
  };

  return (
    <select
      value={currentLocale}
      onChange={(e) => handleChange(e.target.value)}
    >
      {Object.entries(LANGUAGES).map(([code, name]) => (
        <option key={code} value={code}>
          {name}
        </option>
      ))}
    </select>
  );
}

Fluxo de Trabalho de Extração e Compilação

A CLI do Lingui fornece dois comandos principais que formam o núcleo do seu fluxo de trabalho de tradução: extract para extrair mensagens do código-fonte para catálogos PO e compile para converter arquivos PO em módulos JavaScript otimizados para produção.

# Extract messages from source code into PO catalogs
npx lingui extract

# Translate your PO files (manually, with a TMS, or with AI)

# Compile PO catalogs into optimized JS modules for production
npx lingui compile

1. Extrair: Analisa seus arquivos de origem e cria ou atualiza catálogos PO com todas as mensagens traduzíveis.
2. Traduzir: Preencha os campos msgstr em seus arquivos PO - manualmente, com um TMS ou automaticamente com tradução impulsionada por IA.
3. Compilar: Converte catálogos PO em módulos JS leves que são carregados em tempo de execução. Apenas mensagens traduzidas são incluídas.

Suporte Total a PO no l10n.dev

O l10n.dev oferece suporte nativo para arquivos PO, tornando-o o companheiro perfeito para projetos Lingui.js. Envie seu catálogo PO de origem e receba arquivos traduzidos com precisão:

• Formato PO Nativo: Envie arquivos PO diretamente - o l10n.dev lê entradas msgid, traduz e grava arquivos PO formatados corretamente com valores msgstr corretos.
• Ciente do ICU MessageFormat: Placeholders ({name}), tags indexadas (<0>), formas plurais e expressões de seleção são preservados corretamente em todas as traduções.
• Tradução por IA Consciente do Contexto: Comentários do tradutor (#.) e contexto de mensagem (msgctxt) são usados por nossa IA para produzir traduções mais precisas e conscientes do contexto.
• Geração de Plural: Todas as formas plurais CLDR necessárias são geradas para cada idioma de destino. Idiomas com regras plurais complexas (árabe, russo, polonês) são tratados automaticamente.
• Atualizações em Lote e Incrementais: Traduza catálogos inteiros de uma vez ou use a flag --update para traduzir apenas mensagens novas e alteradas, preservando as traduções existentes.

Automatize Traduções com npm

Use o pacote npm ai-l10n para traduzir seus catálogos PO do Lingui a partir da linha de comando ou como parte de um pipeline de CI/CD. Instale uma vez e traduza para qualquer número de idiomas em um único comando.

# Install the CLI
npm install ai-l10n

# Translate your source PO file to multiple languages
npx ai-l10n translate src/locales/en/messages.po \
  --languages fr,de,ja,zh-CN,es,ko

Integração no seu Processo de Build

Conecte o ai-l10n diretamente ao seu processo de build do Lingui para que as traduções estejam sempre atualizadas. Combine extração, tradução e compilação em um único fluxo de trabalho.

Via scripts package.json

Adicione extract, translate e compile como scripts e encadeie-os. O script i18n executa o pipeline completo; use-o no prebuild para garantir que as traduções estejam sempre atuais antes do envio.

{
  "scripts": {
    "extract": "lingui extract",
    "compile": "lingui compile",
    "translate": "ai-l10n translate src/locales/en/messages.po --languages fr,de,ja,zh-CN,es,ko --update",
    "i18n": "npm run extract && npm run translate && npm run compile",
    "prebuild": "npm run i18n",
    "build": "vite build",
    "dev": "vite"
  }
}

Via Makefile

Se sua equipe usa Make, declare extração, tradução e compilação como alvos separados com dependências adequadas:

LANGUAGES = fr,de,ja,zh-CN,es,ko

extract:
	npx lingui extract

translate:
	npx ai-l10n translate src/locales/en/messages.po --languages $(LANGUAGES) --update

compile:
	npx lingui compile

i18n: extract translate compile

dev: i18n
	npx vite

build: i18n
	npx vite build

Para integração de CI/CD, atualizações incrementais, tradução em lote em vários arquivos e exemplos de fluxo de trabalho do GitHub Actions, consulte o Guia de Automação de Localização.

Extensão para VS Code

A extensão l10n.dev para VS Code traz a tradução de arquivos PO diretamente para o seu editor. Traduza seus catálogos Lingui sem sair do VS Code.

Como Funciona no VS Code:

1. Abra seu arquivo PO de origem (por exemplo, src/locales/en/messages.po) no editor.
2. Clique com o botão direito no editor e selecione "Translate..." (funciona com arquivos PO também).
3. Escolha um ou mais idiomas de destino (por exemplo, francês, japonês, alemão).
4. A extensão cria arquivos PO traduzidos nas pastas de local correspondentes, prontos para compilar.

Comece a Localizar seu Aplicativo React com Lingui

Pronto para alcançar usuários globais? Traduza seus arquivos PO do Lingui diretamente no workspace do l10n.dev, automatize com a CLI npm ou traduza diretamente dentro do VS Code: