# gt: General Translation CLI tool: .xcstrings
URL: https://generaltranslation.com/zh/docs/cli/reference/formats/xcstrings-files.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: 使用 General Translation CLI 翻译 Apple String Catalogs。.xcstrings 文件格式的 API 参考。

CLI 支持翻译 `.xcstrings` 文件，该类文件将源内容和所有区域设置一并存储在同一个 String Catalog 中。此功能需要 `gt` 2.21.0 或更高版本。

## 概览 [#overview]

| 主题                    | 说明                          |
| --------------------- | --------------------------- |
| [配置](#config)         | 选择翻译目录，并将所有区域设置保存在同一个文件中。   |
| [工作原理](#how-it-works) | 上传时拆分源内容，下载时合并已翻译的区域设置。     |
| [本地编辑](#local-edits)  | 同步编辑内容，且不将翻译目录中的其他区域设置视为变更。 |
| [错误](#errors)         | 识别无效的翻译目录和不受支持的 path 设置。    |

## Configuration [#config]

在 `files` 下添加一个 `xcstrings` entry，并通过 `include` array 直接指向每个 翻译目录。

```json title="gt.config.json"
{
  "defaultLocale": "en",
  "locales": ["es", "ja"],
  "files": {
    "xcstrings": {
      "include": ["Resources/Localizable.xcstrings"]
    }
  }
}
```

String 翻译目录 将所有区域设置保存在同一个文件中，并原地更新。其 `include` 模式不得包含 `[locale]`，且 `xcstrings` 配置不接受 `transform`。

翻译目录 的 `sourceLanguage` 必须解析为与 `defaultLocale` 相同的规范区域设置。例如，`"sourceLanguage": "en"` 的 翻译目录 可以使用 `"defaultLocale": "en"`，但不能使用 `"defaultLocale": "fr"`。

## 工作原理 [#how-it-works]

上传时，CLI 会读取翻译目录，并将仅包含源内容的切片发送到 API。每个 entry 若存在源语言的 localization，则会保留；以 键 本身作为源文本的 entry 也会留在切片中，但不带 `localizations` 字段。已有的目标区域设置不会作为源内容上传。

下载时，CLI 会将每个目标区域设置合并回磁盘上的翻译目录，仅更新匹配 entry 中该区域设置对应的 localization。其他区域设置、comments、提取状态、替换项、变体以及无法识别的字段均保持原样不变。

如果下载的翻译中包含本地翻译目录中已不存在的 键，CLI 会跳过该 键 并输出警告。下载的文件会序列化为使用两个空格缩进的 JSON，并以换行符结尾。

## 本地编辑 [#local-edits]

尽管所有区域设置共用一个文件，下载记录仍按区域设置分别存储。这样可以避免在另一个区域设置被合并到翻译目录 后，将未发生变更的目标区域设置当作本地编辑提交。

使用 [`gt save-local`](/docs/cli/reference/commands/save-local)、[`gt translate --save-local`](/docs/cli/reference/commands/translate) 或 [`options.saveLocal: true`](/docs/cli/reference/config#save-local) 提交已编辑的目标本地化内容。本地编辑同步需要手动启用。

仪表板还会在可编辑的 Raw 视图中打开 `.xcstrings` 翻译。保存编辑时，只会更新翻译目录 中所选的目标区域设置。

## 错误 [#errors]

* JSON 无效、`sourceLanguage` 缺失或为空、或 `strings` 字段不是对象时，CLI 会跳过该翻译目录并报告校验问题。
* 若 `sourceLanguage` 与 `defaultLocale` 不匹配，则在上传文件前终止本次运行。
* 若 `include` 模式中包含 `[locale]`，或设置了 `xcstrings.transform`，也会终止本次运行，因为翻译后的区域设置必须合并回原始翻译目录。
* 字符串映射和本地化映射中不允许使用保留键 `__proto__`。名为 `constructor` 或 `prototype` 的键则受支持。

## Sitemap

See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.