使用 CLI (Strings)

通过编辑 .phrase.yml 配置文件控制客户端如何推送和拉取文件。

配置文件示例。

转义规则和引号的使用

当命令行传递 JSON 对象时，转义规则和引号的用法可能因所使用的 shell 而异。

如果使用 Windows shell，用双引号 "" 括住整个 JSON 字符串，并在 JSON 中使用反斜杠 \ 字符转义双引号。例如：

phrase locales create --project_id PROJECT123 --data "{\"name\":\"French\", \"code\":\"fr\"}" --access_token TOKEN123123

访问 API 端点

客户端可用于访问所有 API 端点。例如列出所有项目：

$ phrase projects list --access_token ACCESS_TOKEN

使用 Phrase 凭据进行身份验证

使用 --username 标记指定用户名，密码将在稍后请求：

$ phrase projects list --username user@example.com
Password: ********

如果用户或公司启用了双因素验证，必须通过 --tfa 标记提供有效的多因素令牌：

$ phrase projects list --username user@example.com --tfa
Password: ********
TFA: ********

使用 Strings 令牌进行身份验证

使用 --access_token 标记指定访问令牌：

$ phrase projects list --access_token ACCESS_TOKEN

或使用 PHRASE_ACCESS_TOKEN 环境变量存储令牌：

export PHRASE_ACCESS_TOKEN="ACCESS_TOKEN"

如果启用了双因素验证，必须通过 --x_phrase_app_otp 标记提供有效的多因素令牌：

$ phrase projects list --access_token ACCESS_TOKEN --x_phrase_app_otp PASSWORD

也可以通过 --tfa 标记以交互模式提供令牌：

$ phrase projects list --access_token ACCESS_TOKEN --tfa
TFA: ********

默认从 .phrase.yml 配置文件中读取访问令牌，但可以使用提到的标记或环境变量来覆盖该行为，此时将使用通过标记或环境变量提供的令牌。通过标记提供的令牌覆盖通过环境变量提供的令牌。

将 .phrase.yml 文件存储在代码存储库中时，建议先移除令牌并使用其他方法，例如通过环境变量或命令行标记传递令牌。将机密令牌直接存储在存储库中可能会导致安全问题。

使用 Platform 令牌进行身份验证

Platform API 令牌 不会被 Strings CLI 直接接受。 用户必须首先 将其交换为短期产品令牌 (JWT)，然后通过以下选项之一使用返回的令牌：

推送和拉取

使用 push 和 pull 命令上传和下载本地化文件。Push 和 pull 依赖于存储在项目根目录文件夹中 .phrase.yml 配置文件的配置，而不是命令行参数。

如果 push 将 update_translations 选项设置为true，则推送的内容将覆盖翻译。Pull 始终覆盖本地文件中的翻译。

若要在从原文/源语文件中移除键时自动删除 Phrase Strings 中的键，请将 delete_unmentioned_keys: true 参数添加到 .phrase.yml 配置文件的 push 部分。此参数必须放置在 push 级别，作为 sources 的同级，而不是嵌套在 params 下。此参数会删除 Phrase 项目中同步文件中不存在的任何键。仅当原文/源语文件包含项目的所有键时，才使用此参数。

典型 Rails 应用程序的上传和下载本地化文件配置示例：

phrase:
  access_token: "ACCESS_TOKEN"
  project_id: "PROJECT_ID"
  file_format: "yml"
  push:
    sources:
      - file: "./config/locales/<locale_name>.yml"
  pull:
    targets:
      - file: "./config/locales/<locale_name>.yml"

使用 push 命令将本地化文件上传到 project_id 指定的项目，该项目与 config/locales 文件夹中的 de.yml 和 en.yml 文件相匹配。如果有新键，这些键将被添加到本地化文件中：

$ phrase push
Uploading config/locales/de.yml
Uploaded config/locales/de.yml successfully.
Uploading config/locales/en.yml
Uploaded config/locales/en.yml successfully.

使用 pull 命令将 project_id 指定的项目中的本地化文件下载到相关的文件路径。如果有新键，这些键将被添加到项目中：

