---
title: "翻訳の実行"
description: "translate、watch、実行まわりのエントリポイントに加え、疑似ロケールと型付きカタログも、自分の Node.js スクリプトから呼び出せます。"
type: "reference"
---
# 翻訳の実行

translate、watch、実行まわりのエントリポイントに加え、疑似ロケールと型付きカタログも、自分の Node.js スクリプトから呼び出せます。

## 翻訳と監視 [#run-translations]

### translate [#translate]

1 回で完結するフローです。ソースを読み込み、各ターゲットロケールをロックファイルのベースラインと比較し、欠落しているキーと変更されたキーをプロバイダーに送り、整合性チェックを実行し、ロケールファイルを書き込み、ロックファイルを更新します。スクリプト、ビルドの手順、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/ja/docs/sdk/run-summary.md)

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

**例**：[翻訳してサマリーを読む](https://verbatra.kreitz-webdev.de/ja/docs/sdk-quickstart.md#翻訳してサマリーを読む)

表に載っていない内容は次のとおりです。

- `cache` は、ローカルの[翻訳キャッシュ](https://verbatra.kreitz-webdev.de/ja/docs/the-cache.md)（`verbatra.cache.json`。`CACHE_FILE_NAME` としてもエクスポートされます）です。
- `humanEdits`（バージョン 0.12.0 以上）：デフォルトでは、人が書いた、インポートした、または verbatra の外で変更した古くなったキーは、そのまま保たれ、`LocaleSummary.protected` に一覧されます。詳しくは[人手翻訳を保護する](https://verbatra.kreitz-webdev.de/ja/docs/protecting-human-translations.md)を参照してください。
- `onProgress` は、後述の[進捗イベント](#進捗イベント)を受け取ります。
- `maxBatchSize` と `budgetBehavior` は設定ファイル専用で、実行ごとの上書きはありません。

実行全体の問題は `SdkError` をスローします。1 つのロケールの失敗はスローされず、そのロケールのエントリに `status: "failed"` として記録され、実行は続きます。詳しくは [RunSummary の構造](https://verbatra.kreitz-webdev.de/ja/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` | 出力が途中で切れたバッチを、2 つに分けて再試行する | `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` はロケールを示しません。1 つのプロバイダーが実行全体を担当するためです。Gemini は待ち時間とステータスを報告します。Anthropic、OpenAI、OpenCode、openai-compatible は、クライアントが再試行を始めるときに試行回数を報告します。DeepL、Google Cloud Translation、LibreTranslate は何も報告しません。ドライランと見積もりが出力するのは、`locale-started`、`locale-finished`、`run-finished` だけです。CLI の `--json` の進捗レコードは、元の 4 つの型である `locale-started`、`sub-batch`、`locale-finished`、`run-finished` に限られます。

`extract`、`unused` 付きの `diff`、`literals` 付きの `doctor` は、それぞれ独自の `onProgress` を受け取ります。この `onProgress` は `ScanProgressEvent`（`{ type: "files-scanned", scanned, total }`）を受け取り、スキャンがアプリケーションのソースファイルを 1 つ読むたびに 1 回呼ばれます。

| 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` は、実行が進捗を報告するときに、第 3 引数の `CreateProviderHooks` を受け取ります。その `onRetry` を `{ attempt, delayMs?, status? }` で呼ぶと、プロバイダーの再試行が `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` を再実行します。起動時にすぐ最初の実行を 1 回行い、その後は変更が落ち着くたびに 1 回実行します。実行は直列化され、実行中の変更は 1 回の後続の実行にまとめられます。

```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/ja/docs/error-codes.md#unknown_locale)、[`LOCALE_UNSUPPORTED_BY_PROVIDER`](https://verbatra.kreitz-webdev.de/ja/docs/error-codes.md#locale_unsupported_by_provider)、[`CONCURRENCY_INVALID`](https://verbatra.kreitz-webdev.de/ja/docs/error-codes.md#concurrency_invalid)、[`LOCK_TIMEOUT_INVALID`](https://verbatra.kreitz-webdev.de/ja/docs/error-codes.md#lock_timeout_invalid)、[`CONCURRENCY_BUDGET_CONFLICT`](https://verbatra.kreitz-webdev.de/ja/docs/error-codes.md#concurrency_budget_conflict)、[`LOCALE_LAYOUT_INVALID`](https://verbatra.kreitz-webdev.de/ja/docs/error-codes.md#locale_layout_invalid)、[`LOCALE_PATH_COLLISION`](https://verbatra.kreitz-webdev.de/ja/docs/error-codes.md#locale_path_collision)、[`SOURCE_UNREADABLE`](https://verbatra.kreitz-webdev.de/ja/docs/error-codes.md#source_unreadable)、[`NETWORK_POLICY_VIOLATION`](https://verbatra.kreitz-webdev.de/ja/docs/error-codes.md#network_policy_violation)、[`PROVIDER_CONSTRUCTION_FAILED`](https://verbatra.kreitz-webdev.de/ja/docs/error-codes.md#provider_construction_failed)、[`CONFIG_INVALID`](https://verbatra.kreitz-webdev.de/ja/docs/error-codes.md#config_invalid)

**例**：[長時間動くプロセスで監視する](https://verbatra.kreitz-webdev.de/ja/docs/programmatic-api.md#長時間動くプロセスで監視する)

`debounceMs` のデフォルトは 300 です。`onRun` は、実行ごとに 1 回、`WatchRunResult` とともに呼ばれます。値は `{ status: "succeeded", summary }` または `{ status: "failed", error: { code, message, causeCode?, hint? } }` で、`causeCode` は失敗が包んでいるコード付きエラーを示し、`hint` は `errorHint` が返す次の手順です。`onReady` は、起動時のチェックを通過したあと、最初の実行の直前に 1 回呼ばれます。これにより、その実行の出力より先にセッションを通知できます。`onReady` がスローした場合、監視プロセスは閉じられ、どの実行も始まる前に、`watch` が返す Promise がそのエラーで reject されます。SDK はログを出力せず、出力は `onRun` だけです。`concurrency`、`cache`、`onProgress`、`onLockWait`、`lockAcquireTimeoutMs` はすべての実行にそのまま渡され、`translate` と同じように動作します。`locales` はセッションのすべての実行をそのサブセットに絞り、サイクルごとではなく、起動時に 1 回検証されます。

`stop()` という 1 つのメソッドを持つ `WatchController` を返します。`stop()` は監視プロセスを閉じ、進行中の実行が終わるまで待ちます。**例外**の行にあるすべてのコードは、監視プロセスが作られる前の起動時に拒否されます。そのため `watch` が返す Promise 自体が reject され、コントローラーは返りません。そのうち 2 つは、1 回の実行よりもセッションにとって重くなります。1 つは、`maxTokens` を設定した設定ファイルに対して 1 より大きい `concurrency` を指定した場合で、ドライランの監視はないため、常に `CONCURRENCY_BUDGET_CONFLICT` をスローします。もう 1 つは、0.12.0 以上では、API キーの変数が未設定などのためにプロバイダーを生成できない場合で、すべての実行が失敗するのではなく、`PROVIDER_CONSTRUCTION_FAILED` を 1 回だけスローします。起動後の失敗はすべて `onRun` を通じて通知され、監視は続きます。

### releaseHeldLocks [#releaseheldlocks]

<AvailableFrom version="0.12.0" />

現在のプロセスが保持しているすべての書き込みロックを削除します。実行中の処理が終わるのを待たずに終了しようとするプロセス向けです。CLI は、割り込みで `translate` や `import` が止まるとき、および 2 回目の割り込みで `watch` を強制停止するときに、これを呼びます。その書き込みロックを取っていた実行は保護を失うため、プロセスが終了する直前にだけ呼んでください。引数はなく、保持されている書き込みロックを削除できなかった場合に限り、すべての書き込みロックを試したあとで、そのパスだけを示す `AggregateError` で reject されます。まだ実行中の処理が、実行中に書き込みロックを取っている、または取ろうとしている場合、その書き込みロックは `RUN_CANCELLED` で拒否され、ファイルは残りません。そのような取得を待つ時間は、最大 3 秒です。

```ts title="シグネチャ"
function releaseHeldLocks(): Promise<void>;
```

**戻り値**：`void`

プロセスが強制終了されるなどして残ってしまった書き込みロックには、この関数は不要です。同じマシンで待機している実行が、記録されたプロセスがすでにないことを検知し、自分でその書き込みロックを回収します。詳しくは[書き込みロック](https://verbatra.kreitz-webdev.de/ja/docs/the-lock-file.md#書き込みロック)を参照してください。

## 疑似ローカライズ [#疑似ローカライズ]

### pseudolocalize [#pseudolocalize]

<AvailableFrom version="0.11.0" />

ソース文字列だけから偽のロケールを作ります。これにより、API キーが存在する前でも、レイアウトで文字が切れる箇所や、翻訳用に抽出されていなかった文字列が見つかります。すべての値にアクセント記号を付け、翻訳可能な長さのおよそ 3 分の 1 だけ長くし、`[` と `]` の境界マーカーで囲みます。プレースホルダーは、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/ja/docs/error-codes.md#pseudo_output_conflict)、[`UNKNOWN_FORMAT`](https://verbatra.kreitz-webdev.de/ja/docs/error-codes.md#unknown_format)、[`LOCALE_LAYOUT_INVALID`](https://verbatra.kreitz-webdev.de/ja/docs/error-codes.md#locale_layout_invalid)、[`LOCALE_PATH_COLLISION`](https://verbatra.kreitz-webdev.de/ja/docs/error-codes.md#locale_path_collision)、[`SOURCE_UNREADABLE`](https://verbatra.kreitz-webdev.de/ja/docs/error-codes.md#source_unreadable)、[`SOURCE_INVALID`](https://verbatra.kreitz-webdev.de/ja/docs/error-codes.md#source_invalid)、[`TARGET_UNWRITABLE`](https://verbatra.kreitz-webdev.de/ja/docs/error-codes.md#target_unwritable)

**例**：[疑似ロケールを作る](https://verbatra.kreitz-webdev.de/ja/docs/programmatic-api.md#疑似ロケールを作る)

生成されたすべての値は、プロバイダーの訳文が通る必要があるのと同じ整合性ゲートを通ります。通らない値は、壊れた形で書き込まれる代わりに、ソースからそのままコピーされ、`copied` に名前が載ります。そのため、エントリは存在し続け、表示もされます。

<AvailableFrom version="0.12.0" />

`mode` は、`PSEUDO_MODES` から変換方法を選びます。デフォルトは `accented` で、もう一方は `bidi` です。`bidi` は、翻訳可能なテキストのすべての単語を右から左へのマークとオーバーライドで囲みます。プレースホルダー、ICU 構文、マークアップ、数字、句読点はその外に残し、アクセント記号は何も付けません。`bidi` モードでは、`locale` のデフォルトは `ar-XB` で、右から左の方向に解決されるコードです。アラビア語の複数形ルールがソースの複数形とどう合うかは、[`verbatra pseudo`](https://verbatra.kreitz-webdev.de/ja/docs/cli/pseudo.md) を参照してください。

`locale` のデフォルトは `en-XA`、`out` のデフォルトは `.verbatra-local/pseudo` で、`verbatra init` がすでに `.gitignore` に追加しています。設定した `files.pattern` がこの中に展開されるため、ファイルはアプリケーションが期待するレイアウトを保ちます。設定済みのロケールと同じ名前の疑似ロケール、または設定済みのロケールファイルに書き込まれる疑似ロケールは、何かを読み書きする前に `PSEUDO_OUTPUT_CONFLICT` で拒否されます。そのため、本物の訳文を上書きすることも、その代わりになることもありません。次の `out` も同様に拒否されます。絶対パスの `out`、`cwd` の外に出る `out`、`.` のように `cwd` 自体を指す `out` です。また、`deps.fs` がデフォルトと同じく `realpath` を実装している場合は、シンボリックリンクを解決したあとで、これらのいずれかに当てはまる `out`、設定済みのロケールファイルのディレクトリに着地する `out`、プロジェクトが依存するほかのファイルに着地する `out` も拒否されます。ファイルは `files.pattern` の外に置かれるため、`translate` がそのファイルに費用をかけることはなく、`check` と `diff` がそれをドリフトとして報告することもありません。

`PseudolocalizeResult` を返します。内容は、`locale`、`mode`、絶対パスの `path`、処理された `entries` の数、変換された `transformed` の数、コピーされたキーである `copied`、何かが `written` されたかどうかです。変換は決定的なので、ソースが変わらない 2 回目の実行は何も書き直さず、`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/ja/docs/error-codes.md#types_output_conflict)、[`TYPES_UNWRITABLE`](https://verbatra.kreitz-webdev.de/ja/docs/error-codes.md#types_unwritable)、[`UNKNOWN_FORMAT`](https://verbatra.kreitz-webdev.de/ja/docs/error-codes.md#unknown_format)、[`LOCALE_LAYOUT_INVALID`](https://verbatra.kreitz-webdev.de/ja/docs/error-codes.md#locale_layout_invalid)、[`LOCALE_PATH_COLLISION`](https://verbatra.kreitz-webdev.de/ja/docs/error-codes.md#locale_path_collision)、[`SOURCE_UNREADABLE`](https://verbatra.kreitz-webdev.de/ja/docs/error-codes.md#source_unreadable)、[`SOURCE_INVALID`](https://verbatra.kreitz-webdev.de/ja/docs/error-codes.md#source_invalid)

**例**：[型付きカタログを生成する](https://verbatra.kreitz-webdev.de/ja/docs/programmatic-api.md#型付きカタログを生成する)

読み込むファイルは 1 つ（ソースロケールのカタログ）、書き込むファイルも 1 つ（宣言ファイル）で、ターゲットロケールのファイルには触れません。キーは、フォーマットアダプターがすでに生成したものそのままで、ドキュメント内の順序です。そのため、変更のないカタログに対する 2 回の実行は、バイト単位で同一の内容を書き込みます。引数は、アダプターが抽出したプレースホルダーから取得します。ただし 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` を拒否します。ファイルを指さない `out`（パスの区切り文字で終わるものを含みます）、絶対パス、`..` で `cwd` の外に出るもの、`cwd` 自体（`.`）を指すもの、`.ts`、`.mts`、`.cts` で終わらないものです。さらに、設定済みのロケールファイル、ロックファイル、来歴ファイル、翻訳メモリのキャッシュ、verbatra が設定を探すファイル、`config` の読み込み元の設定ファイルである `configPath`、指定された用語集ファイルである `glossaryPath` を指す `out` も拒否します。名前は大文字と小文字を区別せずに比較され、`deps.fs` がデフォルトと同じく `realpath` を実装している場合は、シンボリックリンクを解決したあとのパスの着地点に対して同じチェックがもう一度行われます。生成する実行は、verbatra が書くヘッダー行で始まらない既存のファイルを置き換えることも、同じコードで拒否し、そのファイルには触れません。完全な一覧は [`verbatra types`](https://verbatra.kreitz-webdev.de/ja/docs/cli/types.md) のページにあります。`check` を設定すると、何も書き込まれず、内容を理由に拒否されることもなく、コミット済みのファイルがまだ一致しているかどうかだけを報告します。これは CI のゲートが求める形です。

`GenerateTypesResult` を返します。内容は、絶対パスの `path`、元になった `sourcePath`、宣言された `keys` の数、そのうち verbatra が判定できた引数を 1 つ以上取るものの数（`withArguments`。`unresolved` のキーは数えません）、`unresolved` のキー、`excluded` のキーと `plural` のキー、何かが `written` されたかどうか、実行の開始時にディスク上のファイルが `stale` だったかどうか、ファイルが完全に `missing` だったかどうか（ファイルがない場合は `stale` でもあります）、そしてこれが `check` の実行だったかどうかです。
