Configuração · Lingo.dev

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.

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 (depois de `link`)	Organização proprietária do motor.
`engineId`	sim (depois de `link`)	Motor que faz a tradução. Inclui a configuração do modelo, glossário e voz da marca.
`sourceLocale`	sim	Código de idioma dos seus ficheiros de origem (por exemplo, `"en"`). Os ficheiros de origem são lidos, nunca escritos.
`targetLocales`	sim	Idiomas para os quais traduzir. Os resultados são escritos no mesmo diretório da origem, com o código de idioma substituído no padrão (`locales/en.json` → `locales/de.json`).
`files`	sim	Array de padrões de origem. `pattern` é um glob (barras normais, recursão `*`, wildcards ``). A CLI substitui os códigos de idioma ao resolver os caminhos de destino.
`github`	não	Definições da 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 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.

Os comandos push, pull e purge também verificam para onde cada caminho aponta efetivamente. Se um ficheiro de origem, um ficheiro de destino, .lingo/lock.json ou .lingo/config.json apontar para fora da raiz do projeto ou para dentro de .git — por exemplo, através de uma ligação simbólica —, o comando é interrompido com um erro antes de qualquer leitura, escrita ou eliminação nesse local. As ligações que apontam para dentro do projeto continuam a funcionar, mas, se um ficheiro de destino ou Lockfile for uma ligação, não será feita qualquer escrita através dessa ligação. Num monorepo, execute a CLI a partir de uma raiz que contenha os ficheiros partilhados, em vez de criar ligações para esses ficheiros a partir de um pacote.

`.lingo/lock.json` — com commit#

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

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.
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 de origem só são registados no ficheiro de bloqueio quando uma execução é concluída (lingo push --wait, ou lingo pull depois), pelo que uma execução com falha ou cancelada pode ser repetida sem necessidade de 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 --wait novamente.

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

Regista o push submetido mais recentemente para que o lingo pull saiba de que execução deve ir buscar os resultados — funciona mesmo depois de fechar o terminal, na mesma máquina e a partir do 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 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.

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

.lingo/config.json — com commit#