Skip to main content

​
Canonical file name

The lockfile name is fixed to .hyperlocalise.lock.json. hyperlocalise does not currently read i18n.lock or other alias names. Keep the file in your project root so run and sync commands share the same checkpoint state. The CLI writes the lockfile as indented JSON so diffs are readable. It keeps file size down by grouping task entries by target path and storing short field names.

​
What the lockfile is for

Treat the lockfile as an advisory checkpoint, not your source of truth.
  • Source of truth for translatable content is your source files.
  • Source of truth for generated output is your target files.
  • Source of truth for synced remote state is your TMS plus local artifacts.
The lockfile only records what the CLI already attempted or completed so it can skip repeated work. It is not used to prove that a sync push is safe. Sync safety comes from current local files plus a fresh remote baseline read at execution time.

​
Schema

Current shape: 
{
  "adapter": "crowdin",
  "project_id": "12345",
  "last_pull_at": "2026-01-15T12:34:56Z",
  "locale_states": {
    "es-ES": {
      "revision": "rev_abc123",
      "updated_at": "2026-01-15T12:00:00Z"
    }
  },
  "run_completed": {
    "apps/web/lang/es-ES.json": {
      "checkout.submit": {
        "s": "7f4f7d...",
        "t": "1a2b3c..."
      }
    }
  }
}
Field meanings:
  • adapter: active TMS adapter name.
  • project_id: adapter-specific project identifier.
  • last_pull_at: timestamp of the latest successful sync pull.
  • locale_states: per-locale checkpoint map.
    • revision: adapter revision or cursor for incremental pull logic.
    • updated_at: last time that locale checkpoint was refreshed.
  • run_completed: per-task completion map used by run for skip decisions. Current writes group entries by target path.
    • nested key: entry key inside the target file.
    • s: fingerprint of the source segment.
    • t: fingerprint of task dimensions, such as model, prompt, context fields, and related inputs.
  • active_run_id: identifier for an in-progress run. It is cleared after a successful run.
  • run_checkpoint: temporary per-task output checkpoint for interrupted runs. It is grouped by target path and cleared after a successful run.
    • r: run identifier.
    • p: source path.
    • l: target locale.
    • v: staged output value.
    • s, t, and u: source fingerprint, task fingerprint, and update timestamp.
New writes use a 32-character lowercase hex prefix of SHA-512 for fingerprints. Older lockfiles may still store flat target::entry keys and full field names such as source_hash and task_hash. They may also store full 128-character hex digests. The CLI accepts both shapes and both digest lengths.

​
Lifecycle by command

​
hyperlocalise run

  • Reads .hyperlocalise.lock.json when planning tasks.
  • Skips work already marked complete in run_completed.
  • Persists successful tasks back to run_completed.

​
hyperlocalise sync pull

  • May read existing adapter and locale checkpoint metadata as a performance hint.
  • Fetches a fresh remote snapshot for the requested scope.
  • Updates adapter, project_id, last_pull_at, and locale_states after successful pull.

​
hyperlocalise sync push

  • May read adapter/project context from the lockfile.
  • Does not require lockfile or sidecar metadata to authorize writes.
  • Computes push diffs from local files plus a fresh remote baseline for the same scope.
  • Does not replace source/target content authority.

​
Safe reset guidance

Reset the lockfile when checkpoint state is stale or no longer trustworthy. Common reset cases:
  • you changed source text structure heavily
  • you changed bucket mappings or file path templates
  • you switched adapters or projects
  • you suspect corrupted or manually edited checkpoint entries
Safe reset steps:
  1. ensure your source and generated files are committed or backed up
  2. delete .hyperlocalise.lock.json
  3. run hyperlocalise run --dry-run to inspect the larger plan
  4. run hyperlocalise run and/or hyperlocalise sync pull to rebuild checkpoint state
Expected side effects after reset:
  • run may re-execute tasks that were previously skipped
  • next sync pull may perform a broader refresh for locales
  • CLI runtime can increase temporarily until checkpoints are rebuilt

​
Team conventions

  • Do not hand-edit lockfile fields unless debugging a local incident.
  • Keep lockfile handling explicit in CI scripts.
  • Review lockfile changes in pull requests when run/sync behavior looks unexpected.