$ phrase pull
Downloaded de to config/locales/de.yml
Downloaded en to config/locales/en.yml

速率限制支持

客户端支持本地化文件下载速率限制。当达到速率限制时，客户端等待直到速率限制过期，然后继续下载本地化文件。客户端显示超出速率限制，将在 x 秒后恢复下载。

上传清理

uploads cleanup 命令用于删除项目中未包含在上传文件中的键。推送本地化文件后，可能需要删除默认区域或其他区域不包含的所有键：

$ phrase uploads cleanup --id <YOUR_UPLOAD_ID>

格式选项

上传时支持多种格式，如 CSV。通过在选项前加上 --format_options 前缀来访问这些选项：

phrase uploads create \
--project_id PROJECT_ID \
--file ./en.csv \
--file_format csv \
--locale_mapping ‘{“en”:3, “de”:2}’ \
--format_options ‘{“key_index”:1}’ \
--access token YOUR_ACCESS_TOKEN

翻译键前缀

翻译键前缀可防止不同项目或文件之间的键冲突，并提高翻译键的可追溯性。CLI 界面支持针对 pull 和 push 操作的键前缀处理。

phrase.yml 文件的配置示例：

phrase:
  access_token: access_token
  file_format: yml
  push:
    sources:
      -
        file: path/to/your/file.yml
        project_id: project_id
        params:
          locale_id: en
          translation_key_prefix: prefix_
  pull:
    targets:
      -
        file: path/to/your/file.yml
        project_id: project_id
        params:
          translation_key_prefix: prefix_
          filter_by_prefix: true

Curl 命令示例：

curl "https://api.phrase.com/v2/projects/:project_id/uploads?translation_key_prefix=prefix_" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X POST \
  -F file=@/path/to/my/file.format \
  -F file_format=format \
  -F locale_id=locale_id

curl \"https://api.phrase.com/v2/projects/:project_id/locales/:id/download?file_format=file_format&translation_key_prefix=prefix_&filter_by_prefix=true\" \\
  -u USERNAME_OR_ACCESS_TOKEN

代理

如果使用了代理，请使用 HTTPS_PROXY 环境变量指定代理设置：

export HTTPS_PROXY=https://user:password@host:port

一个项目多个本地化文件

项目中的每个区域使用单独的文件。如果工具或框架强制使用多个文件，请参阅维护文件结构了解如何设置项目。

一个本地化项目中有多个项目

处理大型本地化项目时，将翻译分配到多个项目中。将 CLI 配置为处理一个本地化项目中多个本地化文件。

格式选项

一些文件格式允许指定格式选项，以加强对文件语法的控制。在 .phrase.yml 配置文件中指定格式选项：

phrase:
  pull:
    targets:
    - file: file.xml
      params:
        format_options:
          convert_placeholder: true

  push:
    sources:
    - file: file.csv
      params:
        format_options:
          column_separator: ";"

Android 项目配置

Android 不使用标准的 ISO 语言代码作为文件模式。在 .phrase.yml 中指定所需的模式。

无需为每个区域定义单独的译文目标，请结合使用全局 locale_mapping 设置和 <locale_name> 占位符。CLI 将使用映射中的自定义名称作为相应区域的名称，并对所有其他语言回退到默认的 Phrase 区域代码。

例如：

phrase:
  access_token: ACCESS_TOKEN
  project_id: PROJECT_ID
  file_format: "xml"

  # 将 Phrase 区域映射到 Android 特定的目录名称
  locale_mapping:
    en-US: values
    de-DE: values-de-rDE
    fr-FR: values-fr

  push:
    sources:
      # 原文/源语文件是默认语言，映射到 'values'
      - file: ./app/src/main/res/values/strings.xml
        params:
          locale_id: en-US # 必须与 Phrase 中的原文/源语区域匹配

  pull:
    targets:
      # 使用 <locale_name> 占位符，它将被映射替换
      - file: ./app/src/main/res/<locale_name>/strings.xml