# General Translation Knowledge Base: 如何从 Phrase 迁移到 General Translation？
URL: https://generaltranslation.com/zh/kb/migrate-from-phrase.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: 保留你的区域设置文件、国际化库和已验证的译文。从 Phrase Strings 拉取文件时排除未翻译的键和后备内容，停用 Repo Sync，并在首次运行 npx gt translate 之前使用 npx gt upload 导入这些文件。此后，General Translation 会在构建过程中翻译新增和变更的字符串，你的术语库将存放在上下文分组中，键描述则作为各个键的上下文。
Category: 工作流工具
Last updated: 2026-11-12
Authors: Kevin Wu
Published: 2026-11-12

Phrase Strings 是 Phrase 旗下的软件本地化产品，它以键的形式将字符串存储在项目中，下载时生成区域设置文件，并与你的代码仓库同步。迁移到 General Translation 后，应用现在读取的区域设置文件可以继续沿用：`gt` CLI 会将这些文件连同现有译文一并导入，然后在构建或 CI 中翻译新增和变更的字符串。你的国际化库和键都无需改动；将文案改为内联是另一个独立的可选步骤 (参见[从 react-i18next 迁移](/kb/migrate-from-react-i18next)或[从 next-intl 迁移](/kb/migrate-from-next-intl)) 。你的术语库将转为一个上下文分组，可在应用、文档及其他项目之间共享。本指南仅适用于 Phrase Strings；在 Phrase TMS 中翻译的文档需采用另一套工作流。

## 哪些内容可以从 Phrase Strings 迁移过来？

| 在 Phrase Strings 中                                                   | 在 General Translation 中                                                                                                     |
| -------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `.phrase.yml` 拉取目标                                                   | `gt.config.json` 中的 `files`，用 `[locale]` 替代 `<locale_name>`                                                                 |
| 译文                                                                   | 通过 [`npx gt upload`](/docs/cli/reference/commands/upload) 导入，在其源内容变更前一直保留                                                   |
| 术语库                                                                  | [上下文分组](/docs/platform/dashboard/guides/defining-context-for-translations)中的词汇表，可从 CSV 导入                                   |
| 风格指南                                                                 | [自定义提示词](/docs/platform/dashboard/guides/defining-context-for-translations)，可全局设置，也可按区域设置分别设置                               |
| 键描述和字符数限制                                                            | 一个[键级元数据](/docs/cli/reference/keyed-metadata)文件，为每个键指定 `context` 和 `maxChars`，适用于 JSON 和 YAML                               |
| 翻译记忆库                                                                | 你上传的译文：未变更的字符串沿用现有译文，只翻译新增和修改的字符串。不支持导入 TMX 文件                                                                              |
| Repo Sync                                                            | 在 CI 中运行 [`npx gt translate`](/docs/cli/reference/commands/translate)，或使用 [Locadex](/docs/platform/locadex/quickstart) 拉取请求 |
| 翻译验证与审校                                                              | 在[仪表板](/docs/platform/dashboard/guides/reviewing-translations)中编辑，Enterprise 方案还支持批准                                        |
| 适用于 iOS、Android、React Native、Flutter、i18next 和 Rails 的空中下载 (OTA) SDK | 译文包含在区域设置文件中，随每次应用发布一同交付                                                                                                    |

