# General Translation Knowledge Base: 如何从 Lokalise 迁移到 General Translation？
URL: https://generaltranslation.com/zh/kb/migrate-from-lokalise.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: 你的资源文件、国际化库和已审校的译文都可以保留。从 Lokalise 导出时跳过空译文，关闭其 GitHub 同步，并在首次运行 npx gt translate 之前，用 npx gt upload 导入这些文件。此后，General Translation 会在构建时翻译新增和变更的字符串，你的词汇表放在上下文分组中，键描述则作为各个键的上下文。
Category: 工作流工具
Last updated: 2026-11-12
Authors: Kevin Wu
Published: 2026-11-12

Lokalise 将你的字符串以键的形式存储在项目中，导出时为各个平台生成资源文件，并与你的代码仓库同步。迁移到 General Translation 后，应用现在读取的资源文件可以继续沿用：`gt` CLI 会连同现有译文一并导入这些文件，然后在构建或 CI 中翻译新增和变更的字符串。你的国际化库和键都无需改动；将文案改为内联是一个独立的可选步骤 (参见[从 react-i18next 迁移](/kb/migrate-from-react-i18next)或[从 next-intl 迁移](/kb/migrate-from-next-intl)) 。你的词汇表会成为一个上下文分组，可在你的应用、文档和其他项目之间共享。

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

| 在 Lokalise 中                               | 在 General Translation 中                                                                                                     |
| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------- |
| 按平台导出为文件的键                                 | 同样的文件，列在 `gt.config.json` 的 `files` 下                                                                                       |
| 译文                                         | 通过 [`npx gt upload`](/docs/cli/reference/commands/upload) 导入，并一直保留，直到对应的源内容发生变化                                             |
| 词汇表                                        | [上下文分组](/docs/platform/dashboard/guides/defining-context-for-translations)中的词汇表，可从 CSV 导入                                   |
| Pro AI 的风格指南                               | [自定义提示词](/docs/platform/dashboard/guides/defining-context-for-translations)，可全局设置，也可按区域设置单独设置                               |
| 键描述和字符数限制                                  | iOS 和 Android 文件中的注释 (General Translation 会将其作为上下文读取) ；JSON 和 YAML 则使用[键级元数据](/docs/cli/reference/keyed-metadata)文件         |
| 翻译记忆库                                      | 你上传的译文：未更改的字符串沿用原有译文，仅翻译新增和更改的字符串。不支持导入 TMX 文件                                                                              |
| GitHub app、自动拉取和 GitHub Actions            | 在 CI 中运行 [`npx gt translate`](/docs/cli/reference/commands/translate)，或使用 [Locadex](/docs/platform/locadex/quickstart) 拉取请求 |
| 审校任务                                       | 在[仪表板](/docs/platform/dashboard/guides/reviewing-translations)中编辑，Enterprise 方案还支持批准                                        |
| 适用于 iOS、Android 和 Flutter 的 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：为每种语言导出一个文件

Lokalise 不会保留你的原始文件，而是在每次导出时根据键重新生成文件。如果你的代码仓库中已有 Lokalise 同步过来的文件，请使用相同的设置导出，以确保输出一致，并在导入前将导出结果与代码仓库中的文件进行差异比对。

