> ## Documentation Index
> Fetch the complete documentation index at: https://hyperlocalise.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# 短语适配器

> 配置 Phrase 以进行远程翻译同步。

## 必需配置

```jsonc theme={null}
{
  "storage": {
    "adapter": "phrase",
    "config": {
      "projectID": "project-uuid",
      "apiTokenEnv": "PHRASE_API_TOKEN",
      "mode": "strings"
    }
  }
}
```

## 可选配置字段

* `sourceLanguage`
* `targetLanguages`
* `timeoutSeconds`
* `fileFormat`（当`mode`为`files`时必填）

## 模式

* `strings`：使用 Phrase key 和翻译 API 进行拉取和推送。
* `files`：使用 Phrase 导出/导入任务进行拉取和推送。

## 常见问题

* 未找到标记：export `PHRASE_API_TOKEN`
* 模式验证错误：将 `mode` 设置为 `strings` 或 `files`
* 文件模式导入失败：请验证 `fileFormat` 是否与你的项目设置一致

## Phrase CLI 配置

文件工作流命令也可以读取 Phrase 的`.phrase.yml`格式：

```yaml theme={null}
phrase:
  access_token: $PHRASE_ACCESS_TOKEN
  project_id: project-uuid
  file_format: json
  host: https://api.phrase.com/v2
  locale_mapping:
    fr-FR: fr
  push:
    sources:
      - file: ./locales/en.json
        params:
          locale_id: en-US
          tags: app,source
          update_translations: true
  pull:
    targets:
      - file: ./locales/<locale_name>.json
        params:
          locale_id: fr-FR
          include_unverified_translations: false
```

支持的命令：

* `hyperlocalise phrase config validate --config .phrase.yml`
* `hyperlocalise phrase upload sources --config .phrase.yml`
* `hyperlocalise phrase download translations --config .phrase.yml`

如果省略 `--config`，Hyperlocalise 会先检查 `PHRASEAPP_CONFIG`，然后检查当前目录中的 `.phrase.yml`，再检查 `$HOME/.phrase.yml`。