Lockfile e cache

Mantenha as bases de referência da origem, os hashes de destino, os artefatos remotos e o ponteiro local de execução conectados durante as atualizações e a recuperação.

A tradução incremental precisa saber o que mudou. .lingo/lock.json registra os hashes de origem e destino; o servidor mantém os artefatos e os resultados da tradução; um ponteiro no diretório pessoal identifica a execução mais recente a ser coletada. Cada um atende a uma operação diferente, por isso excluir um não é uma solução geral para corrigir outro.

A base de referência do projeto #

O Lockfile usa a versão 1 e um mapa files que associa caminhos relativos ao repositório a hashes SHA-256:

json
{
  "version": 1,
  "files": {
    "locales/en.json": {
      "sha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
    }
  }
}

Este hash serve apenas para ilustrar o formato, não para ser copiado. Os hashes de origem identificam os bytes anteriores para a comparação incremental. Os hashes de destino ajudam a detectar edições locais antes da coleta. O arquivo não contém texto traduzido nem avaliação de qualidade.

Inclua o Lockfile no commit junto com as alterações aceitas de origem e destino que ele descreve. Se o estado estiver ausente, o push se comporta como na criação da primeira base de referência; se estiver malformado ou não for compatível, a operação falha em vez de redefini-lo silenciosamente.

Quando os hashes são atualizados #

A coleta registra os hashes dos destinos concluídos. O envio sem coleta não consolida a base de referência. Cada documento é consolidado separadamente, e seus destinos ficam retidos até que todos sejam concluídos. Uma base de referência existente para a origem inteira só é atualizada quando o documento abrange todos os idiomas de destino configurados, todos os destinos estão concluídos e nenhum escopo de chaves está definido. A coleta de apenas alguns idiomas mantém essa base para os demais; também pode inicializar uma entrada de origem, caso ainda não exista. Uma atualização de chave mantém o hash de origem inalterado, seja a coleta feita por push --wait ou por pull.

Artefatos e traduções em cache #

Os artefatos são endereçados pelo conteúdo, então o push envia apenas os bytes que o servidor ainda não tem. Uma versão anterior da origem indicada pelo Lockfile precisa ser recuperável a partir dos bytes locais ou do servidor. Se não estiver disponível em nenhum dos dois, examine a entrada indicada no Lockfile e recupere bytes comprovadamente válidos ou uma base de referência coerente. Não use um hash por suposição.

Os resultados de tradução em cache são diferentes do armazenamento da origem. Excluir um destino local não garante que uma solicitação posterior fará uma nova chamada ao modelo.

O ponteiro da execução mais recente #

~/.lingo/runs/<project-hash>.json identifica o push mais recente para um caminho absoluto do diretório raiz do projeto. Ele inclui os IDs da execução, da organização e do engine de localização, o idioma de origem e a data e hora de criação. Até que o push seja coletado, também mantém a identidade da solicitação, permitindo que um push repetido reutilize o envio em vez de duplicá-lo.

Esse ponteiro não é .lingo/run.json e não é transportado pelo Git. Um checkout movido ou outro executor pode não ter o ponteiro, mesmo com a mesma configuração e o mesmo Lockfile. Um novo push pode substituí-lo. Mantenha a identidade original da execução em registros operacionais sem segredos até concluir a recuperação.

Preservar uma execução para outra tarefa de CI #

Para aguardar uma revisão ou separar o envio e a recuperação em tarefas distintas, preserve o ponteiro antes que o executor responsável pelo envio seja descartado. Execute isto no diretório absoluto que contém o .lingo/config.json desejado, imediatamente após o envio e antes de outro push:

sh
node --input-type=module <<'JS'
import { createHash } from "node:crypto";
import { copyFileSync, existsSync, mkdirSync, writeFileSync } from "node:fs";
import { homedir } from "node:os";
import { join } from "node:path";

const root = process.cwd();
if (!existsSync(".lingo/config.json")) throw new Error("Run from the configured project root");
const hash = createHash("sha256").update(root).digest("hex").slice(0, 16);
mkdirSync(".lingo-ci", { recursive: true });
copyFileSync(join(homedir(), ".lingo", "runs", `${hash}.json`), ".lingo-ci/run.json");
writeFileSync(".lingo-ci/project-root.txt", root);
JS

Esses dois arquivos contêm o ponteiro de execução sem segredos e o caminho absoluto exato do diretório raiz do projeto usado para localizá-lo. Verifique se runId no JSON exportado corresponde ao ID exibido neste envio; um ponteiro anterior pode permanecer quando o envio falha antes de registrar uma nova execução. Guarde os arquivos verificados como artefatos de tarefa com acesso controlado, junto com a revisão do código-fonte, .lingo/config.json, .lingo/lock.json e os arquivos de origem e destino correspondentes, incluindo os resultados ainda não incluídos em um commit. Para os exemplos de CI com um único arquivo, guarde locales/en.json e locales/es.json; em outro projeto, use os caminhos efetivamente selecionados. Preserve todo o catálogo compartilhado quando a origem e os destinos usarem um único arquivo. Configure um período de retenção dos artefatos suficiente para a revisão e a coleta. Nunca arquive todo o conteúdo de ~/.lingo, arquivos de credenciais ou valores secretos de ambiente.

