Configuração · Lingo.dev

O estado persistente da CLI fica em três lugares: dois dentro do projeto (versionados) e um no seu diretório home (por máquina).

`.lingo/config.json` — versionado#

Criado por lingo init (seção de localização) e lingo link (vínculo org/engine). Faça commit dele.

json

{
  "orgId": "org_a8c...",
  "engineId": "eng_b9d...",
  "sourceLocale": "en",
  "targetLocales": ["de", "fr", "es"],
  "files": [
    { "pattern": "locales/en.json" },
    { "pattern": "docs/en/**/*.md" }
  ]
}

Referência dos campos#

Campo	Obrigatório	Descrição
`orgId`	sim (após `link`)	Organização que é dona do engine.
`engineId`	sim (após `link`)	Engine que faz a tradução. Armazena configuração do modelo, glossário e voz da marca.
`sourceLocale`	sim	Código de idioma dos seus arquivos de origem (por exemplo, `"en"`). Os arquivos de origem são lidos, nunca escritos.
`targetLocales`	sim	Idiomas para os quais traduzir. As saídas são gravadas no mesmo diretório da origem, com o código do idioma substituído no padrão (`locales/en.json` → `locales/de.json`).
`files`	sim	Lista de padrões de origem. `pattern` é um glob (barras normais, recursão com `*`, curingas ``). A CLI substitui os códigos de idioma ao resolver os caminhos de destino.
`github`	não	Configurações do GitHub App — ignoradas pela própria CLI.

Mapeamento de padrão → destino#

A CLI substitui o idioma de origem no padrão por cada idioma de destino:

locales/en.json → locales/de.json, locales/fr.json, ...
docs/en/**/*.md → docs/de/**/*.md (subárvore espelhada)
copy/en/marketing.md → copy/de/marketing.md

Se a estrutura dos seus arquivos de origem não incluir o código do idioma no caminho, reestruture-a. Sem isso, a CLI não consegue inferir para onde os arquivos de destino devem ir.

Os comandos push, pull e purge também verificam para onde cada caminho realmente aponta. Se um arquivo de origem, um arquivo de destino, .lingo/lock.json ou .lingo/config.json levar para fora da raiz do projeto ou para dentro de .git — por exemplo, por meio de um link simbólico —, o comando será interrompido com um erro antes que qualquer dado seja lido, gravado ou excluído nesse local. Links que apontam para locais dentro do projeto continuam funcionando, mas, se o próprio arquivo de destino ou Lockfile for um link, a gravação não será realizada por meio dele. Em um monorepo, execute a CLI a partir de uma raiz que contenha os arquivos compartilhados, em vez de criar links para eles a partir de um pacote.

`.lingo/lock.json` — versionado#

Rastreia o hash do último estado conhecido no servidor de cada arquivo de origem e de destino. Ele é usado para duas coisas:

lingo push consulta isso para decidir se um arquivo de origem mudou desde a última execução bem-sucedida. Arquivos inalterados viram um no-op sem precisar fazer uma ida ao servidor.
lingo pull consulta isso para detectar edições locais no destino — se o hash de um destino local for diferente do que o lockfile informa, o pull sobrescreveria o trabalho local, então pull retorna erro, a menos que você passe --force.

Os hashes de origem só são gravados no arquivo de lock quando uma execução é concluída (lingo push --wait ou lingo pull depois), então uma execução com falha ou cancelada pode ser repetida sem limpeza manual.

Faça commit do lockfile junto com as saídas traduzidas. Trate conflitos da mesma forma que trataria conflitos de package-lock.json: regenere executando lingo push --wait novamente.

`~/.lingo/runs/<hash>.json` — por máquina, #

Registra o push enviado mais recentemente para que o lingo pull saiba de qual execução buscar as saídas — funciona mesmo depois de fechar o terminal, na mesma máquina e no mesmo caminho do projeto.

json

{
  "runId": "lrg_a8c...",
  "engineId": "eng_b9d...",
  "organizationId": "org_a8c...",
  "sourceLocale": "en",
  "createdAt": "2026-05-22T14:32:01.000Z"
}

O hash do nome do arquivo é derivado do caminho absoluto da raiz do projeto, e não do conteúdo dos arquivos. Então:

Editar en.json não invalida o arquivo — o mesmo pull ainda encontra a execução.
Dois checkouts do mesmo repositório na mesma máquina recebem arquivos distintos (caminhos absolutos diferentes).
Mover o projeto (mv ~/Projects/foo ~/Projects/bar) entre o push e o pull invalida a busca, já que o hash muda. O JSON continua em ~/.lingo/runs/ se você precisar recuperar manualmente o ID da execução.

Este arquivo é um estado por máquina, não do projeto — ele não é ignorado pelo git porque fica totalmente fora do repositório.

Credenciais de autenticação — `~/.lingo/auth.json`#

Armazenadas por lingo login (o fluxo OTP armazena uma sessão do Supabase; o fluxo --api-key armazena a chave). Não são versionadas e nunca são lidas por nada além da própria CLI.

bash

lingo logout         # clear credentials
lingo whoami         # check what's stored and which org/engine the cwd resolves to

Resolução a partir de subdiretórios#

Cada comando sobe a partir de cwd em busca do .lingo/config.json mais próximo. Executar lingo push em src/components/ grava o lockfile de volta na raiz do projeto, e não cria um novo .lingo/ em components/. Assim, você não precisa cd até a raiz antes de cada comando.

.lingo/config.json — versionado#