---
title: "受け渡しと交換"
description: "ブックと TMX のインポートとエクスポート、ロケールファイルのスナップショット、ロケールごとに verbatra が解決するパスを扱う SDK のエントリポイントです。"
type: "reference"
---
# 受け渡しと交換

ブックと TMX のインポートとエクスポート、ロケールファイルのスナップショット、ロケールごとに verbatra が解決するパスを扱う SDK のエントリポイントです。

<SdkAnchorForward />

## ロケールファイルのスナップショット [#ロケールファイルのスナップショット]

Studio のようなライブ更新の監視プロセスを作るための部品です。ロケールファイルの状態を取得し、その後の変更を数えます。

### readLocaleFileSnapshot [#readlocalefilesnapshot]

<AvailableFrom version="0.5.0" />

1 つのロケールファイル（ソースロケールまたは任意のターゲットロケール）を読み込み、キーごとのコンテンツハッシュに縮約します。まだ存在しないファイルは、スローせずに空のスナップショットとして読み込まれます。

```ts title="シグネチャ"
function readLocaleFileSnapshot(
  input: ReadLocaleFileSnapshotInput,
  deps?: ReadLocaleFileSnapshotDeps,
): Promise<LocaleFileSnapshot>;
```

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `config` | `VerbatraConfig` | yes | The resolved project config, normally from loadConfig. |
| `locale` | `string` | yes | The locale file to snapshot. Unlike most entry points this is not checked against the configured target locales, so the source locale can be snapshotted too. |
| `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. |

**戻り値**：`LocaleFileSnapshot`

**例外**：[`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)

`{ locale, hashes }` を返します。

### diffLocaleSnapshots [#difflocalesnapshots]

<AvailableFrom version="0.5.0" />

異なる時点で取得した同じファイルの 2 つのスナップショットを比較し、その間に追加、変更、削除されたキーの数を数えます。単純な同期関数で、`diffLocaleSnapshots(previous, current)` は `{ added, changed, removed }` を返します。返すのは件数だけで、キー名は返しません。

```ts title="シグネチャ"
function diffLocaleSnapshots(
  previous: LocaleFileSnapshot,
  current: LocaleFileSnapshot,
): LocaleSnapshotDelta;
```

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `locale` | `string` | yes | The locale this snapshot was taken for. |
| `hashes` | `ReadonlyMap<string, string>` | yes | Content hash per key, in the order the adapter read them. |

**戻り値**：`LocaleSnapshotDelta`

## ロケールのパス [#ロケールのパス]

### createLocalePathResolver [#createlocalepathresolver]

<AvailableFrom version="0.7.0" />

`files.pattern`、設定されたロケール、`files.localeStyle` から、プロジェクトのロケールとパスの対応を双方向に解決します。`createLocalePathResolver(cwd, config)` は `{ pathFor, localeFor }` を返します。`pathFor(locale)` は 1 つのロケールのファイルの絶対パスです。`localeFor(path)` は、そのパスを持つロケールを返します。このプロジェクトに属さないパスでは `undefined` を返し、`apple-xcstrings` のように 1 つのカタログを共有するフォーマットでは常に `undefined` を返します。すべての SDK エントリポイントがこれを通してパスを解決します。そのため、SDK 上に作った監視プロセスやダッシュボードには、実行が書き込むパスとまったく同じパスが見えます。

```ts title="シグネチャ"
function createLocalePathResolver(
  cwd: string,
  config: LocalePathResolverConfig,
): LocalePathResolver;
```

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `sourceLocale` | `string` | yes | The source locale, which some styles spell differently from the targets. |
| `targetLocales` | `readonly string[]` | yes | Every target locale. All of them are mapped up front so collisions are caught immediately. |
| `format` | `FormatId` | yes | The configured format. Every format maps each locale to a distinct path except a shared-catalogue format (one holding every locale in a single file, such as `apple-xcstrings`), which maps every locale to the same path. A `custom:` format is always treated as one file per locale. Under the `posix` locale style, the `gettext-po` format also spells a script the gettext way (`sr-Latn` as `sr@latin`) rather than the ICU way (`sr_Latn`). |
| `files` | `object` | yes | The file layout. |

