A CLI do Lingo.dev traduz os arquivos de recursos do seu app web — JSON, YAML, XLIFF, PO ou PHP — com um engine de localização configurado. Configure o i18n no seu framework, aponte a CLI para os arquivos de tradução e execute.
Como funciona#
Todo framework web tem uma biblioteca de i18n que carrega traduções de arquivos de recursos — JSON para React, XLIFF para Angular, PO para Django e assim por diante. A CLI traduz esses arquivos diretamente, para que o framework use as traduções sem exigir nenhuma alteração no código.
Configure o i18n no seu framework
Use a biblioteca oficial de i18n do seu framework para adicionar roteamento por idioma, uma função de tradução e arquivos de recursos no idioma de origem. Cada seção de framework abaixo traz um link para o guia oficial de configuração.
Configure a CLI
Execute lingo init para criar um .lingo/config.json com seus idiomas de origem e destino, além dos padrões de arquivos a traduzir. Depois, rode lingo link para vincular sua organização e o engine. A CLI detecta automaticamente o formato de cada arquivo pela extensão, então não é preciso informar nenhum tipo de bucket. Faça commit de .lingo/config.json.
Execute as traduções
Execute lingo push e a CLI traduzirá seus arquivos de recursos com o engine de localização — regras de glossário, voz da marca e seleção de modelo são aplicadas automaticamente.
Pré-requisitos#
Instale a CLI e faça a autenticação:
npm install -g @lingo.dev/cli
lingo loginA CLI requer Node.js 22+. Em CI, pule o login interativo e passe uma chave com --api-key ou pela variável de ambiente LINGO_API_KEY.
Cada execução do CLI envia o conteúdo por um engine de localização — a configuração que define qual modelo de LLM, glossário, voz da marca e regras serão aplicados. Crie um no painel do Lingo.dev e gere uma chave de API. lingo link grava o orgId e o engineId do engine em .lingo/config.json.
Configuração com IA
O i18n MCP pode montar automaticamente toda a infraestrutura de i18n do seu framework. Conecte-o ao Claude Code, Cursor ou GitHub Copilot e use o prompt "Set up i18n" — o agente segue uma checklist de 13 etapas para configurar roteamento, arquivos de tradução e um seletor de idioma.
Frameworks JavaScript#
O segmento de idioma em cada pattern é substituído de acordo com o idioma de destino — public/locales/en/translation.json vira public/locales/de/translation.json, e assim por diante. O caminho de origem precisa conter o código do idioma de origem.
O react-i18next carrega traduções de arquivos 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 vem com localização nativa, que carrega traduções de arquivos PHP organizados por diretório de idioma.
{
"orgId": "org_...",
"engineId": "eng_...",
"sourceLocale": "en",
"targetLocales": ["es", "fr", "de", "ja"],
"files": [{ "pattern": "lang/en/messages.php" }]
}Executando traduções#
Com .lingo/config.json configurado, traduza todos os arquivos de recurso com um único comando:
lingo pushA CLI lê os arquivos do idioma de origem, calcula o que mudou desde a última execução usando o lockfile (.lingo/lock.json, versionado junto com a sua configuração), traduz apenas o delta e grava os resultados nos arquivos de idioma de destino. As traduções existentes são preservadas — a CLI só preenche strings ausentes ou atualizadas.
Na primeira execução, ou depois de adicionar um novo idioma de destino, traduza tudo do zero:
lingo push --backfill-missingRestrinja a execução a um subconjunto de arquivos passando um glob:
lingo push "messages/**"Para buscar as traduções mais recentes em outro ambiente (por exemplo, em outra máquina ou em uma etapa de build) sem traduzir, execute lingo pull. Use lingo check como gate de deploy para verificar se as traduções estão em dia.
