Localização de apps web
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 push --waitA 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-missing --waitRestrinja a execução a um subconjunto de arquivos passando um glob:
lingo push "messages/**"Para recuperar a última execução enviada deste checkout sem traduzir de novo, execute lingo pull; as outras máquinas recebem as traduções assim que elas são commitadas. Use lingo check como uma etapa de validação no deploy para verificar se as traduções estão atualizadas.