---
title: "verbatra export"
description: "把未翻译的字符串导出为译者交接文件：带样式的 Excel 工作簿、每个语言环境一个 CSV 或 TSV 文件，或每个语言环境一个供 CAT 工具使用的 XLIFF 文件。"
type: "reference"
---
# verbatra export

把未翻译的字符串导出为译者交接文件：带样式的 Excel 工作簿、每个语言环境一个 CSV 或 TSV 文件，或每个语言环境一个供 CAT 工具使用的 XLIFF 文件。

把需要翻译的字符串写成交接文件，由人填写后发回，供 [`verbatra import`](https://verbatra.kreitz-webdev.de/zh-CN/docs/cli/import.md) 导入。默认只包含缺失和已更改的字符串，也就是自动运行会发送给提供商的那些键。源值为空或只有空白的键，在你写好它的源文本之前没有行。`export` 从不调用提供商，也不需要 API 密钥。

## 用法 [#用法]

```bash
verbatra export [flags]
```

## 示例 [#示例]

```bash
# write the workbook with missing and changed strings
verbatra export

# only the German and French sheets, to a specific path
verbatra export --locales de,fr --out handoff/round-2.xlsx

# one de.csv and fr.csv under handoff/
verbatra export --format csv --out handoff

# one de.xlf and fr.xlf in XLIFF 2.0 for a CAT tool
verbatra export --format xliff2 --out handoff
```

## 选项 [#选项]

| 选项 | 参数 | 默认值 | 作用 |
| --- | --- | --- | --- |
| `--out` | `<path>` | `verbatra-translations.xlsx`；其他格式为 `verbatra-translations` | 交接文件的写入位置：`xlsx` 为文件，`csv`、`tsv`、`xliff2` 和 `xliff12` 为目录 |
| `--format` | `<format>` | `xlsx` | `xlsx`（Excel 工作簿）、`csv` 或 `tsv`（每个语言环境一个文件）、`xliff2` 或 `xliff12`（每个语言环境一个 XLIFF 文件） |
| `--locales` | `<list>` | 所有已配置的目标语言环境 | 只导出这个用逗号分隔的子集；未配置的语言环境以 `UNKNOWN_LOCALE` 失败，空列表以 `INVALID_LOCALES` 失败，两者都以 `2` 退出 |
| `--include-unchanged` | 无 | 关闭 | 同时导出已是最新的字符串 |

此命令还接受[全局选项](https://verbatra.kreitz-webdev.de/zh-CN/docs/cli.md#全局选项) `--cwd`、`--config` 和 `--json`。

## 行为 [#行为]

### CSV 和 TSV [#csv-和-tsv]

`--format csv` 和 `--format tsv` 为每个导出的语言环境写出一个 `<locale>.csv` 或 `<locale>.tsv`，列及其顺序与工作簿的工作表相同。`--out` 指定目录，目录不存在时会创建。

分隔符文件便于做差异比对，到处都能打开，但它没有单元格保护：每一列都可编辑，`Source hash` 列也可见。verbatra 从不信任被编辑过的哈希：导入时会把它与当前源值比对，并搁置该行。

每次分隔符文件导出还会写入一个隐藏的清单 `.verbatra-export-csv.json` 或 `.verbatra-export-tsv.json`，列出本次写出的语言环境。之后用范围更窄的 `--locales` 导出，会让被去掉的语言环境退役：它们的文件保留在磁盘上，[`verbatra import`](https://verbatra.kreitz-webdev.de/zh-CN/docs/cli/import.md) 会把它们当作遗留文件拒绝。导出从不删除输出目录中的任何内容。

### XLIFF [#xliff]

<AvailableFrom version="0.12.0" />

`--format xliff2` 写出 XLIFF 2.0，`--format xliff12` 写出 XLIFF 1.2：在 `--out` 目录中为每个导出的语言环境写出一个 `<locale>.xlf`，另有一个 `.verbatra-export-xliff.json` 清单，作用与 CSV 的清单相同。每个键成为一个以该键命名的单元，占位符和内联标记成为受保护的内联代码，键的描述和含义成为备注，句段状态跟随锁文件和审校状态（缺失或过期的键为 `initial`，已是最新为 `translated`，已批准为 `reviewed`）。详见[交给翻译公司（XLIFF）](https://verbatra.kreitz-webdev.de/zh-CN/docs/translation-agency.md)。

每个目标还会说明它的来源。在 XLIFF 1.2 中，由提供商、翻译记忆库或 AI 智能体写入且无人批准的目标带有 `state-qualifier="mt-suggestion"`；在 XLIFF 2.0 中，单元的 `verbatra` 元数据组带有 `origin` 和 `review-state`。导入会忽略这两者。无法读取 `verbatra.provenance.json` 时，不写入任何标记，`--json` 结果带有 `provenanceMarkers: "unavailable"`。详见[记录机器翻译证据](https://verbatra.kreitz-webdev.de/zh-CN/docs/provenance-evidence.md#导出文件中的标记)。

### 交接文件的写入位置 [#交接文件的写入位置]

交接文件只会写入项目根目录之内。读取任何内容之前，`export` 会以 `EXPORT_OUTPUT_CONFLICT` 拒绝以下 `--out`：越出项目根目录的路径，或者本身（或通过它将写入的某个文件）指向项目所依赖文件的路径，这些文件包括已配置的语言文件、锁文件、来源记录文件、翻译记忆库缓存、verbatra 会查找的配置文件、本次运行加载的配置，以及已配置的 `glossary` 文件。对 `xlsx`，没有指向文件的路径（例如 `out/`）或项目根目录本身也会被拒绝。名称比较不区分大小写，符号链接解析之后会再检查一次。

通过检查的路径仍可能在写入时失败（不可写、路径已被占用、磁盘已满）：运行以 `EXPORT_UNWRITABLE` 停止，并给出文件和文件系统错误码。

目标语言环境无法给出工作表名或文件名时，导出以 `WORKBOOK_INVALID` 停止。xlsx 工作表名必须为 1 到 31 个字符，不得包含 `: \ / ? * [ ]` 中的任何字符，也不得与 `Instructions` 或另一个目标语言环境的工作表名相同（不区分大小写）。`csv`、`tsv` 或 `xlf` 文件名不得为空、`.` 或 `..`，不得包含路径分隔符、控制字符，也不得包含 `: * ? " < > |` 中的任何字符。同一个错误码也涵盖无法序列化的工作簿。

### 终端反馈 [#终端反馈]

<AvailableFrom version="0.12.0" />

`export` 在写入期间显示一行，有内容要交接时，还会给出把填好的文件带回来的导入命令：

```text output
verbatra: exporting to xlsx... done (0.3s)
next: verbatra import verbatra-translations.xlsx (once your translators have filled it in)
```

没有待处理内容且未传入 `--include-unchanged` 时，文件没有行，`next:` 行会改为建议带 `--include-unchanged` 的同一个导出，并保留 `--format`、`--out`、`--locales`、`--cwd` 和 `--config`。 <AvailableFrom version="0.13.5" />

这些行输出到 stderr，`--quiet` 会去掉它们。详见[终端输出](https://verbatra.kreitz-webdev.de/zh-CN/docs/cli/output.md#终端输出)。

无法使用的 `verbatra.limits.json` 会被忽略，并在 stderr 上给出警告（`--json` 中为 `LIMITS_FILE_IGNORED`）。

### JSON 输出 [#json-输出]

Schema：[`export-envelope.json`](https://verbatra.kreitz-webdev.de/schema/v1/export-envelope.json) 校验整个信封（envelope）；其他 schema 见 [Schema](https://verbatra.kreitz-webdev.de/zh-CN/docs/cli/output.md#schema)。

使用 `--json` 时，[信封](https://verbatra.kreitz-webdev.de/zh-CN/docs/cli/output.md#json-输出)包含交接文件的去向和每个语言环境的行数：

```ts
{
  path: string;                // absolute path: the workbook for xlsx, the output directory otherwise
  locales: { locale: string; rows: number }[];
  provenanceMarkers?: "written" | "unavailable"; // XLIFF formats only
  limitsNotice?: { code: "LIMITS_FILE_IGNORED"; message: string };
}
```

## 退出码 [#退出码]

| 退出码 | 含义 |
| --- | --- |
| `0` | 交接文件已写入 |
| `2` | 无法运行：整次运行的错误、被拒绝的输出路径（`EXPORT_OUTPUT_CONFLICT`）、无法写入的交接文件（`EXPORT_UNWRITABLE`、`WORKBOOK_INVALID`），或用法错误 |

`export` 没有按语言环境的失败模式，所以从不以 `1` 退出。每个命令都遵循的约定见[退出码](https://verbatra.kreitz-webdev.de/zh-CN/docs/cli/output.md#退出码)。

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

- [手动翻译](https://verbatra.kreitz-webdev.de/zh-CN/docs/manual-translation.md)：介绍工作簿的布局、审校列和完整的往返流程。
- [交给翻译公司（XLIFF）](https://verbatra.kreitz-webdev.de/zh-CN/docs/translation-agency.md)：介绍面向 CAT 工具的 XLIFF 交接。
- [`verbatra import`](https://verbatra.kreitz-webdev.de/zh-CN/docs/cli/import.md)：读回填好的交接文件。