使用 [`lokalise2` CLI](https://github.com/lokalise/lokalise-cli-2-go/blob/master/docs/lokalise2_file_download.md) 时，Web 应用的 JSON 导出如下所示：

```bash
lokalise2 --token "$LOKALISE_TOKEN" --project-id "$LOKALISE_PROJECT_ID" file download \
  --format json \
  --original-filenames=false \
  --bundle-structure "locales/%LANG_ISO%/common.json" \
  --unzip-to . \
  --export-empty-as skip \
  --filter-data nonhidden \
  --async
```

要顺利完成导入，需要注意以下四项设置：

* **`--export-empty-as skip`。** 默认情况下，Lokalise 会将未翻译的键导出为空字符串，而 `base` 则会用源文本填充这些键。无论哪种情况，这些内容都会被当作译文导入。`skip` 会将它们排除在外。
* **复数形式和占位符格式。** 应与你的库所读取的格式保持一致：i18next 的 `_one` 和 `_other` 键使用 `--plural-format i18next_v4`，next-intl 则使用 `--plural-format icu --placeholder-format icu`。 (参见 Lokalise 的[复数形式和占位符格式](https://developers.lokalise.com/reference/api-plurals-and-placeholders)。) 
* **平台。** 每个键属于一个或多个平台，每次导出只包含该格式所属平台上的键。请为每个平台分别执行一次导出：iOS 使用 `--format strings` 和 `stringsdict`，Android 使用 `--format xml`。
* **`--async`。** Lokalise 的同步下载仅适用于键-语言对少于 10,000 个的项目；规模更大的项目需要使用异步下载。

如果不使用 CLI，请打开项目的 **Download** 页面，选择格式，将 **Empty translations** 设为跳过，然后点击 **Build and download**。下载需要具备 **Download files** 贡献者权限。

请检查文件夹名称中的区域设置代码。Lokalise 使用自有的语言代码 (例如 `en_GB`) ，CLI 会将其与你的 `locales` 列表进行精确匹配。你可以在 **Download** 页面上点击代码或通过 `--language-mapping` 来覆盖代码，也可以直接在 `gt.config.json` 中按导出时的形式列出这些代码。

## 第 2 步：停止 Lokalise 的同步

在 General Translation 写入任何文件之前，请关闭所有会向你的代码仓库写入译文的途径：

* 在 GitHub 代码仓库的设置中删除 Lokalise 的自动拉取 Webhook。
* 停止在下载时使用 GitHub 触发器，该触发器会从新分支创建拉取请求。
* 移除或禁用使用了 Lokalise push 和 pull GitHub Actions 的工作流。

GitLab、Bitbucket 和 Azure DevOps 应用的机制与此相同。如果两个工具写入同一批文件，则以最后写入的内容为准。

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

安装 `gt` CLI，并在 `gt.config.json` 中配置导出的文件：

```json title="gt.config.json"
{
  "defaultLocale": "en",
  "locales": ["de", "fr", "pt-BR"],
  "files": {
    "json": { "include": ["locales/[locale]/*.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 密钥，该密钥需具备 **文件 > 写入**、**翻译队列 > 已启用** 和 **上下文 > 写入** 权限。

## 第 4 步：迁移词汇表和键上下文

在 Lokalise 的 [词汇表](https://docs.lokalise.com/en/articles/1400629-glossary) 页面上，使用 **More &gt; Download CSV** 导出所有术语及其译文。该文件以分号分隔，每种语言各占一列，例如 `de_DE`。保留 `term` 列，将 `description` 重命名为 `definition`，将各语言列重命名为 `translation_<locale>` (例如 `translation_de`) ，删除其余列，然后将文件另存为逗号分隔格式。General Translation 的导入工具可直接读取这种布局，其他布局则由 AI 解析。在仪表板中创建一个[上下文分组](/docs/platform/dashboard/guides/defining-context-for-translations)，点击 **Import**，选择该文件，并在首次运行翻译之前将该组分配给你的项目，这样新译文从一开始就会采用你的术语。

键描述用于向译者说明字符串的含义。iOS `.strings` 和 Android `strings.xml` 导出文件默认会以注释形式包含这些描述，General Translation 会将这些注释作为上下文发送。对于 JSON，可以通过 `lokalise2 key list` 获取每个键的描述和字符数限制，也可以导出源语言的 [`json_structured`](https://docs.lokalise.com/en/articles/3229161-structured-json) 文件 (保存在 `gt.config.json` 所配置的文件夹之外) 来获取，然后将这些信息写入源文件旁的[键级元数据](/docs/cli/reference/keyed-metadata)文件：

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

将您的 Pro AI 风格指南重新创建为[自定义提示词](/docs/platform/dashboard/guides/defining-context-for-translations)。如果您的方案包含翻译记忆库管理功能，团队管理员可以在 **Team settings &gt; Translation memory** 中通过 **Download as TMX file** 保存一份存档。

## 第 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)，生成的新译文会覆盖已导出的文件。对于 Lokalise 中尚未翻译的键，General Translation 会在其源文件下次变更时进行翻译。如需尽快发布这些译文，请在导出前先在 Lokalise 中完成翻译。

## 第 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)，以保留这些修改。

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

如果你的原生移动应用依赖 OTA (空中更新) 方式更新字符串，设计师依靠 Figma 插件和截图开展工作，你需要直接在同一工具内订购专业翻译，或者你的流水线需要交换 XLIFF 或 ARB 文件，那么建议继续使用 Lokalise。 (参见 [General Translation 与 Lokalise 对比](/kb/general-translation-vs-lokalise)。)

## 常见问题

### 我审校过的译文会丢失吗？

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

### 截图如何处理？

截图会保留在 Lokalise 中，不会迁移。若要保留截图为译者提供的信息，请在每个键的上下文中说明对应字符串的出现位置 (步骤 4) 。

## 要点总结

* 使用 `--export-empty-as skip` 为每种语言和平台分别导出一个文件，并与应用现有读取的复数格式保持一致。
* 在让 General Translation 写入这些文件之前，先移除 Lokalise 的 Webhook、触发器和 Actions。
* 开始翻译前，先将词汇表导入上下文分组，并将各个键的描述迁移为对应键的上下文。
* 首次运行 [`npx gt translate`](/docs/cli/reference/commands/translate) 之前，先运行 [`npx gt upload`](/docs/cli/reference/commands/upload)；此后可在构建流程中或通过 Locadex 翻译新增文案。

## Related questions

- [Lokalise 替代方案：General Translation 与 Lokalise 对比](https://generaltranslation.com/zh/kb/general-translation-vs-lokalise.mdx): 对于希望在 JSX 中直接编写可读文案、并将翻译融入开发流程的团队来说，General Translation 是 Lokalise 的有力替代方案。Lokalise 的核心是共享键、设计工具集成和移动端 OTA（空中下载）投递。General Translation 根据应用中已标记的内容生成译文，并支持在其仪表板或 GitHub 拉取请求中进行审校。
- [如何从 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 会在构建过程中翻译新增和变更的字符串，并使用 上下文分组 中的词汇表。
- [如何从 Phrase 迁移到 General Translation？](https://generaltranslation.com/zh/kb/migrate-from-phrase.mdx): 保留你的区域设置文件、国际化库和已验证的译文。从 Phrase Strings 拉取文件时排除未翻译的键和后备内容，停用 Repo Sync，并在首次运行 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: [如何从 Crowdin 迁移到 General Translation？](https://generaltranslation.com/zh/kb/migrate-from-crowdin.mdx)
- Next question: [如何从 Phrase 迁移到 General Translation？](https://generaltranslation.com/zh/kb/migrate-from-phrase.mdx)

## Sitemap

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