Configuração

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.

{
  "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#

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.

.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:

1. 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.
2. 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ão gravados no lockfile somente após um push totalmente bem-sucedido, então uma execução concluída pela metade 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 novamente.

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

Registra o push enviado mais recentemente para que lingo pull saiba de qual execução buscar as saídas — isso funciona mesmo com terminais fechados e entre máquinas que compartilham o mesmo checkout.

{
  "runId": "run_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.

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.