---
title: "运行翻译"
description: "translate、watch 以及围绕一次运行的各个入口函数，外加伪语言环境和带类型的消息目录，全部可以在你自己的 Node.js 脚本中调用。"
type: "reference"
---
# 运行翻译

translate、watch 以及围绕一次运行的各个入口函数，外加伪语言环境和带类型的消息目录，全部可以在你自己的 Node.js 脚本中调用。

## 翻译与监听 [#run-translations]

### translate [#translate]

一次性流程：读取源文件，把每个目标语言环境与锁文件基线比对，把缺失和已更改的键发给提供商，运行完整性检查，写入语言文件，并更新锁文件。适用于脚本、构建步骤和 CI 任务。

```ts title="签名"
function translate(
  input: TranslateInput,
  deps?: TranslateDeps,
): Promise<RunSummary>;
```

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `config` | `VerbatraConfig` | yes | The resolved project config, normally from loadConfig. |
| `cwd` | `string` | no | Directory the `files.pattern` is resolved against, and where the lock-file, the translation memory, and the run-status file live. Defaults to the project root of the config object loadConfig returned, else the process working directory; a copied or rebuilt config loses that root, so pass `cwd` from resolveProjectRoot. |
| `locales` | `readonly string[]` | no | Restrict the run to a subset of the configured target locales, which is how you translate one locale at a time against a rate-limited provider. Defaults to every configured target. The result keeps the configured order whatever order the subset is given in, and any locale named here that is not a configured target fails the whole run with `UNKNOWN_LOCALE` before anything is read or spent. An explicit empty array selects no locale at all rather than every locale. Locales left out are untouched: their files, their lock entries, and their translation-memory entries all stay as they were. The run-status file always describes the most recent run alone, so a subset run narrows it to that subset. |
| `dryRun` | `boolean` | no | Compute the whole run but write nothing and call no provider. The returned RunSummary reports what would have happened, which makes this safe to run in CI to preview work without spending anything. Defaults to false. In human-only mode (provider `none`) it reads the translation memory, so the plan matches a live run. |
| `estimate` | `boolean` | no | Compute a pre-run cost estimate and return it on RunSummary.estimate. Implies `dryRun`: an estimate constructs no provider, reads no API key, makes no network call, and writes no file, so it is safe to run anywhere. Defaults to false. The figure bounds the plan rather than the invoice: every provider call a live run schedules is counted, plural generation included, and the prompt is measured from the request payload that would be sent. Provider-side retries, a repair round, and a language that expands past the allowance can each push a live run above it; EstimateCaveatCode names them all. It carries a currency amount only when the config supplies a `rates` block covering the configured provider and model; otherwise it reports the quantity and says why the money is missing. See RunEstimate. |
| `prune` | `boolean` | no | Remove keys that no longer exist in the source. Defaults to the config's `prune`, then to false, so orphaned keys are reported but kept unless removal is asked for explicitly. |
| `generatePlurals` | `boolean` | no | Generate the plural categories a target language requires rather than translating each category separately. Defaults to the config's `generatePlurals`, then to false. Takes effect only for the `i18next-json` format with an LLM provider; any other format, a machine-translation provider, and provider `none` generate nothing. |
| `onLockWait` | `LockWaitListener` | no | Called while waiting on another process's write lock, so a CLI can explain a stall instead of appearing to hang. Never called for a lock this process holds itself, such as the lock-file guard a sibling locale holds on a concurrent run. Fires first once a wait has lasted a second. The SDK writes no output itself. |
| `onProgress` | `ProgressListener` | no | Called as locales and sub-batches start and finish, for progress reporting. The SDK writes no output itself. |
| `lockAcquireTimeoutMs` | `number` | no | How long, in milliseconds, to wait for a locale's write lock before that locale fails with `LOCK_CONTENDED`, and for the lock-file guard before a locale whose respelled state could not be moved fails with `LOCALE_STATE_NOT_CARRIED_OVER`. Both waits happen before any provider call. Defaults to ten minutes. It does not bound the lock-file guard a locale takes to record its result once its target file is written: that wait always allows the ten-minute default, so a written file is not left unrecorded. Not used on a dry run, which takes no lock. |
| `concurrency` | `number` | no | How many locales to run at once. Must be an integer of at least 1; defaults to 1. On a live run it cannot be combined with a token budget, configured or passed as `maxTokens`: the ceiling would still hold, but which locale loses its remaining work would depend on the order the locales interleave, so the run would not be reproducible. A whole-run error raised once locales are running starts no further locale, and the locales in flight finish and release their write locks before `translate` rejects, so the rejection arrives after the slowest one. |
| `cache` | `boolean` | no | Consult and update the translation memory, fuzzy reuse included. Defaults to true. Turning it off forces every key through the provider, which is what to do when you want to re-pay for a fresh translation. A dry run never reads the memory, whatever this says, except in human-only mode (provider `none`), where the memory is all a live run would use. The memory is the local CACHE_FILE_NAME file; `false` is the CLI's `--no-cache`. |
| `humanEdits` | `"overwrite" \| "protect" \| "suggest"` | no | Overrides the config's `humanEdits` for this run only (see HumanEditsPolicy). Set `overwrite` to retranslate stale keys a person wrote, as the CLI's `--include-human` flag does. Keys matching the config's `pinnedKeys` stay protected whatever this says. A dry run reads the provenance file too, unless this resolves to `overwrite`. |
| `maxTokens` | `number` | no | A token ceiling for this run alone, as the CLI's `--max-tokens` flag sets it. It is always a hard stop: a provider request that would pass it is withheld rather than sent, whatever the config's `budgetBehavior` says, and its keys are listed in LocaleSummary.budgetWithheld. When the config also sets `maxTokens`, the lower of the two applies, so this can tighten the configured budget but never loosen it. Must be a whole number of at least 1. Defaults to the config's `maxTokens` and `budgetBehavior` alone. |
| `signal` | `AbortSignal` | no | Cancels the run when aborted. No further locale starts, and a wait for a write lock stops. The locales running at the time send no further request, and an in-flight request is abandoned rather than counted as a provider failure, unless the provider reported a failure of its own. What already arrived is still written and recorded, the keys left over get no lock-file entry and stay pending for the next run, the run status is recorded, and every lock is released. The call then resolves rather than rejects: the result carries RunSummary.cancelled, each locale kept from starting is `failed` with the `RUN_CANCELLED` error code, and locales stopped while running carry a `RUN_CANCELLED` notice and are `partial`, or `failed` when no key landed and others were withheld. A dry run only stops early. Defaults to none. |

