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

O Lingui.js é um framework de internacionalização (i18n) leve e poderoso para aplicações JavaScript e React. Ele utiliza 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 desenvolvimento limpa e produz bundles otimizados com menos de 2 kB. Este guia cobre tudo, desde a configuração do projeto até fluxos de trabalho com arquivos PO, pluralização e automação de traduções com a l10n.dev.

Por que usar o Lingui.js para i18n?

O Lingui.js se destaca entre as bibliotecas de i18n para JavaScript por sua combinação de experiência de desenvolvimento, 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 para React, incluindo suporte a React Server Components (RSC).
• Suporte Completo a Rich-Text: Use componentes React dentro de mensagens traduzíveis sem problemas - links, texto em negrito, ícones e qualquer JSX são totalmente suportados.
• Formato de Arquivo PO: Utiliza 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), e os componentes React adicionam apenas 1,3 kB. Dados não essenciais são removidos em tempo de 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 runtime (@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 locales e caminhos dos catálogos) 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. Ele define seu locale de origem, locales de destino, onde armazenar os 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 junto com o plugin React com a macro Babel. Isso habilita a transformação de mensagens em tempo de compilação e a compilação de catálogos sob demanda:

// 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 para 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 #: arquivo:linha mostrando exatamente onde ela é usada na sua base de código.
• Suporte a Contexto: Use msgctxt para desambiguar strings idênticas que possuem significados diferentes em contextos distintos.
• Suporte Universal a Ferramentas: Compatível com praticamente todos os sistemas de gestão 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 locale. A CLI do Lingui cria e atualiza automaticamente esses arquivos durante a extração. Módulos JS compilados são gerados no momento da 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. Ambos 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, aria labels, valores de atributos ou qualquer código imperativo - use o hook de macro useLingui com tagged template literals:

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 prop comment em qualquer macro para adicionar uma descrição. Este comentário é extraído para o arquivo PO como uma nota para o 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 de plural diretamente no JSX:

• Use o componente Plural com value, one, other e formas exatas opcionais (_0, _2, etc.).
• O placeholder # é automaticamente substituído pelo valor do plural.
• A l10n.dev gera todas as formas de plural necessárias para cada idioma de destino - incluindo idiomas complexos 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 Runtime

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 sob demanda 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 o I18nProvider para disponibilizar as 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 Runtime

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

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: Escaneia 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 baseada em IA.
3. Compilar: Converte catálogos PO em módulos JS leves que são carregados em runtime. Apenas mensagens traduzidas são incluídas.

Suporte Completo a PO na l10n.dev

A l10n.dev oferece suporte nativo a arquivos PO, tornando-a a companheira perfeita 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 - a l10n.dev lê entradas msgid, traduz e escreve de volta arquivos PO formatados corretamente com valores msgstr adequados.
• Consciente de ICU MessageFormat: Placeholders ({name}), tags indexadas (<0>), formas de plural e expressões select são preservados corretamente em todas as traduções.
• Tradução por IA Consciente do Contexto: Comentários do tradutor (#.) e contexto da 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 de plural CLDR necessárias são geradas para cada idioma de destino. Idiomas com regras de plural 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 ou 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 com 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 do 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 atualizadas antes do deploy.

{
  "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 a extração, tradução e compilação como targets separados com as devidas dependências:

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 com CI/CD, atualizações incrementais, tradução em lote entre múltiplos arquivos e exemplos de fluxo de trabalho no GitHub Actions, veja 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 (ex: 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 (ex: Francês, Japonês, Alemão).
4. A extensão cria arquivos PO traduzidos nas pastas de locale correspondentes, prontos para compilar.

Comece a Localizar seu App React com Lingui

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