**戻り値**：`LocalePathResolver`

**例外**：[`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)

すべてのチェックは、ファイルを読み込む前の、リゾルバーの作成時に行われます。組み合わせられないパターンとスタイル、またはスタイルに正しい表記がないロケールは `LOCALE_LAYOUT_INVALID` をスローします。2 つのロケールが 1 つのパスに解決される場合は `LOCALE_PATH_COLLISION` をスローします。

### localeWatchPaths [#localewatchpaths]

<AvailableFrom version="0.13.0" />

監視プロセスが必要とするファイルを返します。設定された各ロケールのファイルと、データの一部を持つ隣のファイル（`apple-strings` の `.stringsdict` ファイル）、そしてコミット、ブランチの切り替え、リセット、ステージング操作で git が書き換えるファイルです。読み取り専用です。git の部分は、差し替え可能な `execFile` を通して問い合わせ、[`localeGitStatus`](https://verbatra.kreitz-webdev.de/ja/docs/sdk/review.md#localegitstatus) と同じ安全策が適用されます。

```ts title="シグネチャ"
function localeWatchPaths(
  input: LocaleWatchPathsInput,
  deps?: LocaleWatchPathsDeps,
): Promise<LocaleWatchPathsResult>;
```

| 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 git runs in. Defaults to the project root of the config object loadConfig returned, else the process working directory; pass `cwd` from resolveProjectRoot for a copied config. |

**戻り値**：`LocaleWatchPathsResult`

**例外**：[`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)

`locales` には、ソースロケールが先頭に来て、それぞれの `paths` が一覧されます。`git` は、このワークツリーの index、`HEAD`、`HEAD` の reflog の絶対パスを持つ `{ available: true, paths }` です。読み取れるワークツリーの外では `{ available: false, reason }` になります。どちらの場合も、ロケールファイルは一覧されます。

## ブック用の関数ペア [#ブック用の関数ペア]