Após a revisão, restaure a mesma revisão do código e o estado dos arquivos preservados no mesmo diretório raiz absoluto do projeto, em um executor autorizado. Instale a mesma versão da CLI e forneça as credenciais separadamente pelo mecanismo de segredos do executor. A partir desse diretório raiz, restaure apenas este ponteiro:

sh
node --input-type=module <<'JS'
import { createHash } from "node:crypto";
import { copyFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
import { homedir } from "node:os";
import { join } from "node:path";

const root = readFileSync(".lingo-ci/project-root.txt", "utf8");
if (process.cwd() !== root || !existsSync(".lingo/config.json")) {
  throw new Error("Restore the configured project at its original absolute root");
}
const hash = createHash("sha256").update(root).digest("hex").slice(0, 16);
const directory = join(homedir(), ".lingo", "runs");
mkdirSync(directory, { recursive: true });
const destination = join(directory, `${hash}.json`);
if (existsSync(destination)) throw new Error("Preserve the existing run pointer before replacing it");
copyFileSync(".lingo-ci/run.json", destination);
JS
lingo pull --dry-run

Confirme que a execução informada é a que foi preservada, resolva eventuais conflitos e, em seguida, use lingo pull e examine os resultados recuperados. Não faça um push antes disso, pois ele substitui o ponteiro. Se o serviço de CI não puder recriar o diretório raiz original, use um executor persistente autorizado com esse caminho para o envio e a recuperação; copiar o ponteiro para um checkout em outro local não é suficiente. Remova a exportação temporária de .lingo-ci somente após a conclusão da coleta e do período de retenção operacional, e não a inclua nos commits de tradução.

Traduções existentes e edições humanas #

O planejamento com escopo definido ou de inicialização pode adotar destinos já existentes. Primeiro, verifique se estão no idioma correto e completos: textos provisórios no idioma de origem podem passar em uma verificação de presença sem serem traduções. O preenchimento retroativo cria arquivos comuns ausentes, não chaves ausentes em um arquivo existente.

O processamento incremental normal fornece as edições de destino das chaves inalteradas para que sejam preservadas. Alterações nas chaves de origem podem substituir essas edições. O JSON usa os caminhos das chaves como identificadores, por isso renomear uma chave gera novo trabalho mesmo que o texto de origem seja idêntico; isso difere da reutilização por impressão digital do conteúdo da v0.

preservedKeys adiciona uma proteção explícita quando o texto de destino deve continuar sendo a referência definitiva, mas forçar o arquivo inteiro remove o contexto do destino atual necessário para essa proteção. O pull compara hashes recém-calculados antes de gravar; um commit do Git, por si só, não altera essa comparação. Evite editar destinos durante a coleta direta por push --wait.

Branches e gravação compartilhada #

OrganizaçãoConsequência
Traduzir na branch da funcionalidadeRevise a origem e o destino juntos; concilie edições conflitantes da base de referência durante os rebases.
PR de tradução após a mesclagem da origemRevisão separada, com um intervalo até que as alterações traduzidas sejam aceitas.
PR de tradução do GitHub AppA integração controla os gatilhos e a gravação dos resultados; a aprovação da execução é separada da mesclagem.
Executor autorizado grava diretamente em uma branchExige autorização explícita de gravação, verificações de conteúdo e proteção contra gravações simultâneas.

Em caso de conflito de mesclagem do Lockfile, primeiro identifique as revisões de origem e destino que cada lado descreve. Concilie o conteúdo aceito e, em seguida, mantenha ou reconstrua uma base de referência coerente pelo workflow adequado. Combinar hashes sem relação entre si ou excluir o Lockfile para silenciar um conflito pode ocultar traduções inacabadas.

A configuração do provedor está em GitHub App, GitHub Actions, GitLab, Bitbucket ou Buildkite. check compara as fontes configuradas com este Lockfile e indica quais arquivos de destino estão faltando. Exceto nos catálogos React .jsonc, ele não verifica as chaves nesses arquivos.

Outros estados locais no diretório pessoal #

~/.lingo/update-check.json mantém as verificações de versão em cache por 24 horas. As credenciais e a identidade de telemetria anônima são armazenadas separadamente. Nenhum desses estados contém os arquivos traduzidos resultantes. Use Solução de problemas para identificar a operação que falhou antes de remover o estado.