> ## Documentation Index
> Fetch the complete documentation index at: https://hyperlocalise.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# 锁文件契约

> 了解 `.hyperlocalise.lock.json` 存储了什么、何时重置它，以及为什么它只是建议性的。

## 规范文件名

锁文件名固定为 `.hyperlocalise.lock.json`。

`hyperlocalise` 当前不读取 `i18n.lock` 或其他别名。

将文件保留在项目根目录中，这样 `run` 和同步命令就会共享同一个检查点状态。

CLI 会将锁定文件写为**缩进的 JSON**，这样差异更易于阅读。它通过按目标路径对任务条目分组并使用较短的字段名来减小文件大小。

## 锁文件的用途是什么

将锁文件视为一个**建议性检查点**，而不是你的真实来源。

* 可翻译内容的真实来源是你的源文件。
* 生成输出的真实来源是你的目标文件。
* 同步远程状态的真实来源是你的 TMS 加上本地工件。

锁文件只记录 CLI 已经尝试过或已完成的内容，这样它就可以跳过重复的工作。

它不用于证明同步推送是安全的。同步安全性来自当前本地文件加上执行时读取的新鲜远程基线。

## 模式

当前形状：

```json theme={null}
{
  "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..."
      }
    }
  }
}
```

字段含义：

* `adapter`：活动的 TMS 适配器名称。
* `project_id`：适用于适配器的项目标识符。
* `last_pull_at`：最近一次成功同步拉取的时间戳。
* `locale_states`：按语言环境的检查点映射。
  * `revision`：用于增量拉取逻辑的适配器版本或游标。
  * `updated_at`：上次刷新该区域检查点的时间。
* `run_completed`：由 `run` 用于跳过决策的按任务完成映射。当前写入按目标路径对条目分组。
  * 嵌套键：目标文件中的条目键。
  * `s`：源片段的指纹。
  * `t`：任务维度的指纹，例如模型、提示、上下文字段以及相关输入。
* `active_run_id`：进行中的运行标识符。成功运行后会清除。
* `run_checkpoint`：用于中断运行的每任务临时输出检查点。它按目标路径分组，并在成功运行后清除。
  * `r`：运行标识符。
  * `p`：源路径。
  * `l`：目标语言环境。
  * `v`：暂存输出值。
  * `s`、`t` 和 `u`：源指纹、任务指纹和更新时间戳。

新的写入使用 SHA-512 的 **32 个字符**小写十六进制前缀作为指纹。较旧的锁文件可能仍然存储扁平的 `target::entry` 键以及完整字段名，例如 `source_hash` 和 `task_hash`。它们也可能存储完整的 **128 个字符**十六进制摘要。CLI 同时接受这两种结构和这两种摘要长度。

## 命令生命周期

### `hyperlocalise run`

* 为请求的范围获取一个新的远程快照。
* 在成功拉取后更新 `adapter`、`project_id`、`last_pull_at` 和 `locale_states`。
* 可从锁文件中读取适配器/项目上下文。

### `hyperlocalise sync pull`

* 授权写入时不需要 lockfile 或 sidecar 元数据。
* 从本地文件加上同一范围的新远程基线计算推送差异。
* 不替换源/目标内容权限。

### `hyperlocalise sync push`

* 你大幅更改了源文本结构
* 你更改了存储桶映射或文件路径模板
* 你切换了适配器或项目
* 您怀疑检查点条目已损坏或被手动编辑

## 团队约定

常见的重置情况：

安全重置步骤：

* 除非是在调试本地故障，否则不要手动编辑锁文件字段。
* 在 CI 脚本中显式处理 lockfile。
* 在拉取请求中审查锁定文件变更，当运行/同步行为看起来不符合预期时。
* `run` 可能会重新执行先前被跳过的任务

重置后的预期副作用：

1. 确保你的源文件和生成的文件已提交或已备份
2. 删除 `.hyperlocalise.lock.json`
3. 运行 `hyperlocalise run --dry-run` 以检查更大的计划
4. 运行 `hyperlocalise run` 和/或 `hyperlocalise sync pull` 以重建检查点状态

当检查点状态已过期或不再可信时，重置锁文件。

* 下一次同步拉取可能会对区域设置执行更广泛的刷新
* CLI 运行时可能会临时增加，直到检查点重建完成
* 可将现有适配器和区域设置检查点元数据作为性能提示进行读取。

## 安全重置指南

* 将成功的任务持久化回 `run_completed`。
* 跳过已在`run_completed`中标记为完成的工作。
* 在规划任务时读取 `.hyperlocalise.lock.json`。