A CLI do Lingo.dev traduz os ficheiros de recursos da sua aplicação web — JSON, YAML, XLIFF, PO ou PHP — através de um motor de localização configurado. Configure o i18n no seu framework, aponte a CLI para os seus ficheiros de tradução e execute.
Como funciona#
Todos os frameworks web têm uma biblioteca de i18n que carrega traduções a partir de ficheiros de recursos — JSON para React, XLIFF para Angular, PO para Django, entre outros. A CLI traduz esses ficheiros diretamente, para que o framework use as traduções sem qualquer alteração ao código.
Configure o i18n no seu framework
Use a biblioteca oficial de i18n do seu framework para adicionar routing adaptado ao idioma, uma função de tradução e ficheiros de recursos no idioma de origem. Cada secção abaixo inclui uma ligação para o guia oficial de configuração.
Configure a CLI
Execute lingo init para criar um .lingo/config.json com os seus idiomas de origem e de destino, bem como os padrões dos ficheiros a traduzir, e depois lingo link para associar a sua organização e o motor. A CLI deteta automaticamente o formato de cada ficheiro pela extensão, por isso não é necessário indicar qualquer tipo de bucket. Faça commit de .lingo/config.json.
Execute as traduções
Execute lingo push e a CLI traduz os seus ficheiros de recursos através do motor de localização — as regras do glossário, a voz da marca e a seleção do modelo são aplicadas automaticamente.
Pré-requisitos#
Instale a CLI e inicie sessão:
npm install -g @lingo.dev/cli
lingo loginA CLI requer Node.js 22+. Em CI, ignore o início de sessão interativo e forneça uma chave com --api-key ou através da variável de ambiente LINGO_API_KEY.
Sempre que executa o CLI, o conteúdo é enviado através de um motor de localização — a configuração que define que modelo LLM, glossário, voz da marca e regras são aplicados. Crie um no painel do Lingo.dev e gere uma API key. lingo link escreve o orgId e o engineId do motor em .lingo/config.json.
Configuração assistida por IA
O i18n MCP pode criar automaticamente toda a infraestrutura de i18n do seu framework. Ligue-o ao Claude Code, Cursor ou GitHub Copilot e introduza o prompt "Set up i18n" — o agente segue uma checklist de 13 passos para configurar o routing, os ficheiros de tradução e um seletor de idioma.
Frameworks JavaScript#
O segmento de idioma em cada pattern é substituído para cada idioma de destino — public/locales/en/translation.json passa a public/locales/de/translation.json, e assim sucessivamente. O caminho de origem tem de incluir o código do idioma de origem.
O react-i18next carrega traduções a partir de ficheiros JSON e fornece um hook useTranslation que mapeia chaves para strings traduzidas em tempo de execução.
{
"orgId": "org_...",
"engineId": "eng_...",
"sourceLocale": "en",
"targetLocales": ["es", "fr", "de", "ja"],
"files": [{ "pattern": "public/locales/en/translation.json" }]
}Frameworks server-side#
O Laravel inclui localização nativa, que carrega traduções a partir de ficheiros PHP organizados por diretório de idioma.
{
"orgId": "org_...",
"engineId": "eng_...",
"sourceLocale": "en",
"targetLocales": ["es", "fr", "de", "ja"],
"files": [{ "pattern": "lang/en/messages.php" }]
}Executar traduções#
Com .lingo/config.json pronto, traduza todos os ficheiros de recursos com um único comando:
lingo pushA CLI lê os ficheiros do seu idioma de origem, calcula o que mudou desde a última execução com base no lockfile (.lingo/lock.json, com commit feito juntamente com a sua configuração), traduz apenas o delta e escreve os resultados nos ficheiros dos idiomas de destino. As traduções existentes são preservadas — a CLI limita-se a preencher as cadeias em falta ou atualizadas.
Na primeira execução, ou depois de adicionar um novo idioma de destino, traduza tudo de raiz:
lingo push --backfill-missingLimite uma execução a um subconjunto de ficheiros, passando um glob:
lingo push "messages/**"Para obter as traduções mais recentes noutro contexto (por exemplo, noutra máquina ou numa etapa de build) sem traduzir, execute lingo pull. Use lingo check como controlo de deploy para verificar se as traduções estão atualizadas.
