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 compact JSON (no indentation) to limit file size.

​
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": {
      "source_hash": "7f4f7d..."
    }
  }
}
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.
    • source_hash: fingerprint of the source segment. New writes use a 32-character lowercase hex prefix of SHA-512. Older lockfiles may still store the full 128-character hex digest; both forms are accepted when deciding whether to skip work.
    • task_hash: when present, fingerprint of task dimensions (model, prompt, context fields, and related inputs). It uses the same encoding rules as source_hash.

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