Configuração

O estado persistente da CLI fica guardado em três locais: dois dentro do projeto (com commit) e um no seu diretório pessoal (por máquina).

.lingo/config.json — com commit#

Criado por lingo init (secção de localização) e lingo link (associação entre org e motor). Faça commit deste ficheiro.

{
  "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 ficheiros de origem não incluir o código de idioma no caminho, terá de a reorganizar. Sem isso, a CLI não consegue inferir onde devem ficar os ficheiros de destino.

.lingo/lock.json — com commit#

Regista o último hash conhecido no servidor de cada ficheiro de origem e de destino. É usado para duas coisas:

1. lingo push consulta-o para decidir se uma origem mudou desde a última execução bem-sucedida. Os ficheiros inalterados tornam-se um no-op sem ida e volta ao servidor.
2. lingo pull consulta-o para detetar edições locais nos ficheiros de destino — se o hash de um destino local diferir do que o lockfile indica, um pull iria sobrescrever trabalho local, por isso pull devolve um erro, a menos que passe --force.

Os hashes da origem só recebem commit no lockfile após um push totalmente bem-sucedido, para que uma execução incompleta possa ser repetida sem limpeza manual.

Faça commit do lockfile juntamente com os resultados traduzidos. Trate os conflitos da mesma forma que trataria conflitos de package-lock.json: regenere executando lingo push novamente.

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

Regista o push submetido mais recentemente para que lingo pull saiba de que execução obter os resultados — funciona mesmo depois de fechar o terminal e entre máquinas que partilham 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 ficheiro é derivado do caminho absoluto da raiz do projeto, e não do conteúdo dos ficheiros, por isso:

• Editar en.json não invalida o ficheiro — o mesmo pull continuará a encontrar a execução.
• Dois checkouts do mesmo repositório na mesma máquina recebem ficheiros distintos (caminhos absolutos diferentes).
• Mover o projeto (mv ~/Projects/foo ~/Projects/bar) entre push e pull invalida a pesquisa, porque o hash muda. O JSON continua em ~/.lingo/runs/ se precisar de recuperar manualmente o ID da execução.

Este ficheiro é estado por máquina, não estado do projeto — não está em gitignore 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 Supabase; o fluxo --api-key armazena a chave). Não recebem commit 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 à procura do .lingo/config.json mais próximo. Executar lingo push a partir de src/components/ escreve o respetivo lockfile de volta na raiz do projeto, e não cria um novo .lingo/ em components/. Assim, não tem de fazer cd para a raiz antes de cada comando.