CLI 可读取 JSON、YAML、`.pot` 和 `.po`、iOS `.strings`、`.stringsdict` 和 `.xcstrings`、Android `strings.xml`、`.resx`、HTML、Markdown 和 MDX 等格式 (参见[支持的格式](/docs/cli/reference/config#files)) 。它无法读取 XLIFF、ARB、Java `.properties`，以及导出的 CSV 和 XLSX 文件，因此拉取时请选择受支持的格式。

## 第 1 步：为每个区域设置拉取一个文件

Phrase 每次下载时都会根据键重新生成文件。如果你的代码仓库中已有 Phrase 同步过的文件，请使用相同的 `.phrase.yml` 目标进行拉取，确保输出一致，并在导入前将其与代码仓库中的文件进行差异比对。

JSON 应用的拉取目标示例如下：

```yaml title=".phrase.yml"
phrase:
  project_id: "YOUR_PROJECT_ID"
  file_format: nested_json
  pull:
    targets:
      - file: ./locales/<locale_name>/app.json
        params:
          file_format: nested_json
          include_empty_translations: false
```

然后使用具有 `read` 作用域的访问令牌运行 [`phrase pull`](https://developers.phrase.com/en/developer-tools/strings-cli)。不加 `--branch` 即可从主分支拉取。如果你的账户位于 Phrase 的美国数据中心，请在 `.phrase.yml` 的 `phrase:` 下添加 `host: https://api.us.app.phrase.com/v2`。

要干净地完成导入，需要注意以下三项设置：

* **未翻译的键。** `include_empty_translations: false` 是 CLI 的默认值，会排除未翻译的键。不要设置 `fallback_locale_id` 或 `use_locale_fallback`，并确认项目设置 **Use fallback for unverified translations** 已关闭。这些选项都会用其他区域设置的文本填补空缺，导致这些文本被当作译文导入。
* **文件格式。** 使用你的库已支持读取的格式：`nested_json` 或 `simple_json`；i18next 使用 `i18next_4`；Rails 使用 `yml`；iOS 使用 `strings` 和 `stringsdict`；`.xcstrings` 使用 `strings_catalog`；Android 使用 `xml`。Phrase 的 `json` 格式指的是 Chrome 扩展 JSON，而非通用 JSON。 (参见 Phrase 的[支持的文件格式](https://support.phrase.com/hc/en-us/articles/9652464547740)。) 
* **区域设置名称。** `<locale_name>` 会展开为你在 Phrase 中为各区域设置所起的名称，例如 `de-AT`。`gt` CLI 会将文件夹名称与你的 `locales` 列表进行精确匹配，因此你可以在 Phrase 中重命名区域设置，或在 `.phrase.yml` 的 `phrase:` 下通过 `locale_mapping` 进行映射 (需要 Phrase CLI 2.59.0 或更高版本) ，也可以直接在 `gt.config.json` 中按拉取下来的名称列出它们。

如果不使用 CLI，可以打开项目的 **Languages** 标签页，点击 **Download** 一次性下载多个区域设置，并确保 **Include empty translations** 保持未勾选。

## 步骤 2：停用 Repo Sync 和 OTA

Phrase 的 [Repo Sync](https://support.phrase.com/hc/en-us/articles/5784125562012-GitHub-Strings) 在 **Automations &gt; Repo Syncs** 下配置，可在推送时导入内容，并以拉取请求的形式导出译文，默认从 `phrase-translations` 分支发起。在 General Translation 写入任何文件之前，请逐一停用这些同步，使其不再导入和导出；关闭所有尚未合并的 Phrase 拉取请求；并从 CI 中移除 `phrase push` 和 `phrase pull` 步骤。如果两个工具写入相同的文件，以最后写入的为准。

如果你的移动应用使用了 Phrase OTA，已安装的应用仍会继续接收新的 OTA 发布。请停止创建发布或删除该分发，使应用不再接收更新，并在后续的应用版本中移除该 SDK。

## 第 3 步：将 CLI 指向这些文件

安装 `gt` CLI，并在 `gt.config.json` 中配置拉取下来的文件：

```json title="gt.config.json"
{
  "defaultLocale": "en",
  "locales": ["de", "fr", "pt-BR"],
  "files": {
    "json": { "include": ["locales/[locale]/app.json"] }
  }
}
```

当 CLI 在你的 `package.json` 中检测到 `i18next` 或 `next-intl` 时，会按 i18next 和 next-intl 的消息语法解析 JSON，其他 JSON 值则一律视为普通字符串。 (参见 [JSON 文件](/docs/cli/reference/formats/json-files)。) 

使用 [`npx gt login`](/docs/cli/reference/commands/login) 登录并设置 `GT_PROJECT_ID`，或在配置中设置 `projectId`。在 CI 环境中，请通过 `GT_API_KEY` 提供一个项目 API 密钥，该密钥需具备 **文件 &gt; 写入**、**翻译队列 &gt; 已启用** 和 **上下文 &gt; 写入** 权限。

## 第 4 步：迁移术语库和键上下文

在 Phrase Strings 中，打开 **Term bases**，然后选择 **More &gt; Download CSV**，选择所需字段，再点击 **Download**。该文件包含 `term`、`case_sensitive`、`translatable` 和 `description` 列，每个区域设置另占一列。 (参见 [Uploading and downloading terms](https://support.phrase.com/hc/en-us/articles/10112307427740)。) 将 `description` 重命名为 `definition`，将每个区域设置列 (例如 `de`) 重命名为 `translation_de`，并删除 `case_sensitive` 和 `translatable` 列。General Translation 的导入工具可直接读取这种布局，其他布局则由 AI 解析。在仪表板中创建一个[上下文分组](/docs/platform/dashboard/guides/defining-context-for-translations)，点击 **Import**，选择该文件，并在首次运行翻译之前将该组分配给你的项目，让新译文从一开始就使用你的术语。

键描述和字符数限制能让译者了解字符串的含义及允许的长度。为源区域设置添加第二个拉取目标，设置 `file_format: strings_json`，并将其保存在 `gt.config.json` 所配置的文件夹之外 (例如 `./phrase-export/app.strings.json`) 。该文件包含每个键的 `description` 和 `max_characters_allowed`；请将它们写入源文件旁的[键级元数据](/docs/cli/reference/keyed-metadata)文件中：

```json title="locales/en/app.metadata.json"
{
  "checkout": {
    "save": { "context": "Button that saves the shipping address", "maxChars": 12 }
  }
}
```

将你的风格指南重新创建为[自定义提示词](/docs/platform/dashboard/guides/defining-context-for-translations)。如需存档翻译记忆库，请将项目中的每种语言分别下载为 TMX 文件。

## 第 5 步：先上传，再翻译

先运行 [`npx gt upload`](/docs/cli/reference/commands/upload)。该命令会上传每个源文件，以及各区域设置下对应的翻译后的文件，并将这些译文存储为已完成状态：

```bash
npx gt upload
npx gt translate
```

随后，[`npx gt translate`](/docs/cli/reference/commands/translate) 只会翻译缺失的内容 (例如新增的区域设置或尚无译文的文件) ，并将结果写入相同的路径。如果在 [`npx gt upload`](/docs/cli/reference/commands/upload) 之前运行 [`npx gt translate`](/docs/cli/reference/commands/translate)，新生成的译文会覆盖已拉取的文件。对于 Phrase 中尚未翻译的键，General Translation 会在其源文件下次变更时进行翻译。如需尽早发布这些译文，请先在 Phrase 中完成翻译，再执行拉取。

## 第 6 步：自动翻译新文案

此后，在你的[构建或 CI](/kb/translations-in-ci) 流程中运行 [`npx gt translate`](/docs/cli/reference/commands/translate)，或者让 [Locadex](/docs/platform/locadex/quickstart) 自动创建包含译文的拉取请求。请将 `gt-lock.json` 提交到代码仓库：该文件记录了 CLI 已写入的译文，避免重复下载。如果你的团队会直接在代码仓库中编辑翻译后的文件，请在下一次翻译前运行 [`npx gt save-local`](/docs/cli/reference/commands/save-local)，以免这些修改被覆盖。

## 什么情况下应继续使用 Phrase？

如果你需要用同一个平台同时管理软件字符串和 Phrase TMS 中的文档翻译项目、原生移动应用依赖 OTA 更新、你通过 Phrase 采购人工翻译服务，或者你的流水线需要交换 XLIFF 或 ARB 文件，那么继续使用 Phrase 是更合适的选择。 (参见 [General Translation 与 Phrase 对比](/kb/general-translation-vs-phrase)。)

## 常见问题

### 我已验证的译文会丢失吗？

不会，只要拉取时不包含后备内容，并在运行 [`npx gt translate`](/docs/cli/reference/commands/translate) 之前先运行 [`npx gt upload`](/docs/cli/reference/commands/upload)。已上传的译文会一直保留，直到对应的源文本发生变化；你的团队也可以随时在[仪表板](/docs/platform/dashboard/guides/reviewing-translations)中修正任何译文。

## 要点总结

* 为每个区域设置拉取一个文件，设置 `include_empty_translations: false`，不使用回退区域设置，并采用应用当前读取的格式。
* 在 General Translation 写入相同文件之前，先停用 Repo Sync 和 OTA。
* 翻译之前，先将 Phrase 的区域设置名称与 `gt.config.json` 中的 `locales` 对应，将术语库导入上下文分组，并将键的描述和字符数限制迁移为每个键的上下文。
* 首次运行 [`npx gt translate`](/docs/cli/reference/commands/translate) 之前，先运行 [`npx gt upload`](/docs/cli/reference/commands/upload)；此后可在构建过程中或通过 Locadex 翻译新增文案。

## Related questions

- [Phrase 替代方案：General Translation 与 Phrase 对比](https://generaltranslation.com/zh/kb/general-translation-vs-phrase.mdx): 如果你的应用和文档一起发布，General Translation 是 Phrase Strings 的有力替代方案。它基于代码和内容文件生成译文，统一应用共享术语，并直接在你的发布工作流中运行。Phrase 则将软件本地化与以文档为中心的 TMS、供应商管理以及丰富的翻译引擎选择融为一体。
- [如何从 Lokalise 迁移到 General Translation？](https://generaltranslation.com/zh/kb/migrate-from-lokalise.mdx): 你的资源文件、国际化库和已审校的译文都可以保留。从 Lokalise 导出时跳过空译文，关闭其 GitHub 同步，并在首次运行 npx gt translate 之前，用 npx gt upload 导入这些文件。此后，General Translation 会在构建时翻译新增和变更的字符串，你的词汇表放在上下文分组中，键描述则作为各个键的上下文。
- [如何从 Crowdin 迁移到 General Translation？](https://generaltranslation.com/zh/kb/migrate-from-crowdin.mdx): 保留现有的资源文件、国际化库和已审校的译文。开启 Skip untranslated strings，下载译文，停止 Crowdin 的 Git 集成推送译文，并在首次运行 npx gt translate 之前，使用 npx gt upload 导入这些文件。之后，General Translation 会在构建过程中翻译新增和变更的字符串，并使用 上下文分组 中的词汇表。
- [如何在每次部署时保持译文同步更新？](https://generaltranslation.com/zh/kb/translations-in-ci.mdx): 在每次生产环境构建之前，将翻译作为流水线中的一个步骤运行，这样新增文案就会在引入它的那次部署中以翻译好的形式一同上线。General Translation 的 gt CLI 通过 npx gt translate 实现这一点，所需的项目 API 密钥和项目 ID 以 CI 密钥的形式存储。
- [什么是翻译记忆库？有了 AI 还需要它吗？](https://generaltranslation.com/zh/kb/what-is-translation-memory.mdx): 翻译记忆库（TM）是一个存储既往源文与译文片段对的数据库，翻译工具会在其中查找完全匹配、上下文匹配和模糊匹配。即便使用 AI，你仍然需要复用已批准的措辞，并将过往译文作为上下文。General Translation 会复用早期文件版本中匹配的译文并保留团队所做的修改，无需另外维护一套 TM。

## Previous and next questions

- Previous question: [如何从 Lokalise 迁移到 General Translation？](https://generaltranslation.com/zh/kb/migrate-from-lokalise.mdx)
- Next question: [对于每天都要发布的团队，哪款持续本地化工具最合适？](https://generaltranslation.com/zh/kb/best-continuous-localization-tools.mdx)

## Sitemap

See the [Knowledge Base sitemap](https://generaltranslation.com/zh/kb/sitemap.md) for every article.