---
title: "翻译缓存"
description: "verbatra.cache.json 在多次运行之间复用什么、指纹如何把每个条目限定在其配置内，以及缓存问题为何不会让运行失败。"
type: "concept"
---
# 翻译缓存

verbatra.cache.json 在多次运行之间复用什么、指纹如何把每个条目限定在其配置内，以及缓存问题为何不会让运行失败。

翻译缓存 `verbatra.cache.json` 是按内容建立键的本地翻译记忆库：它记住一段源文本的译文，不论是哪个键持有这段文本，因此同一段文本不会重复付费。[锁文件与来源记录](https://verbatra.kreitz-webdev.de/zh-CN/docs/the-lock-file.md)回答“这个键是不是最新的？”，缓存回答“这段文本以前翻译过吗？”。

## 复用什么 [#复用什么]

键交给提供商之前，verbatra 会查找其当前源条目的哈希：文本加上它的描述、含义、复数标志和占位符。命中不产生花费。查找按内容进行，所以复用能覆盖锁文件看不到的情况：

- **重命名的键**：把 `home.title` 移到 `landing.title`，它的译文照样复用。
- **重复的内容**：源文本和上下文相同的两个键共用一条译文。

复用的值不会被盲目信任。它要像新译文一样，对照当前源值通过同一个[完整性门禁](https://verbatra.kreitz-webdev.de/zh-CN/docs/translation-safety.md#完整性门禁)，不再适用的值会被丢弃并重新翻译。缓存命中按语言环境单独报告，与本次运行翻译的键分开。

审校人员[拒绝](https://verbatra.kreitz-webdev.de/zh-CN/docs/the-lock-file.md#审校决定)的值绝不会再复用到该键：来源记录文件保存了被拒绝文本的哈希，运行会跳过与之匹配的任何命中。唯一的缺口是运行无法读取来源记录文件的情况（文件来自更新的 verbatra，或在 `humanEdits: "overwrite"` 下已损坏），此时运行不知道任何拒绝记录。

## 指纹 [#指纹]

每个条目都限定在生成它的上下文中：指纹由提供商、模型、该语言环境的语气、该语言环境的术语表术语，以及提供商的 [`localeMap`](https://verbatra.kreitz-webdev.de/zh-CN/docs/providers.md#发送给提供商的语言环境代码)（有条目时）共同计算。其中任何一项更改，之前的条目就不再匹配，所以更换语气或编辑术语表后，缓存不会返回过期的结果。已写入的值会保持不变，直到你重新翻译它们。术语表部分是 verbatra 会发送给提供商的术语，已应用任何会搁置或脱敏某个术语的 `sensitiveData` 设置，不论所配置的提供商是否使用术语表术语（DeepL、Google Cloud Translation 和 LibreTranslate 会忽略它们），所以编辑过的术语仍会触发重新翻译。术语的 `caseSensitive` 标志不属于指纹。每个语言环境都有自己的指纹，因此只编辑某个术语的德语译文，法语条目仍然匹配。

格式不属于指纹，每次命中时的完整性门禁会拦住不再适用的值。提供商为 `none` 时，所有条目都进入同一个纯人工分组，语气和术语表对它没有影响。

## 模糊复用 [#模糊复用]

<AvailableFrom version="0.11.0" />

精确命中要求源文本的哈希与之前相同，所以编辑一个字符就会未命中。[`fuzzyCache`](https://verbatra.kreitz-webdev.de/zh-CN/docs/config-file.md#fuzzycache) 是针对这种情况的可选回退：键未命中时，verbatra 把它的源文本与同一语言环境、同一指纹下的其他条目打分，复用得分达到或超过 `threshold` 的最接近的一条。得分为 1 减去字符编辑距离除以较长字符串的长度，所以 `1` 表示完全相同。

### 阈值不是安全设置 [#阈值不是安全设置]

字符距离不等于含义。去掉一个“not”、把“cannot”改成“can”或换掉一个品牌名，都是得分高于 `0.9` 的小改动，却会让句子意思相反。阈值决定你能少花多少提供商费用，而不是复用有多安全。安全来自与这个数字无关的规则：

- **除非你开启，否则默认关闭**。
- **每次模糊复用都会标记为待审校**，使用 [`FUZZY_CACHE_REUSE`](https://verbatra.kreitz-webdev.de/zh-CN/docs/error-codes.md#fuzzy_cache_reuse)，每次运行都如此，不论得分多少。如果没有人处理审校队列（**Review queue**，见[在 Studio 中审校](https://verbatra.kreitz-webdev.de/zh-CN/docs/review-in-studio.md)），请保持关闭。
- **数字变了就拒绝复用**：两个源文本中的数字在个数、值或顺序上不同，该条目就不是候选。这涵盖所有 Unicode 数字字符（`m²` 到 `m³`、`½` 到 `¼`），但不包括用文字写出的数字。
- **复用不会让键定稿**：锁文件保留该键原来的基线，所以它仍是已更改状态：之后每次运行都会再次提供它，不产生提供商费用，[`check`](https://verbatra.kreitz-webdev.de/zh-CN/docs/cli/check.md) 也会一直报告它，直到真正的译文写入。
- **未更改的源文本不会进入模糊层**：只编辑描述或复数标志时，该键照常发送给提供商。

### 模糊复用仍然不是什么 [#模糊复用仍然不是什么]

模糊复用的译文对应的是已经不再作为源文本的旧文本，所以从不当作精确命中呈现：

- 它像其他候选译文一样要通过完整性门禁；占位符不再适用的近似匹配会被拒绝，该键转交提供商。
- 它与精确命中分开报告，记为 `fuzzy-reused`，附键、得分和之前的源文本；SDK 在 `LocaleSummary.fuzzyHits` 上提供同样的信息。
- 它不会写回缓存，所以之后的运行不会把它误认为精确命中。

打分只在同一个指纹内进行，并有上限：每个键最多 256 个候选，超过 2,000 个字符的源文本会被跳过。提供商为 `none` 时，不会应用模糊匹配。

## 文件 [#文件]

`verbatra.cache.json` 是位于锁文件旁边的本地可再生文件。不要将它纳入版本控制：它是费用优化，不是共享基线。`verbatra init` 会把它加入 gitignore，`translate`、`watch`、`import`、`tmx import` 和 `pseudo` 会在现有 `.gitignore` 缺少该条目时补上，并在 stderr 中说明。

缓存绝不会让运行失败。缺失、损坏或过大的文件会变成空缓存并重建。来自更新的 verbatra 的文件在本次运行中同样视为空，但会原样留在磁盘上，并给出通知。要重新开始，删除该文件即可。为了模糊打分，文件会把每个源字符串存放在其译文旁边，所以文件大小大致增长到你的源文本的规模。

## 在工具之间迁移翻译记忆库 [#在工具之间迁移翻译记忆库]

<AvailableFrom version="0.11.0" />

[`verbatra tmx`](https://verbatra.kreitz-webdev.de/zh-CN/docs/cli/tmx.md) 把另一个翻译工具的 TMX 文件导入缓存，也把缓存导出为 TMX。导入的单元存放在当前指纹下，所以提供商、模型、语气、verbatra 会发送的术语表术语或 `localeMap` 更改时，它们和其他内容一样不再匹配。关于“删除后会重建”有一个例外：导入的翻译记忆库只能从它来源的 TMX 文件恢复，所以请保留该文件。

## 绕过缓存 [#绕过缓存]

在 [`translate`](https://verbatra.kreitz-webdev.de/zh-CN/docs/cli/translate.md) 或 [`watch`](https://verbatra.kreitz-webdev.de/zh-CN/docs/cli/watch.md) 上使用 `--no-cache`（SDK 中为 `cache: false`），发出的提供商调用与没有缓存时的运行完全一致（模糊复用也一并绕过），并且不动该文件。要保留精确复用、只去掉模糊回退，请不要在配置中写 `fuzzyCache`。试运行从不写入缓存，只在提供商为 `none` 时读取它，使该计划与实际运行一致。

## 限制 [#限制]

`generatePlurals` 合成的复数形式不会缓存，所以总是来自提供商。

## 相关内容 [#相关内容]

- [`fuzzyCache`](https://verbatra.kreitz-webdev.de/zh-CN/docs/config-file.md#fuzzycache)：该配置项及其取值范围。
- [`verbatra tmx`](https://verbatra.kreitz-webdev.de/zh-CN/docs/cli/tmx.md)：把翻译记忆库导入和导出为 TMX。
- [运行的工作原理](https://verbatra.kreitz-webdev.de/zh-CN/docs/how-it-works.md)：缓存查找在流程中的位置。
- [运行前估算费用](https://verbatra.kreitz-webdev.de/zh-CN/docs/estimating-cost.md)：花费之前缓存能省下什么。
