Lockfile e cache

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

A tradução incremental precisa de saber o que mudou. .lingo/lock.json regista os hashes de origem e de destino; o servidor conserva os artefactos e os resultados da tradução; um apontador local, no diretório pessoal, identifica a execução mais recente a recolher. Cada elemento serve uma operação diferente, pelo que eliminar um não resolve, de forma geral, os problemas de outro.

A base de referência do projeto #

O Lockfile utiliza 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 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 detetar alterações locais antes da recolha. O ficheiro não contém texto traduzido nem avaliações de qualidade.

Inclua o Lockfile no mesmo commit que as alterações aceites de origem e de destino que descreve. Se o estado estiver em falta, push comporta-se como na criação da primeira base de referência; se o estado estiver malformado ou não for suportado, a operação falha em vez de o repor silenciosamente.

Quando avançam os hashes #

A recolha regista os hashes dos destinos concluídos. A submissão sem recolha não consolida a base de referência. Cada documento é consolidado separadamente, ficando os restantes destinos desse documento retidos até estarem todos concluídos. Uma base de referência existente para a totalidade da origem só avança quando o documento abrange todos os idiomas de destino configurados, todos os destinos estão concluídos e não está definido qualquer âmbito de chaves. A recolha de apenas alguns idiomas mantém essa base de referência para os restantes; pode inicializar uma entrada de origem caso ainda não exista. Uma atualização de chaves mantém o hash de origem inalterado, quer a recolha seja feita por push --wait ou por pull.

Artefactos e traduções em cache #

Os artefactos são endereçados pelo conteúdo, pelo que push envia apenas os bytes que faltam no servidor. Uma versão anterior da origem identificada no Lockfile tem de poder ser recuperada a partir dos bytes locais ou do servidor. Se não estiver disponível em nenhum dos dois, inspecione a entrada indicada no Lockfile e recupere bytes comprovadamente corretos ou uma base de referência coerente. Não recorra a um hash por adivinhação.

Os resultados de tradução em cache são distintos do armazenamento da origem. Eliminar um destino local não garante que um pedido posterior invoque novamente o modelo.

O apontador da execução mais recente #

~/.lingo/runs/<project-hash>.json identifica o push mais recente para um caminho absoluto da raiz do projeto. Inclui os IDs da execução, da organização e do motor de localização, o idioma de origem e a data e hora de criação. Até à recolha do push, conserva também a identidade do pedido, que permite a um push repetido reutilizar a submissão em vez de a duplicar.

Este apontador não é .lingo/run.json nem acompanha o Git. Um checkout movido ou outro executor pode não ter o apontador, mesmo com uma configuração e um Lockfile idênticos. Um novo push pode substituí-lo. Guarde a identidade da execução original em registos operacionais não secretos até a recuperação estar concluída.

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

Se for necessário aguardar uma revisão ou separar a submissão e a recuperação em tarefas distintas, preserve o apontador antes de o executor responsável pela submissão deixar de estar disponível. Execute o seguinte a partir do caminho absoluto do diretório que contém o .lingo/config.json pretendido, imediatamente após a submissão 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

Estes dois ficheiros contêm o apontador não secreto da execução e o caminho absoluto exato da raiz do projeto utilizado para o localizar. Verifique se runId no JSON exportado corresponde ao ID apresentado por esta submissão; um apontador anterior pode manter-se quando a submissão falha antes de registar uma nova execução. Conserve os ficheiros verificados como artefactos da tarefa com controlo de acesso, juntamente com a revisão da origem, .lingo/config.json, .lingo/lock.json e os ficheiros de origem e de destino correspondentes, incluindo resultados ainda não incluídos num commit. Para os exemplos de CI com um único ficheiro, conserve locales/en.json e locales/es.json; noutro projeto, utilize os caminhos efetivamente selecionados. Preserve o catálogo partilhado completo quando a origem e os destinos utilizarem um único ficheiro. Configure um período de retenção dos artefactos suficientemente longo para permitir a revisão e a recolha. Nunca arquive a totalidade de ~/.lingo, ficheiros de credenciais ou valores secretos de variáveis de ambiente.

Após a revisão, restaure a mesma revisão e o estado dos ficheiros conservados no mesmo caminho absoluto da raiz do projeto, num executor autorizado. Instale a mesma versão da CLI e forneça as credenciais separadamente através do respetivo mecanismo de segredos. A partir dessa raiz, restaure apenas este apontador:

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 indicada é a que foi preservada, resolva eventuais conflitos e, em seguida, utilize lingo pull e inspecione os resultados recuperados. Não execute push primeiro, pois isso substitui o apontador. Se o serviço de CI não conseguir recriar a raiz original, utilize um executor autorizado persistente com esse caminho para a submissão e a recuperação; copiar o apontador para um checkout noutra localização não é suficiente. Remova a exportação temporária .lingo-ci apenas depois de concluídas a recolha e a retenção operacional, e não a inclua nos commits de tradução.

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

O planeamento com âmbito limitado ou de inicialização pode adotar os destinos existentes. Verifique primeiro o idioma e se estão completos: os marcadores de posição no idioma de origem podem passar numa verificação de presença sem serem traduções. O preenchimento de elementos em falta cria ficheiros normais que ainda não existem, mas não acrescenta chaves em falta a um ficheiro existente.

O trabalho incremental normal disponibiliza as alterações de destino das chaves inalteradas para que sejam preservadas. As chaves de origem alteradas podem levar à substituição dessas alterações. O JSON utiliza os caminhos das chaves como identificadores, pelo que mudar o nome de uma chave cria novo trabalho, mesmo que o texto de origem seja idêntico; este comportamento difere da reutilização por impressão digital do conteúdo da v0.

preservedKeys acrescenta proteção explícita quando o texto de destino deve continuar a prevalecer, mas forçar o ficheiro completo remove o contexto do destino atual necessário para essa proteção. O pull compara hashes atualizados antes de escrever; um commit Git, por si só, não altera essa comparação. Evite editar os destinos durante a recolha direta com push --wait.

Ramos e processos de escrita partilhados #

AbordagemConsequência
Traduzir no ramo da funcionalidadeReveja a origem e o destino em conjunto; concilie as alterações concorrentes à base de referência durante as operações de rebase.
PR de tradução após a integração da origemRevisão separada, com um intervalo até à aceitação das alterações traduzidas.
PR de tradução da GitHub AppA integração controla os acionadores e a escrita dos resultados; a aprovação da execução é independente da integração do PR.
Um executor autorizado escreve diretamente num ramoExige autorização explícita de escrita, verificações de conteúdo e proteção contra processos de escrita concorrentes.

Num conflito de integração do Lockfile, identifique primeiro as revisões de origem e de destino que cada lado descreve. Concilie o conteúdo aceite e, em seguida, conserve ou reconstrua uma base de referência coerente através do workflow adequado. Combinar hashes sem relação entre si ou eliminar o Lockfile para fazer desaparecer um conflito pode ocultar traduções por concluir.

A configuração do fornecedor é descrita em GitHub App, GitHub Actions, GitLab, Bitbucket ou Buildkite. check compara as fontes configuradas com este Lockfile e indica os ficheiros de destino em falta. Exceto nos catálogos .jsonc do React, não verifica as chaves no interior desses ficheiros.

Outros estados locais no diretório pessoal #

~/.lingo/update-check.json guarda em cache as verificações de versão durante 24 horas. As credenciais e a identidade de telemetria anónima são guardadas separadamente. Nenhum destes elementos guarda os resultados dos ficheiros traduzidos. Utilize Resolução de problemas para identificar a operação que falhou antes de remover o estado.