**返回**：[`RunSummary`](https://verbatra.kreitz-webdev.de/zh-CN/docs/sdk/run-summary.md)

**抛出**：[`UNKNOWN_LOCALE`](https://verbatra.kreitz-webdev.de/zh-CN/docs/error-codes.md#unknown_locale)、[`LOCALE_UNSUPPORTED_BY_PROVIDER`](https://verbatra.kreitz-webdev.de/zh-CN/docs/error-codes.md#locale_unsupported_by_provider)、[`UNKNOWN_FORMAT`](https://verbatra.kreitz-webdev.de/zh-CN/docs/error-codes.md#unknown_format)、[`CONCURRENCY_INVALID`](https://verbatra.kreitz-webdev.de/zh-CN/docs/error-codes.md#concurrency_invalid)、[`CONCURRENCY_BUDGET_CONFLICT`](https://verbatra.kreitz-webdev.de/zh-CN/docs/error-codes.md#concurrency_budget_conflict)、[`MAX_TOKENS_INVALID`](https://verbatra.kreitz-webdev.de/zh-CN/docs/error-codes.md#max_tokens_invalid)、[`LOCK_TIMEOUT_INVALID`](https://verbatra.kreitz-webdev.de/zh-CN/docs/error-codes.md#lock_timeout_invalid)、[`LOCALE_LAYOUT_INVALID`](https://verbatra.kreitz-webdev.de/zh-CN/docs/error-codes.md#locale_layout_invalid)、[`LOCALE_PATH_COLLISION`](https://verbatra.kreitz-webdev.de/zh-CN/docs/error-codes.md#locale_path_collision)、[`SOURCE_UNREADABLE`](https://verbatra.kreitz-webdev.de/zh-CN/docs/error-codes.md#source_unreadable)、[`SOURCE_INVALID`](https://verbatra.kreitz-webdev.de/zh-CN/docs/error-codes.md#source_invalid)、[`PROVIDER_CONSTRUCTION_FAILED`](https://verbatra.kreitz-webdev.de/zh-CN/docs/error-codes.md#provider_construction_failed)、[`NETWORK_POLICY_VIOLATION`](https://verbatra.kreitz-webdev.de/zh-CN/docs/error-codes.md#network_policy_violation)、[`CONFIG_INVALID`](https://verbatra.kreitz-webdev.de/zh-CN/docs/error-codes.md#config_invalid)、[`LOCK_FILE_INVALID`](https://verbatra.kreitz-webdev.de/zh-CN/docs/error-codes.md#lock_file_invalid)、[`PROVENANCE_FILE_INVALID`](https://verbatra.kreitz-webdev.de/zh-CN/docs/error-codes.md#provenance_file_invalid)

**示例**：[翻译并查看摘要](https://verbatra.kreitz-webdev.de/zh-CN/docs/sdk-quickstart.md#翻译并查看摘要)

表格没有涵盖的内容：

- `cache` 是本地[翻译缓存](https://verbatra.kreitz-webdev.de/zh-CN/docs/the-cache.md)（`verbatra.cache.json`，也以 `CACHE_FILE_NAME` 导出）。
- `humanEdits`（自 0.12.0 起）：默认情况下，由人写入、导入或在 verbatra 之外更改且已过期的键会被保留，并列在 `LocaleSummary.protected` 中。见[保留人工翻译](https://verbatra.kreitz-webdev.de/zh-CN/docs/protecting-human-translations.md)。
- `onProgress` 接收下文的[进度事件](#进度事件)。
- `maxBatchSize` 和 `budgetBehavior` 只能在配置中设置，没有按次运行的覆盖值。

影响整次运行的问题会抛出 `SdkError`；单个语言环境失败从不抛出，而是在运行继续的同时，以 `status: "failed"` 出现在该语言环境的条目上。见 [`RunSummary` 的结构](https://verbatra.kreitz-webdev.de/zh-CN/docs/sdk/run-summary.md#runsummary-的结构)。

### 进度事件 [#进度事件]

<AvailableFrom version="0.12.0" />

`onProgress` 接收 `ProgressEvent`，这是以 `type` 区分的联合类型。次版本可能增加类型，所以请忽略不认识的类型。

| `type` | 触发时机 | 字段 |
| --- | --- | --- |
| `locale-started` | 某个语言环境的工作开始 | `locale`、`localeIndex`、`totalLocales` |
| `locale-planned` | 查询翻译记忆库之后、发送第一个批次之前；仅在调用提供商时触发 | `locale`、`keys`、`batches`、`cacheHits` |
| `sub-batch` | 每个翻译批次开始尝试之前 | `locale`、`batchIndex`、`totalBatches` |
| `provider-retry` | 内置提供商重试一个以可重试状态失败的请求 | `attempt`、`delayMs?`、`status?` |
| `repair` | LLM 提供商重新请求其首次响应遗漏的键 | `locale`、`keys` |
| `split-retry` | 输出被截断的批次拆成两半重试 | `locale`、`keys` |
| `batch-finished` | 一个批次已结束，无论成功与否 | `locale`、`batchIndex`、`totalBatches`、`durationMs`、`usage?` |
| `writing` | 写入某个语言环境的文件之前 | `locale` |
| `locale-finished` | 某个语言环境的工作结束 | `locale`、`status`、`translated`、`localeIndex`、`totalLocales` |
| `run-finished` | 每个语言环境都已结束 | `localesCompleted`、`localesFailed` |
| `change-detected` | 仅 `watch`：对源文件的更改已稳定 | `paths` |
| `idle` | 仅 `watch`：一次运行已结束，且没有排队的运行 | 无 |

`provider-retry` 不指明语言环境，因为一个提供商服务整次运行。Gemini 报告延迟和状态；Anthropic、OpenAI、OpenCode 和 openai-compatible 报告其客户端开始该次尝试时的尝试次数；DeepL、Google Cloud Translation 和 LibreTranslate 都不报告。试运行和估算只发出 `locale-started`、`locale-finished` 和 `run-finished`。CLI 的 `--json` 进度记录只保留最初的四种类型：`locale-started`、`sub-batch`、`locale-finished` 和 `run-finished`。

`extract`、带 `unused` 的 `diff` 以及带 `literals` 的 `doctor` 各有自己的 `onProgress`。它接收 `ScanProgressEvent`，即 `{ type: "files-scanned", scanned, total }`，扫描每读取一个应用源文件，就触发一次。

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | `"files-scanned"` | yes | Discriminant, reserved so later scan events can join a union. |
| `scanned` | `number` | yes | How many files have been scanned so far. |
| `total` | `number` | yes | How many files the scan will read in total. |

只要运行报告进度，自定义的 `CreateProvider` 就会收到第三个参数 `CreateProviderHooks`。用 `{ attempt, delayMs?, status? }` 调用它的 `onRetry`，你的提供商的重试就会作为 `provider-retry` 事件出现。

### resolveDryRun [#resolvedryrun]

<AvailableFrom version="0.11.0" />

回答一组运行选项是否会解析为试运行。它接收你即将交给 `translate` 的 `dryRun` 和 `estimate`，并返回该次运行是否会构造提供商、写入文件或产生任何花费。`estimate` 隐含 `dryRun` 这条规则只在这里判定，所以每当围绕一次运行的某个环节需要事先知道结果时，就用它，而不是自己重述这个隐含关系，导致与它不一致。

```ts title="签名"
function resolveDryRun(input: {
  readonly dryRun?: boolean | undefined;
  readonly estimate?: boolean | undefined;
}): boolean;
```

**返回**：`boolean`

```ts title="示例"
import { resolveDryRun, translate, type VerbatraConfig } from "@verbatra/sdk";

declare const config: VerbatraConfig;

const options = { dryRun: false, estimate: true };
resolveDryRun(options); // true

const summary = await translate({ config, ...options });
```

### watch [#watch]

监听源语言文件，在每次经过防抖的更改后重新运行 `translate`。它在启动时立即触发一次初始运行，之后每次稳定的更改触发一次运行。运行是串行的：一次运行期间发生的更改会合并为一次后续运行。

```ts title="签名"
function watch(
  input: WatchInput,
  deps?: WatchDeps,
): Promise<WatchController>;
```

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `config` | `VerbatraConfig` | yes | The resolved project config, normally from loadConfig. |
| `cwd` | `string` | no | Directory the `files.pattern` is resolved against, and where each run's lock-file, translation memory, and run-status file live. Defaults to the project root of the config object loadConfig returned, else the process working directory; a copied or rebuilt config loses that root, so pass `cwd` from resolveProjectRoot. |
| `locales` | `readonly string[]` | no | Restrict every run of the session to a subset of the configured target locales. Validated once when watching starts, so an unconfigured locale throws `UNKNOWN_LOCALE` before any watching begins rather than failing on each run. An explicit empty array selects no locale at all. |
| `debounceMs` | `number` | no | How long to coalesce rapid source changes before running. Defaults to 300 milliseconds. |
| `onRun` | `(result: WatchRunResult) => void` | yes | Called after every run with its outcome. This is the only way to observe a watch session, since watch itself resolves as soon as watching starts. |
| `onReady` | `(() => void)` | no | Called once when the session's startup checks have passed and the watcher is attached, right before the initial run starts, so a caller can announce the session ahead of that run's output. |
| `onLockWait` | `LockWaitListener` | no | Called while waiting on another process's write lock, never for one this process holds. |
| `onProgress` | `ProgressListener` | no | Called as each run plans, sends and writes its locales, and as the watcher detects a change or goes idle, for progress reporting. |
| `lockAcquireTimeoutMs` | `number` | no | How long, in milliseconds, to wait for a locale's write lock, before any provider call, before that locale fails with `LOCK_CONTENDED` on the run's summary. Defaults to ten minutes. The lock-file guard a locale takes to record its result after writing its target file always allows the ten-minute default instead. |
| `concurrency` | `number` | no | How many locales to run at once. Defaults to 1. Validated once when watching starts, and applied to every run. |
| `cache` | `boolean` | no | Consult and update the translation memory, fuzzy reuse included. Defaults to true. |

**返回**：`WatchController`

**抛出**：[`UNKNOWN_LOCALE`](https://verbatra.kreitz-webdev.de/zh-CN/docs/error-codes.md#unknown_locale)、[`LOCALE_UNSUPPORTED_BY_PROVIDER`](https://verbatra.kreitz-webdev.de/zh-CN/docs/error-codes.md#locale_unsupported_by_provider)、[`CONCURRENCY_INVALID`](https://verbatra.kreitz-webdev.de/zh-CN/docs/error-codes.md#concurrency_invalid)、[`LOCK_TIMEOUT_INVALID`](https://verbatra.kreitz-webdev.de/zh-CN/docs/error-codes.md#lock_timeout_invalid)、[`CONCURRENCY_BUDGET_CONFLICT`](https://verbatra.kreitz-webdev.de/zh-CN/docs/error-codes.md#concurrency_budget_conflict)、[`LOCALE_LAYOUT_INVALID`](https://verbatra.kreitz-webdev.de/zh-CN/docs/error-codes.md#locale_layout_invalid)、[`LOCALE_PATH_COLLISION`](https://verbatra.kreitz-webdev.de/zh-CN/docs/error-codes.md#locale_path_collision)、[`SOURCE_UNREADABLE`](https://verbatra.kreitz-webdev.de/zh-CN/docs/error-codes.md#source_unreadable)、[`NETWORK_POLICY_VIOLATION`](https://verbatra.kreitz-webdev.de/zh-CN/docs/error-codes.md#network_policy_violation)、[`PROVIDER_CONSTRUCTION_FAILED`](https://verbatra.kreitz-webdev.de/zh-CN/docs/error-codes.md#provider_construction_failed)、[`CONFIG_INVALID`](https://verbatra.kreitz-webdev.de/zh-CN/docs/error-codes.md#config_invalid)

**示例**：[在长时间运行的进程中监听](https://verbatra.kreitz-webdev.de/zh-CN/docs/programmatic-api.md#在长时间运行的进程中监听)

`debounceMs` 默认为 300。`onRun` 每次运行调用一次，参数是 `WatchRunResult`：`{ status: "succeeded", summary }` 或 `{ status: "failed", error: { code, message, causeCode?, hint? } }`，其中 `causeCode` 指明该失败所包装的带错误码的错误，`hint` 是 `errorHint` 给出的下一步。`onReady` 在启动检查通过之后、初始运行之前调用一次，这样你可以在该次运行的输出之前宣布会话开始。如果 `onReady` 抛出，监听器会关闭，`watch` 返回的 Promise 在任何运行开始之前就以该错误 reject。SDK 不做任何日志记录；`onRun` 是唯一的输出。`concurrency`、`cache`、`onProgress`、`onLockWait` 和 `lockAcquireTimeoutMs` 会传给每次运行，行为与在 `translate` 上完全相同。`locales` 把会话中的每次运行缩小到该子集，并且只在启动时校验一次，而不是每个周期都校验。

返回一个 `WatchController`，它只有一个方法 `stop()`：`stop()` 会关闭监听器，并等待正在进行的运行结束。**抛出**行中的每个错误码都在启动时、监听器存在之前就会抛出，所以 `watch` 返回的 Promise 本身会 reject，而不是返回控制器。其中两个对会话的影响比对单次运行更大：配置设置了 `maxTokens` 时，大于 1 的 `concurrency` 总会抛出 `CONCURRENCY_BUDGET_CONFLICT`，因为不存在试运行监听；自 0.12.0 起，无法构建的提供商（例如其 API 密钥变量未设置）会抛出一次 `PROVIDER_CONSTRUCTION_FAILED`，而不是让每次运行都失败。启动之后的每个失败都通过 `onRun` 呈现，监听继续进行。

### releaseHeldLocks [#releaseheldlocks]

<AvailableFrom version="0.12.0" />

删除当前进程持有的所有写锁，用于即将退出、不再等待正在进行的运行结束的进程：中断停止 `translate` 或 `import` 时，以及第二次中断强制停止 `watch` 时，CLI 会调用它。获得这些锁的运行会失去保护，所以只能在进程退出前一刻调用。它不接受参数，只有在某个持有的锁无法删除时，才在尝试处理完每个锁之后，以列出这些锁路径的 `AggregateError` reject。仍在运行的操作在运行期间正在获取或尝试获取的锁，会以 `RUN_CANCELLED` 被拒绝，并且不留下文件；`releaseHeldLocks` 为这样的获取最多等待 3 秒。

```ts title="签名"
function releaseHeldLocks(): Promise<void>;
```

**返回**：`void`

进程被直接杀死时仍可能遗留锁，但这种锁不需要调用它：同一台机器上等待的运行会发现记录的进程已经不存在，并自行回收这个锁。见[写锁](https://verbatra.kreitz-webdev.de/zh-CN/docs/the-lock-file.md#写锁)。

## 伪本地化 [#伪本地化]

### pseudolocalize [#pseudolocalize]

<AvailableFrom version="0.11.0" />

只根据源字符串构建一个虚构的语言环境，这样在拥有任何 API 密钥之前，就能发现布局被截断，以及从未提取出来供翻译的字符串。每个值都会加上重音符号，按可翻译长度扩展约三分之一，并用 `[` 和 `]` 边界标记包住，而占位符在适配器能识别的所有语法中都保持不变，包括 ICU 的复数和 select 分支、内联标记标签和转义序列。它不构造提供商，不读取 API 密钥，也不发出网络请求。

```ts title="签名"
function pseudolocalize(
  input: PseudolocalizeInput,
  deps?: PseudolocalizeDeps,
): Promise<PseudolocalizeResult>;
```

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `config` | `VerbatraConfig` | yes | The resolved project config, normally from loadConfig. |
| `cwd` | `string` | no | Directory the `files.pattern` is resolved against. Defaults to the project root of the config object loadConfig returned, else the process working directory; a copied or rebuilt config loses that root, so pass `cwd` from resolveProjectRoot. |
| `mode` | `"accented" \| "bidi"` | no | The transform to apply. Defaults to `accented`. `bidi` wraps every word of translatable text in a right-to-left mark and override (`U+200F U+202E` before, `U+202C U+200F` after), so it renders right to left while the stored letters keep their order; placeholders, ICU syntax, markup, digits and punctuation stay outside the override, and nothing is accented or padded. |
| `locale` | `string` | no | The pseudolocale's BCP-47 code. Defaults to `en-XA` in `accented` mode and to `ar-XB` in `bidi` mode, a code that resolves to right-to-left text direction, so an application that derives its layout direction from the locale flips without further setup. In `bidi` mode an `i18next-json` plural keyed by suffix also gets every CLDR category the pseudolocale's language needs and the source lacks (for `ar-XB`, `_zero`, `_two`, `_few` and `_many`), filled from the source's `other` form, or its `one` or first non-blank form when `other` is missing or blank, so no count falls back to another language. It must not be the source locale or any configured target locale, compared case-insensitively, so a pseudolocale can never stand in for a real translation. |
| `out` | `string` | no | Directory the pseudolocale file is written under, relative to `cwd`. Defaults to `.verbatra-local/pseudo`, which `verbatra init` already adds to `.gitignore`. The configured `files.pattern` is expanded inside it, so the file keeps the layout the application expects. It must name a directory inside `cwd`: an absolute path, one that climbs out with `..`, and `cwd` itself are all refused, as is a directory under which the expanded pattern would place the pseudolocale file beside a configured locale file, so a generated pseudolocale never lands outside the project or beside the real translations where nothing ignores it. The same holds after symbolic links are resolved, so a linked directory cannot carry the file outside `cwd` or into the directory of a configured locale file. |

**返回**：`PseudolocalizeResult`

**抛出**：[`PSEUDO_OUTPUT_CONFLICT`](https://verbatra.kreitz-webdev.de/zh-CN/docs/error-codes.md#pseudo_output_conflict)、[`UNKNOWN_FORMAT`](https://verbatra.kreitz-webdev.de/zh-CN/docs/error-codes.md#unknown_format)、[`LOCALE_LAYOUT_INVALID`](https://verbatra.kreitz-webdev.de/zh-CN/docs/error-codes.md#locale_layout_invalid)、[`LOCALE_PATH_COLLISION`](https://verbatra.kreitz-webdev.de/zh-CN/docs/error-codes.md#locale_path_collision)、[`SOURCE_UNREADABLE`](https://verbatra.kreitz-webdev.de/zh-CN/docs/error-codes.md#source_unreadable)、[`SOURCE_INVALID`](https://verbatra.kreitz-webdev.de/zh-CN/docs/error-codes.md#source_invalid)、[`TARGET_UNWRITABLE`](https://verbatra.kreitz-webdev.de/zh-CN/docs/error-codes.md#target_unwritable)

**示例**：[构建伪语言环境](https://verbatra.kreitz-webdev.de/zh-CN/docs/programmatic-api.md#构建伪语言环境)

每个生成的值都要通过与提供商译文相同的完整性门禁。通不过的值会原样复制源值，并列在 `copied` 中，而不是以损坏的形式写入，因此该条目仍然存在，仍能正常渲染。

<AvailableFrom version="0.12.0" />

`mode` 从 `PSEUDO_MODES` 中选择转换方式：默认的 `accented`，或 `bidi`；后者用从右到左标记和覆盖符包住每个可翻译文本的词，占位符、ICU 语法、内联标记、数字和标点留在它之外，并且不加任何重音。在 `bidi` 模式下，`locale` 默认为 `ar-XB`，这个代码解析为从右到左的方向；它的阿拉伯语复数规则如何与你的源文本的复数形式对应，见 [`verbatra pseudo`](https://verbatra.kreitz-webdev.de/zh-CN/docs/cli/pseudo.md)。

`locale` 默认为 `en-XA`，`out` 默认为 `.verbatra-local/pseudo`，`verbatra init` 已把它加入 `.gitignore`；配置的 `files.pattern` 会在它里面展开，所以文件保持应用所期望的布局。名字与已配置语言环境相同的伪语言环境，或会落在已配置语言文件上的伪语言环境，会在读取或写入任何内容之前以 `PSEUDO_OUTPUT_CONFLICT` 被拒绝，因此它既不会覆盖真实译文，也不会冒充真实译文；以下的 `out` 同样会被拒绝：绝对路径、跳出 `cwd` 的路径，或指向 `cwd` 本身（例如 `.`）的路径；并且当 `deps.fs` 像默认实现一样实现了 `realpath` 时，解析符号链接之后出现以上任何情况、落在已配置语言文件所在目录，或落在项目依赖的其他文件上的 `out` 也会被拒绝。由于该文件位于 `files.pattern` 之外，`translate` 从不为它花费，`check` 和 `diff` 也从不把它报告为已漂移。

返回 `PseudolocalizeResult`：`locale`、`mode`、绝对路径 `path`、处理了多少 `entries`、转换了多少 `transformed`、被 `copied` 的键，以及是否有内容被 `written`。转换是确定性的，所以对未更改的源文件再运行一次不会重写任何内容，并把 `written` 报告为 false。对 `xliff` 和 `apple-xcstrings`，它们的写入器只修补已存在的文档，所以每次写入时输出都会从源文件重新复制，这样第一次运行之后添加到源文件的键仍会进入伪语言环境，复制出的 XLIFF 的 `target-language` 也会被改写为该伪语言环境。

## 带类型的消息目录 [#带类型的消息目录]

### generateTypes [#generatetypes]

<AvailableFrom version="0.11.0" />

把项目的源消息目录声明为 TypeScript：它包含的每个键的联合类型，以及每个键的消息所插值的参数。让翻译函数以结果为类型，拼错的键或缺失的插值参数就会成为编译错误，而不是运行时的查找失败。它不产生任何花费：不构造提供商，不读取 API 密钥环境变量，也不发出网络请求。

```ts title="签名"
function generateTypes(
  input: GenerateTypesInput,
  deps?: GenerateTypesDeps,
): Promise<GenerateTypesResult>;
```

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `config` | `VerbatraConfig` | yes | The resolved project config, normally from loadConfig. |
| `cwd` | `string` | no | Directory the `files.pattern` and the output path are resolved against. Defaults to the project root of the config object loadConfig returned, else the process working directory; a copied or rebuilt config loses that root, so pass `cwd` from resolveProjectRoot. |
| `out` | `string` | no | Where to write the declaration, relative to `cwd`. Defaults to DEFAULT_TYPES_PATH. Refused with `TYPES_OUTPUT_CONFLICT`, before anything is read or written, when it names no file, is absolute, climbs out of `cwd`, does not end in `.ts`, `.mts` or `.cts`, or names a configured locale file, the lock file, the provenance file, the translation-memory cache, a file verbatra searches for its configuration, the GenerateTypesInput.configPath file, or the GenerateTypesInput.glossaryPath file. When the file-system port implements `realpath`, the same checks run again after symbolic links are resolved. Names are compared case-insensitively. A generating run also refuses to replace an existing file there unless that file begins with the header line verbatra writes, after any leading byte order mark and blank lines, and refuses one too large to verify. |
| `configPath` | `string` | no | The configuration file `config` was loaded from, absolute or relative to `cwd`. It is refused as the output path even when its name is not one verbatra searches for. |
| `glossaryPath` | `string` | no | The glossary file the config names, absolute or relative to `cwd`, normally the `path` of a file-backed LoadedConfig.glossary. It is refused as the output path. |
| `check` | `boolean` | no | Compare instead of writing. The run reports whether the file on disk matches what a fresh generation would produce and leaves every file untouched. |

**返回**：`GenerateTypesResult`

**抛出**：[`TYPES_OUTPUT_CONFLICT`](https://verbatra.kreitz-webdev.de/zh-CN/docs/error-codes.md#types_output_conflict)、[`TYPES_UNWRITABLE`](https://verbatra.kreitz-webdev.de/zh-CN/docs/error-codes.md#types_unwritable)、[`UNKNOWN_FORMAT`](https://verbatra.kreitz-webdev.de/zh-CN/docs/error-codes.md#unknown_format)、[`LOCALE_LAYOUT_INVALID`](https://verbatra.kreitz-webdev.de/zh-CN/docs/error-codes.md#locale_layout_invalid)、[`LOCALE_PATH_COLLISION`](https://verbatra.kreitz-webdev.de/zh-CN/docs/error-codes.md#locale_path_collision)、[`SOURCE_UNREADABLE`](https://verbatra.kreitz-webdev.de/zh-CN/docs/error-codes.md#source_unreadable)、[`SOURCE_INVALID`](https://verbatra.kreitz-webdev.de/zh-CN/docs/error-codes.md#source_invalid)

**示例**：[生成带类型的消息目录](https://verbatra.kreitz-webdev.de/zh-CN/docs/programmatic-api.md#生成带类型的消息目录)

它读取一个文件（源语言环境的消息目录），写入一个文件（声明文件）；目标语言文件从不被触及。键与格式适配器已经产生的完全一致，按文档顺序排列，所以对未更改的目录运行两次，写出的字节完全相同。参数来自适配器提取出的占位符记号，ICU 消息格式（`next-intl-json` 和 `arb`）除外，在这两种格式中，每条消息都用适配器所用的同一个 ICU 解析器读取。每个键都作为带引号的字符串字面量输出，所以带点号、保留字、以数字开头、带引号，或根本为空的键，都会原样声明，而不是被丢弃或重新拆分，适配器在 `excludedLeafPaths` 中报告的键则根本不会声明。

它不做哪些断言，和它声明了什么同样重要。没有占位符的消息得到一个形状，传入任何参数都会是类型错误；占位符带有参数名的消息得到对象形状；占位符是编号或匿名的消息得到只读元组。只有部分 `select` 或 `plural` 分支用到的 ICU 参数，声明为可选成员。参数类型只来自目录所记录的内容：ICU 的 `number`、`plural` 或 `selectordinal` 参数，以及数值格式化器或转换，是 `number`；ICU 的 `date` 或 `time` 参数和 i18next 的 `datetime` 格式化器是 `Date | number`；ICU 的 `select` 参数和 printf 字符串转换是 `string`；其他情况是 `string | number` 别名，绝不使用宽松的 `any`。i18next 的未转义插值（`{{- name}}`）按其前缀之后的名字声明。适配器报告为无效的消息、看起来既有命名又有编号参数的消息，以及占位符索引超出范围的消息，会连同它们的参数一起声明，并在 `unresolved` 中报告，而不是悄悄声明为没有参数。复数同级的键从不合并：每个都单独声明，适配器标记为复数的键会列出。

`out` 默认为 `DEFAULT_TYPES_PATH`（`verbatra-types.d.ts`）。在读取或写入任何内容之前，`TYPES_OUTPUT_CONFLICT` 会拒绝以下的 `out`：没有指向任何文件（包括以路径分隔符结尾的）、是绝对路径、用 `..` 跳出 `cwd`、指向 `cwd` 本身（`.`），或不以 `.ts`、`.mts` 或 `.cts` 结尾；还有指向已配置的语言文件、锁文件、来源记录文件、翻译记忆库缓存、verbatra 查找其配置所用的文件、`configPath`（`config` 加载自的配置文件），或 `glossaryPath`（它指名的术语表文件）的 `out`；名字比较不区分大小写，并且当 `deps.fs` 像默认实现一样实现了 `realpath` 时，会在解析符号链接之后，对路径最终落点再次执行同样的检查。生成运行还会以同一个错误码，拒绝替换不以 verbatra 所写的标题行开头的现有文件，并保持该文件不变。完整列表见 [`verbatra types`](https://verbatra.kreitz-webdev.de/zh-CN/docs/cli/types.md) 页面。设置了 `check` 时，完全不写入任何内容，也不会因内容而拒绝任何东西，运行只报告已提交的文件是否仍然匹配，这正是 CI 门禁想要的形式。

返回 `GenerateTypesResult`：绝对路径 `path`、构建它所用的 `sourcePath`、声明了多少个 `keys`、其中有多少个带有 verbatra 能确定的至少一个参数（`withArguments`，从不计入 `unresolved` 的键）、`unresolved` 的键，以及 `excluded` 和 `plural` 的键、是否有内容被 `written`、运行开始时磁盘上的文件是否 `stale`、它是否完全 `missing`（缺失的文件同样是 `stale`），以及这是否是一次 `check` 运行。
