使用 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
密码：********

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

$ phrase projects list --username user@example.com --tfa
密码：********
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 文件存储在代码存储库时，建议先移除令牌，并使用其他方法，例如通过环境或命令行标记传递令牌。直接在存储库中存储秘密令牌可能会导致安全问题。

使用平台访问令牌进行身份验证

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

推送和拉取

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

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

典型 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
正在上传 config/locales/de.yml
config/locales/de.yml 上传成功。
正在上传 config/locales/en.yml
config/locales/en.yml 上传成功。

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

$ phrase pull
已下载 de 到 config/locales/de.yml
已下载 en 到 config/locales/en.yml

速率限制支持

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

上传清理

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

$ 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接口支持对拉取和推送操作的键前缀处理。

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