创建 CLI 配置文件 (Strings)

先决条件

有关更详细的信息，请参阅 Developer Hub。

要自动创建配置文件，请参照以下步骤：

当前目录中会创建一个基本的 .phrase.yml 文件。

提供标志以完全跳过向导，例如 phrase init --access_token=$PHRASE_ACCESS_TOKEN --project_id=... --file_format=ios_strings --path='ios/*.strings'。

如果使用手动创建或复制的配置文件，请将其放在以下位置之一：

全局设置

键	类型	必需的	说明
`phrase.access_token`	字符串	是	个人令牌。
`phrase.project_id`	字符串	是	Strings 项目设置中显示的公共项目 ID。
`phrase.file_format`	字符串	是	默认区域文件格式 (API 扩展)。
`phrase.locale_mapping`	对象	否	将 Phrase 区域 ID 映射到自定义名称，以便在文件路径中使用 `<区域_名称>` 占位符。这对于具有非标准命名约定的平台（如 Android）非常有用。如果映射中未指定区域，则默认使用其标准 Phrase 区域名称。

推送：原文/源语

键	类型	必需的	说明
`push.sources[].file`	路径	是	要推送的文件相对于路径，例如 `./path/to/file/<区域_代码>.json`。支持 `<区域_名称>`、`<区域_代码>`、`<标记>`。
`push.sources[].project_id`	字符串		覆盖此特定原文/源语文件的全局 `项目_ID`。在从同一配置文件向多个 Phrase 项目推送文件时非常有用。

推送：参数

参数	类型	默认	说明
`file_format`	字符串	标题	覆盖此原文/源语的文件格式。
`locale_id`	字符串	—	区域名称（例如 `en-US`）或公共区域 ID。
`tags`	字符串	—	用于新键的逗号分隔标记。
`update_translations`	布尔值	`false`	使用文件内容更新现有翻译。
`update_translation_keys`	布尔值	`true`	在此处传递 `false` 以防止创建新键并更新现有键。
`update_descriptions`	布尔值	`false`	更新键描述；空描述会覆盖现有描述。
`skip_upload_tags`	布尔值	`false`	未创建上传标记。
`skip_unverification`	布尔值	`false`	更新后的译文不会被标记为未验证。
`file_encoding`	字符串	—	文件编码：`UTF-8`、`UTF-16`、`UTF-16BE`、`UTF-16LE` 或 `ISO-8859-1`。
`locale_mapping`	对象	—	（仅限 Excel/CSV）将区域代码映射到列名，例如 `{"en": "C", "de": "D"}` 以解析译文。这与用于文件路径的顶层 `locale_mapping` 不同。
`autotranslate`	布尔值	`false`	自动获取已上传语言的译文。
`mark_reviewed`	布尔值	`false`	将导入的译文标记为已审校（必须启用高级审校工作流）。

推送：格式选项

CLI 配置中支持所有可用的格式选项。请参阅示例配置文件以获取示例。

拉取：译文

键	类型	必需的	说明
`pull.targets[].file`	路径	是	拉取区域文件的相对路径，例如 `./Radio.de/<locale_code>.lproj/Localizable.Strings`。
`pull.targets[].project_id`	字符串		覆盖此特定拉取目标的全局 `project_id`。启用从多个 Phrase 项目拉取译文，并使用相同的配置文件。

拉取：参数

参数	类型	默认	说明
`file_format`	字符串	—	必须为 `Strings`。
`locale_id`	字符串	—	区域名称（例如 `en-US`）或公共区域 ID。
`tags`	字符串	—	用于筛选要拉取哪些键的逗号分隔标记。
`include_empty_translations`	布尔值	`false`	包含没有任何译文的键。
`exclude_empty_zero_forms`	布尔值	`false`	当为空时排除零形式复数。
`include_translated_keys`	布尔值	`true`	包含已经有译文的键。
`keep_notranslate_tags`	布尔值	`false`	在输出中保留 `[NOTRANSLATE]` 标记。
`编码`	字符串	—	文件编码：`UTF-8`、`UTF-16`、`UTF-16BE`、`UTF-16LE` 或 `ISO-8859-1`。
`include_unverified_translations`	布尔值	`true`	如果为 `false`，则排除未验证翻译。
`use_last_reviewed_version`	布尔值	`false`	如果为 `true`，则使用最后已审校版本（需要高级审校工作流）。
`fallback_locale_id`	字符串	—	用于缺失翻译的后备区域。

拉取：格式选项

CLI 配置中支持所有可用的格式选项。请参阅示例配置文件以获取示例。

在 monorepo 中，在每个包中放置一个配置文件，并从相应的子文件夹运行 CLI，或者使用 --config 选项将 CI 作业指向不同的配置文件。

GitLab:

.phrase.yml 配置文件必须存在于存储库中。该文件定义了从存储库导入 (pull) 或导出 (push) 哪些文件。
存储库需要读取和写入权限。
配置文件定义不正确可能会导致错误。确保文件至少包含一个 push 和一个 pull 目标、正确的文件格式以及正确的 update_translations 参数。
使用 GitLab 9.5 或更高版本以确保 API 兼容性。

GitHub:

.phrase.yml 配置文件必须存在于存储库中。该文件定义了从存储库导入 (pull) 或导出 (push) 哪些文件。
存储库需要读取和写入权限。
配置文件定义不正确可能会导致错误。确保文件至少包含一个 push 和一个 pull 目标、正确的文件格式以及正确的 update_translations 参数。
存储库范围内的 GitHub 访问令牌（如果与公共存储库同步，则为 public_repo）。
如果在 GitHub 中启用了 SSO，也必须为访问令牌启用。
不能保护 phrase_translations 分支。
确存储库设置不需要提交签名。

BitBucket:

.phrase.yml 配置文件必须存在于存储库中。该文件定义了从存储库导入 (pull) 或导出 (push) 哪些文件。
存储库需要读取和写入权限。
配置文件定义不正确可能会导致错误。确保文件至少包含一个 push 和一个 pull 目标、正确的文件格式以及正确的 update_translations 参数。