Using the 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: ********

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

设置环境变量在不同的平台上效果不同。建议将访问令牌存储在 .phrase.yml 配置文件中。

使用 --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 配置文件中读取访问令牌，但可以使用提到的标记或环境变量来覆盖该行为，此时将使用通过标记或环境变量提供的令牌。通过标记提供的令牌覆盖通过环境变量提供的令牌。

推送和拉取

使用 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
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 界面支持拉取和推送操作的字符串前缀处理。

phrase.yml 文件配置示例：

phrase:
  access_token: access_token
  file_format: yml
  push:
    sources:
      -
        文件: path/to/your/file.yml
        project_id: project_id
        params:
          locale_id: en
          translation_key_prefix: prefix_
  pull:
    targets:
      -
        文件: 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 中指定所需的模式。

在 .phrase.yml 文件中明确指定每个区域。以英语为默认语言、德语区域和奥地利德语区域为例，.phrase.yml 设置为：

phrase:
  access_token:ACCESS_TOKEN
  project_id:PROJECT_ID
  file_format: xml
  pull:
    targets:
    - file: ./app/src/main/res/values/strings.xml
      params:
        file_format: xml
        # Unique locale id for English
        locale_id:LOCALE_ID
    - file: ./app/src/main/res/values-de/strings.xml
      params:
        file_format: xml
        # Unique locale id for German
        locale_id:LOCALE_ID
    - file: ./app/src/main/res/values-de-rAU/strings.xml
      params:
        file_format: xml
        # Unique locale id for Austrian
        locale_id:LOCALE_ID
  push:
    sources:
    - file: ./app/src/main/res/values/strings.xml
      params:
        file_format: xml
        locale_id:LOCALE_ID
    - file: ./app/src/main/res/values-de/strings.xml
      params:
        file_format: xml
        locale_id:LOCALE_ID
    - file: ./app/src/main/res/values-de-rAU/strings.xml
      params:
        file_format: xml
        locale_id:LOCALE_ID