翻訳者への受け渡しを、Excel ブックまたは区切り文字テキストで行います。[Excel や CSV で受け渡す](https://verbatra.kreitz-webdev.de/ja/docs/manual-translation.md)を参照してください。

### exportWorkbook [#exportworkbook]

<AvailableFrom version="0.2.0" />

まだ翻訳が必要な文字列（ロケールごとの欠落しているキーと変更されたキー。最新のものを加えるには `includeUnchanged` を使います）を、スタイル付きの `.xlsx` ブックに書き込みます。各行には、翻訳の実行が計算するのと同じレビューフラグのシグナルが付きます。プロバイダーは呼び出さず、ロックファイルにも書き込みません。

```ts title="シグネチャ"
function exportWorkbook(
  input: ExportWorkbookInput,
  deps?: ExportWorkbookDeps,
): Promise<ExportWorkbookResult>;
```

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `config` | `VerbatraConfig` | yes | The resolved project config, normally from loadConfig. |
| `cwd` | `string` | no | Directory the `files.pattern` and `out` 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 handoff. Defaults to DEFAULT_WORKBOOK_PATH for `xlsx` and to DEFAULT_DELIMITED_PATH for the delimited and XLIFF formats. Refused with `EXPORT_OUTPUT_CONFLICT`, before anything is read or written, when it resolves outside `cwd`, or when it or a file the export would write names a configured locale file, the lock file, the provenance file, the translation-memory cache, a file verbatra searches for its configuration, the ExportWorkbookInput.configPath file, or the ExportWorkbookInput.glossaryPath file. For `xlsx` it is also refused when it names no file (including one ending in a path separator) or names `cwd` itself; a delimited or XLIFF export may write into `cwd`. Names are compared case-insensitively, and, when the file-system port implements `realpath`, again after symbolic links are resolved, so a link cannot carry the handoff anywhere a plain path could not. |
| `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. |
| `locales` | `readonly string[]` | no | Restrict the export to these target locales. Defaults to every configured target locale. |
| `includeUnchanged` | `boolean` | no | Include keys that are already up to date, not just the missing and stale ones. Useful when a translator needs the surrounding context to translate consistently. Defaults to false. |
| `format` | `ExchangeFormat` | no | The handoff shape to write. Defaults to `xlsx`. |

**戻り値**：`ExportWorkbookResult`

**例外**：[`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)、[`LOCK_FILE_INVALID`](https://verbatra.kreitz-webdev.de/ja/docs/error-codes.md#lock_file_invalid)、[`UNKNOWN_LOCALE`](https://verbatra.kreitz-webdev.de/ja/docs/error-codes.md#unknown_locale)、[`EXPORT_OUTPUT_CONFLICT`](https://verbatra.kreitz-webdev.de/ja/docs/error-codes.md#export_output_conflict)、[`EXPORT_UNWRITABLE`](https://verbatra.kreitz-webdev.de/ja/docs/error-codes.md#export_unwritable)

**例**：[ブックの往復](https://verbatra.kreitz-webdev.de/ja/docs/programmatic-api.md#ブックの往復)

`format` のデフォルトは `xlsx` です。`csv` と `tsv` では、代わりにロケールごとに `<locale>.csv` または `<locale>.tsv` を 1 つ書き込みます。そのため `out` は、これらではディレクトリ（存在しない場合は作成されます）を、`xlsx` ではファイルパスを指定します。`out` のデフォルトは `DEFAULT_WORKBOOK_PATH`（`verbatra-translations.xlsx`）です。区切り文字ファイルと XLIFF のフォーマットでは `DEFAULT_DELIMITED_PATH`（`verbatra-translations`）で、どちらも定数としてエクスポートされています。指定できる値は `EXCHANGE_FORMATS` として、デフォルトは `DEFAULT_EXCHANGE_FORMAT` としてエクスポートされています。そのため、SDK をラップするツールは、一覧をハードコードせずにフォーマットの引数を検証できます。`{ path, locales }` を返します。書き込んだ絶対パスと、ロケールごとの行数です。

何かを読み込む前に、`EXPORT_OUTPUT_CONFLICT` が、次のような `out` を拒否します。`cwd` の外に解決されるもの、または、それ自体や、エクスポートがその中に書き込むファイルが、設定済みのロケールファイル、ロックファイル、来歴ファイル、翻訳メモリのキャッシュ、verbatra が設定を探すファイル、`configPath` のファイル、`glossaryPath` のファイルを指すものです。比較は大文字と小文字を区別せずに行われます。`deps.fs` がデフォルトと同様に `realpath` を実装している場合は、シンボリックリンクを解決した後にもう一度行われます。`xlsx` のパスは、ファイルを指していない場合（パス区切り文字で終わるものを含む）や、`cwd` そのものを指している場合にも拒否されます。`csv`、`tsv`、XLIFF のディレクトリは `cwd` でも構いません。書き込みが失敗した場合は、`EXPORT_UNWRITABLE` をスローします。ディレクトリに書き込めない、ディレクトリやファイルがすでにそのパスにある、ディスクが満杯などが原因です。スローされるエラーは、ファイルとファイルシステムのコードを示し、ファイルシステムのエラーを `cause` に持ちます。

<AvailableFrom version="0.12.0" />

`format: "xliff2"` と `format: "xliff12"` は、CAT ツール（翻訳支援ツール）向けに、ロケールごとに XLIFF 2.0 または 1.2 の `<locale>.xlf` を `out` ディレクトリへ書き込みます。キー 1 つにつき翻訳単位が 1 つで、プレースホルダーとマークアップは保護された `<ph>` インラインコードになり、キーの説明と意味は注記になり、ソースハッシュは翻訳単位のメタデータに入ります。セグメントの状態はロックファイルとレビューの状態から決まります（欠落または古くなったキーは `initial`、最新の場合は `translated`、承認済みの場合は `reviewed`）。どちらの型もエクスポートされています。`XliffFormat` は、`ExchangeFormat` のうち 2 つの XLIFF のメンバーを指します。[翻訳会社に受け渡す（XLIFF）](https://verbatra.kreitz-webdev.de/ja/docs/translation-agency.md)を参照してください。

ターゲットを持つ各翻訳単位には、出どころも記録されます。XLIFF 1.2 では、未承認の機械クラスのターゲットに `state-qualifier="mt-suggestion"` が付きます。XLIFF 2.0 では、翻訳単位の `verbatra` メタデータグループに `origin` と `review-state` のエントリが追加されます。このとき結果には `provenanceMarkers` も含まれます。値は `"written"` で、来歴ファイルを読み込めずマーカーを書き込まなかった場合は `"unavailable"` です。[機械翻訳の証跡を記録する](https://verbatra.kreitz-webdev.de/ja/docs/provenance-evidence.md#エクスポート内のマーカー)を参照してください。

### importWorkbook [#importworkbook]

<AvailableFrom version="0.2.0" />

記入済みのブックをロケールファイルに読み戻します。`translate` と同じように、ソースのドリフトと整合性をチェックします。ロックファイルのベースラインが進むのは、受け入れられた行だけです。空白の行や拒否された行は、本当に解決されるまでエクスポートされ続けます。CSV、TSV、xlsx の受け渡しでは、最新のキーがすでに持つ値と同じで、整合性ゲートも通る記入済みの行は、そのまま残され、`unchanged` として報告されます。翻訳されません<AvailableFrom version="0.13.0" />。詳しくは[インポートが受け付けるもの](https://verbatra.kreitz-webdev.de/ja/docs/manual-translation.md#インポートが受け付けるもの)を参照してください。

```ts title="シグネチャ"
function importWorkbook(
  input: ImportWorkbookInput,
  deps?: ImportWorkbookDeps,
): Promise<RunSummary>;
```

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `config` | `VerbatraConfig` | yes | The resolved project config, normally from loadConfig. |
| `workbook` | `string` | yes | Path to the filled handoff. For a delimited or XLIFF import the path is tried as a single file first, so one individual `<locale>.<csv\|tsv\|xlf>` file can be imported on its own, with the locale taken from its file name. A single XLIFF file whose name is not a configured target locale is matched by the target language it declares instead. If no file exists there, the path is treated as the directory the per-locale files were written into and every configured target locale found inside is read. |
| `cwd` | `string` | no | Directory the `files.pattern` and `workbook` 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. |
| `dryRun` | `boolean` | no | Read and validate the handoff but write nothing. The returned RunSummary reports what would have been applied, which is the safe way to inspect a handoff before trusting it. Defaults to false. |
| `format` | `ExchangeFormat` | no | The handoff shape to read. Defaults to the shape the extension of ImportWorkbookInput.workbook names: `csv` for `.csv`, `tsv` for `.tsv`, `xliff2` for `.xlf` or `.xliff`, and `xlsx` for `.xlsx` or any other file. For a directory it is the format of the export manifest inside, else of the `<locale>` files inside; a directory holding two formats, or none, is refused. `xliff2` and `xliff12` both read either XLIFF version, which is taken from the file. |
| `reviewer` | `string` | no | Free text naming the reviewer, 1 to 64 characters with no control characters, recorded on each value an XLIFF handoff marks `reviewed` or `final` (1.2: `signed-off`, `final`, or `approved="yes"`). It is stored in the committed provenance file, so it is public. Other handoff formats carry no review state, so it is not used for them. |
| `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. |
| `lockAcquireTimeoutMs` | `number` | no | How long, in milliseconds, to wait for a locale's write lock before that locale fails with `LOCK_CONTENDED`. The wait happens before the locale file is written. 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. |

**戻り値**：[`RunSummary`](https://verbatra.kreitz-webdev.de/ja/docs/sdk/run-summary.md)

**例外**：[`LOCK_TIMEOUT_INVALID`](https://verbatra.kreitz-webdev.de/ja/docs/error-codes.md#lock_timeout_invalid)、[`REVIEWER_INVALID`](https://verbatra.kreitz-webdev.de/ja/docs/error-codes.md#reviewer_invalid)、[`UNKNOWN_FORMAT`](https://verbatra.kreitz-webdev.de/ja/docs/error-codes.md#unknown_format)、[`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)、[`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)、[`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/programmatic-api.md#ブックの往復)

`csv` または `tsv` では、`workbook` は 1 つの交換ファイル、またはロケールごとに 1 つのファイルを収めたディレクトリのどちらかです。ロケールはファイル名から決まります。`format` を省略した場合、`.csv` または `.tsv` で終わるファイルはそのフォーマットで読み込まれ、ディレクトリはエクスポートのマニフェストまたはロケールファイルのフォーマットで読み込まれます。`translate` と同じ `RunSummary` の形を返します（プロバイダーが関与しないため、`needsReview` は常に空です）。設定されたターゲットではないロケールのシートは、スローされずに、サマリー上のデータとして、そのロケールが `CONFIG_INVALID` で失敗します。

<AvailableFrom version="0.12.0" />

`onLockWait` と `lockAcquireTimeoutMs` の動作は `translate` とまったく同じです。`lockAcquireTimeoutMs` が制限するのは、ロケールのファイルを書き込む前に取得する、そのロケールの書き込みロックの待機時間です。その後も書き込みロックが競合したままのロケールは、そのロケール自身のサマリーで `LOCK_CONTENDED` により失敗し、ほかのロケールはインポートを続けます。書き込んだファイルをロックファイルに記録する処理は、常に 10 分のデフォルトを許容します。ドライランは書き込みロックを取得しないため、どちらのオプションも適用されません。

<AvailableFrom version="0.12.0" />

各ロケールの `integrityRefusals` には、整合性ゲートが拒否した行が、理由とその `details` とともに示されます。ターゲット言語に合わない ICU の分岐などです。エクスポート以降にソースが変わったために保留された行は、`integrityMismatches` にだけ一覧されます。`exportWorkbook` は、分岐が誤っている最新の訳文を、レビュー列に `icu-arms` としてフラグ付けします。

<AvailableFrom version="0.12.0" />

`xliff2` または `xliff12`（どちらも両方のバージョンを読み込めます）を指定した場合、および `.xlf` または `.xliff` で終わる `workbook` パスではデフォルトで、同じチェックの前に、すべてのインラインコードが元のテキストに戻されます。現在の値と同じターゲットは何も変更しません。ID がどのソースキーも指さない翻訳単位は `malformedRows` に報告されます。状態が `reviewed` または `final` の翻訳単位（1.2 では `signed-off`、`final`、`approved="yes"`）は、来歴ファイルに承認として記録されます。`reviewer` が指定された場合はその名前も記録され（`approveEntry` と同様に検査され、`REVIEWER_INVALID`）、通知 `HANDOFF_REVIEWS_RECORDED` で報告されます。

## TMX 用の関数ペア [#tmx-用の関数ペア]

<AvailableFrom version="0.11.0" />

`importTmx` と `exportTmx` は、[翻訳メモリ](https://verbatra.kreitz-webdev.de/ja/docs/the-cache.md)を TMX に取り込み、TMX から書き出します。TMX は、主要な翻訳プラットフォームが出力し、読み込む交換フォーマットです。どちらもプロバイダーを生成せず、API キーを読み込まず、ネットワーク通信もしません。すべての値は、ファイルか、すでにディスクにある翻訳メモリから取得されます。これは、ブック用の関数ペアを別のフォーマットにしたものではありません。ブック用のペアは、未処理の差分のうちロケールごとの一部を人の翻訳者に渡します。このペアは、翻訳メモリ全体を、1 つの多言語ファイルとしてツール間で移します。

### importTmx [#importtmx]

TMX ファイルをプロジェクトの翻訳メモリに読み込みます。

```ts title="シグネチャ"
function importTmx(
  input: ImportTmxInput,
  deps?: ImportTmxDeps,
): Promise<ImportTmxResult>;
```

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `config` | `VerbatraConfig` | yes | The resolved project config, normally from loadConfig. |
| `file` | `string` | yes | Path to the TMX file, resolved against `cwd`. |
| `cwd` | `string` | no | Directory the file and the memory 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. |
| `dryRun` | `boolean` | no | Read and validate the file but write nothing. Defaults to false. |
| `overwrite` | `boolean` | no | Let an imported unit replace a translation the memory already holds for the same source and locale. Off by default, so the project's own memory wins a collision. |
| `locales` | `readonly string[]` | no | Subset of configured target locales to import. Defaults to all of them. |

**戻り値**：`ImportTmxResult`

**例外**：[`UNKNOWN_FORMAT`](https://verbatra.kreitz-webdev.de/ja/docs/error-codes.md#unknown_format)、[`CONFIG_INVALID`](https://verbatra.kreitz-webdev.de/ja/docs/error-codes.md#config_invalid)、[`UNKNOWN_LOCALE`](https://verbatra.kreitz-webdev.de/ja/docs/error-codes.md#unknown_locale)、[`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)、[`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)、[`MEMORY_UNWRITABLE`](https://verbatra.kreitz-webdev.de/ja/docs/error-codes.md#memory_unwritable)

**例**：[TMX の往復](https://verbatra.kreitz-webdev.de/ja/docs/programmatic-api.md#tmx-の往復)

ファイルの内容は何も信頼されません。XML は、交換パッケージの防御策のもとで解析されます。そのため、エンティティ宣言、内部 DTD サブセット、大きすぎるファイル、壊れたファイルは、解析されずに、構造化された `SOURCE_INVALID` エラーで拒否されます。問題がファイル内の特定の位置にある場合、メッセージにはその行、列、翻訳単位の内側であれば翻訳単位の 1 から始まる序数が示されます。`tmxErrorLocation(error)` は、同じ位置を `TmxErrorLocation` として返します。ほかのエラーでは `undefined` を返すため、エラーやその `cause` をキャストする必要はありません。言語タグは、明示的なルールで、設定されたロケールに解決されます。まず、小文字にしてアンダースコアをハイフンにそろえた綴りが完全に一致するものを探します。見つからなければ、タグの部分タグの接頭辞になっている最長の設定済みロケール（RFC 4647 のルックアップ）を探します。それでも見つからなければ、地域またはバリアントの部分タグだけでタグを拡張している設定済みのロケールを探し、文字体系で拡張しているものは対象にしません。そのため、文字体系や地域の部分タグが異なる 2 つのタグ（`sr-Latn` と `sr-Cyrl`、`de-AT` と `de-CH`）は一致しません。タグがあいまいと報告されるのは、届き得るロケールが 1 本の接頭辞の連鎖上にない場合だけです。1 つの翻訳単位の中で、同じロケール（ソースロケールを含む）に解決されるセグメントが複数ある場合、最後のものが勝つことはありません。完全一致のタグは接頭辞の一致より優先されます。同順位の 2 つのセグメントの値が異なる場合、そのロケールには何も保存されず、`conflicting` として数えられます（ソースロケールでは、翻訳単位が拒否され `conflictingSourceUnits` に数えられます）。そのうえで、すべての候補訳が、プロバイダーの出力や記入済みのブックの行がすでに通っているのと同じゲートを通ります。プレースホルダー、インラインマークアップ、ICU、崩れた出力、空であることの検査で、後でそれを読み込む実行に任せず、レコードが翻訳メモリに入る時点で確認されます。

インポートされた翻訳単位が、翻訳メモリにすでにある訳文と食い違う場合は、`overwrite` を設定しない限り、翻訳メモリの内容が優先されます。翻訳単位は、現在の設定のフィンガープリントのもとで保存されます。これは実際の実行が書き込むのと同じキャッシュキーです。そのため、プロバイダー、モデル、トーン、verbatra が送る用語集の用語、プロバイダーの `localeMap` が変わると、一致しなくなります。同じファイルを 2 回インポートしても、2 回目は何も変わりません。

損傷したデータに対しては、スローせずにレポートを返します。読み込んだ翻訳単位の数、ロケールごとの `added`、`unchanged`、`overwritten`、`kept`、`duplicates`、`conflicting`、理由別の `rejected` の内訳、さらにスキップされた翻訳単位、ソースのセグメントがなかった翻訳単位、インラインマークアップが失われた翻訳単位、`sub` のテキストが除外された翻訳単位（`subflowDroppedUnits`）、どれにも一致しなかった、またはあいまいに一致した言語タグです。`memoryWritable` が false になるのは、翻訳メモリのファイルがより新しい verbatra によって書かれた場合で、そのときファイルには手を加えません。その場合も、ドライランと同様にロケールごとの件数は報告されます。そのため `added` と `overwritten` は、書き込まれていたであろう内容を表します。`memoryWritable` が false の場合、実際には何も書き込まれていません。

<AvailableFrom version="0.12.0" />

各ロケールには `refusals` も一覧されます。ゲートの理由で数えられた翻訳単位ごとに 1 つの `TmxUnitRefusal` が入り、`{ unit, reason, details? }` の形です。`unit` はファイル内の翻訳単位の 1 から始まる序数で、`details` は、ターゲット言語に合わない ICU の分岐など、問題の内容を示します。

### tmxErrorLocation [#tmxerrorlocation]

`importTmx` がスローしたものから、拒否された TMX ファイルのどこで問題が起きたかを読み取ります。ファイル内の位置を持つ `SOURCE_INVALID` の拒否では `TmxErrorLocation`（`{ line, column, unit? }`、すべて 1 から始まる）を返します。ファイルがない、大きすぎるなど、ほかのエラーでは `undefined` を返します。そのため、エラーやその `cause` をキャストする必要はありません。

```ts title="シグネチャ"
function tmxErrorLocation(
  error: unknown,
): TmxErrorLocation | undefined;
```

**戻り値**：`TmxErrorLocation | undefined`

```ts title="例"
import { importTmx, tmxErrorLocation, type VerbatraConfig } from "@verbatra/sdk";

declare const config: VerbatraConfig;

try {
  await importTmx({ config, file: "legacy.tmx" });
} catch (error) {
  const at = tmxErrorLocation(error);
  if (at !== undefined) console.error(`line ${at.line}, column ${at.column}`);
}
```

### exportTmx [#exporttmx]

翻訳メモリを TMX 1.4b として書き出します。`out` のデフォルトは `DEFAULT_TMX_PATH`（`verbatra-memory.tmx`）で、定数としてエクスポートされています。翻訳メモリを読み込む前に、`TMX_OUTPUT_CONFLICT` が、次のような `out` を拒否します。ファイルを指していない（パス区切り文字で終わるものを含む）、`cwd` の外、または `cwd` そのものに解決される、あるいは設定済みのロケールファイル、ロックファイル、来歴ファイル、翻訳メモリのキャッシュ、verbatra が設定を探すファイル、`configPath` のファイル、`glossaryPath` のファイルを指すものです。比較は大文字と小文字を区別せずに行われ、`deps.fs` がデフォルトと同様に `realpath` を実装している場合は、シンボリックリンクを解決した後にもう一度行われます。書き込みが失敗した場合は、`TMX_UNWRITABLE` をスローし、ファイルとファイルシステムのコードを示します。ディレクトリに書き込めない、そのパスにディレクトリがある、ディスクが満杯などが原因です。書き出されるのは、現在の設定のフィンガープリントのもとにあるエントリだけです。これは、実行が再利用するのと同じ集合です。言語タグは BCP 47 の形式で書き込まれます（`en_US` は `en-US` になります）。翻訳メモリのキーの付け方は変わりません。空の翻訳メモリからは、エラーではなく、有効で空のファイルが生成されます。

```ts title="シグネチャ"
function exportTmx(
  input: ExportTmxInput,
  deps?: ExportTmxDeps,
): Promise<ExportTmxResult>;
```

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `config` | `VerbatraConfig` | yes | The resolved project config, normally from loadConfig. |
| `out` | `string` | no | Where to write the file. Defaults to DEFAULT_TMX_PATH, resolved against `cwd`. Refused with `TMX_OUTPUT_CONFLICT`, before anything is read or written, when it names no file, resolves outside `cwd` or to `cwd` itself, or names a configured locale file, the lock file, the provenance file, the translation-memory cache, a file verbatra searches for its configuration, the ExportTmxInput.configPath file, or the ExportTmxInput.glossaryPath file. Names are compared case-insensitively, and, when the file-system port implements `realpath`, again after symbolic links are resolved, so a link cannot carry the file anywhere a plain path could not. |
| `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. |
| `cwd` | `string` | no | Directory the output path and the memory 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. |
| `locales` | `readonly string[]` | no | Subset of configured target locales to export. Defaults to all of them. |
| `toolVersion` | `string` | no | Value for the TMX header's `creationtoolversion`. Defaults to `unknown`. |

**戻り値**：`ExportTmxResult`

**例外**：[`UNKNOWN_LOCALE`](https://verbatra.kreitz-webdev.de/ja/docs/error-codes.md#unknown_locale)、[`CONFIG_INVALID`](https://verbatra.kreitz-webdev.de/ja/docs/error-codes.md#config_invalid)、[`TMX_OUTPUT_CONFLICT`](https://verbatra.kreitz-webdev.de/ja/docs/error-codes.md#tmx_output_conflict)、[`TMX_UNWRITABLE`](https://verbatra.kreitz-webdev.de/ja/docs/error-codes.md#tmx_unwritable)、[`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)

**例**：[TMX の往復](https://verbatra.kreitz-webdev.de/ja/docs/programmatic-api.md#tmx-の往復)

`{ path, units, locales, withoutSource, otherConfiguration?, illegalCharactersRemoved, provenanceMarkers }` を返します。`withoutSource` は、翻訳メモリにそのソーステキストがないために除外されたエントリの数です。これは、翻訳メモリがソーステキストを保存するようになる前に書かれたキャッシュから引き継がれたエントリでだけ起こります。`otherConfiguration` は、別の設定のフィンガープリント（以前のプロバイダー、モデル、トーン、用語集）のもとで保存されているために除外されたエントリの数で、ロケールとハッシュごとに 1 回数えます<AvailableFrom version="0.13.5" />。`illegalCharactersRemoved` は、XML 1.0 で表現できないために、セグメントのテキストから削除された文字の数です。

<AvailableFrom version="0.12.0" />

各ターゲットセグメントには `<prop type="x-origin">`（`machine`、`human`、`import`、`unknown` のいずれか。型は `TmxOrigin`）が付き、`machine` のセグメントにはさらに `<prop type="x-review">`（`approved`、`unreviewed`、`rejected` のいずれか。型は `TmxReview`）が付きます。これらは、ロックファイルのエントリがそのセグメントのソースを指し、記録がそのテキストとまったく同じものを記述しているすべてのキーから導き出されます。来歴ファイルまたはロックファイルを読み込めなかった場合、`provenanceMarkers` は `"unavailable"` になり、どのセグメントにもプロパティは付きません。
