GitHub

什么是本地翻译？

本地翻译存放在应用的 bundle 中，而不是在运行时从 CDN（Content Delivery Network，内容分发网络）获取。将 gtx-cli translate 命令加入构建流程后，会生成 JSON 格式的翻译文件。最后一步是把这些翻译集成到你的应用中以便使用。

有两种方式：

存于应用 bundle 中（本地）：生成后将翻译保存到应用的 bundle
存于 CDN（默认）：在运行时从 CDN 获取翻译

默认情况下，gt-next 会从 General Translation 的翻译 CDN 获取翻译。使用我们的 API 为应用进行翻译时，翻译会自动保存到我们的 CDN。

默认行为： GT 默认使用 CDN 存储。仅在需要其特定优势时再切换到本地存储。

取舍权衡

本地翻译的优势

加载更快：本地翻译直接由应用提供，通常比通过 CDN（内容分发网络）加载更快
不依赖外部服务：应用加载翻译不受 CDN 可用性的影响。若某个 locale 没有找到对应翻译，应用会自动回退到默认语言
可离线工作：翻译随应用一起打包

本地翻译的缺点

更大的 bundle 体积：本地翻译会增加应用的 bundle 体积，可能导致应用的首屏加载变慢
内容管理：每次修改翻译后，都必须重新部署应用才能包含最新的翻译

安装与设置

步骤 1：创建加载函数

在 ./src 目录下添加一个 loadTranslations.[js|ts] 文件，内容如下：

src/loadTranslations.ts

export default async function loadTranslations(locale: string) {
  const translations = await import(`../public/_gt/${locale}.json`);
  return translations.default;
}

withGTConfig 会自动从你的 src/ 目录或项目根目录中检测并使用 loadTranslations.[js|ts] 文件。

步骤 2：配置 CLI

运行配置命令并选择本地存储：

npx gtx-cli configure

出现提示时：

保存到 CDN？ 选择“否”
翻译目录： 输入 ./public/_gt

或者，你也可以手动配置 gt.config.json 文件以使用本地翻译。更多信息请参阅 CLI 配置文档。

步骤 3：生成翻译

现在，当你运行 translate 命令时，翻译会自动下载并添加到你的代码库中：

npx gtx-cli translate

翻译将存放在 public/_gt/ 中，并随您的应用一起打包。

构建集成

Next.js 构建流程

在构建脚本中加入翻译生成步骤：

{
  "scripts": {
    "build": "npx gtx-cli translate && <...您的构建命令...>"
  }
}

CI/CD 管道

# .github/workflows/deploy.yml
- name: 生成翻译
  run: npx gtx-cli translate
  
- name: 构建应用程序  
  run: npm run build

常见问题

缺少翻译文件

请在构建前先生成翻译：

# ❌ 不生成翻译直接构建
<...YOUR_BUILD_COMMAND...>

# ✅ 先生成翻译
npx gtx-cli translate && <...YOUR_BUILD_COMMAND...>

导入路径错误

在 load 函数中确保与目录结构一致：

// ❌ 错误路径
const t = await import(`../translations/${locale}.json`);

// ✅ public/_gt 的正确路径
const t = await import(`../public/_gt/${locale}.json`);

包体过大

对于支持多语言的应用，建议使用代码拆分：

// 仅在需要时加载翻译
export default async function loadTranslations(locale: string) {
  // 仅在 locale 处于活动状态时加载
  if (locale === getCurrentLocale()) {
    const translations = await import(`../public/_gt/${locale}.json`);
    return translations.default;
  }
  return {};
}

本地存储更适合翻译内容稳定、无需频繁更新的应用。

后续步骤

Middleware 指南 - 语言检测与路由
语言配置指南 - 配置支持语言
API 参考：

什么是本地翻译？

有两种方式：

存于应用 bundle 中（本地）：生成后将翻译保存到应用的 bundle
存于 CDN（默认）：在运行时从 CDN 获取翻译

默认情况下，gt-next 会从 General Translation 的翻译 CDN 获取翻译。使用我们的 API 为应用进行翻译时，翻译会自动保存到我们的 CDN。

默认行为： GT 默认使用 CDN 存储。仅在需要其特定优势时再切换到本地存储。

取舍权衡

本地翻译的优势

加载更快：本地翻译直接由应用提供，通常比通过 CDN（内容分发网络）加载更快
不依赖外部服务：应用加载翻译不受 CDN 可用性的影响。若某个 locale 没有找到对应翻译，应用会自动回退到默认语言
可离线工作：翻译随应用一起打包

本地翻译的缺点

更大的 bundle 体积：本地翻译会增加应用的 bundle 体积，可能导致应用的首屏加载变慢
内容管理：每次修改翻译后，都必须重新部署应用才能包含最新的翻译

安装与设置

步骤 1：创建加载函数

在 ./src 目录下添加一个 loadTranslations.[js|ts] 文件，内容如下：

src/loadTranslations.ts

export default async function loadTranslations(locale: string) {
  const translations = await import(`../public/_gt/${locale}.json`);
  return translations.default;
}

withGTConfig 会自动从你的 src/ 目录或项目根目录中检测并使用 loadTranslations.[js|ts] 文件。

步骤 2：配置 CLI

运行配置命令并选择本地存储：

npx gtx-cli configure

出现提示时：

保存到 CDN？ 选择“否”
翻译目录： 输入 ./public/_gt

或者，你也可以手动配置 gt.config.json 文件以使用本地翻译。更多信息请参阅 CLI 配置文档。

步骤 3：生成翻译

现在，当你运行 translate 命令时，翻译会自动下载并添加到你的代码库中：

npx gtx-cli translate

翻译将存放在 public/_gt/ 中，并随您的应用一起打包。

构建集成

Next.js 构建流程

在构建脚本中加入翻译生成步骤：

{
  "scripts": {
    "build": "npx gtx-cli translate && <...您的构建命令...>"
  }
}

CI/CD 管道

# .github/workflows/deploy.yml
- name: 生成翻译
  run: npx gtx-cli translate
  
- name: 构建应用程序  
  run: npm run build

常见问题

缺少翻译文件

请在构建前先生成翻译：

# ❌ 不生成翻译直接构建
<...YOUR_BUILD_COMMAND...>

# ✅ 先生成翻译
npx gtx-cli translate && <...YOUR_BUILD_COMMAND...>

导入路径错误

在 load 函数中确保与目录结构一致：

// ❌ 错误路径
const t = await import(`../translations/${locale}.json`);

// ✅ public/_gt 的正确路径
const t = await import(`../public/_gt/${locale}.json`);

包体过大

对于支持多语言的应用，建议使用代码拆分：

// 仅在需要时加载翻译
export default async function loadTranslations(locale: string) {
  // 仅在 locale 处于活动状态时加载
  if (locale === getCurrentLocale()) {
    const translations = await import(`../public/_gt/${locale}.json`);
    return translations.default;
  }
  return {};
}

本地存储更适合翻译内容稳定、无需频繁更新的应用。

后续步骤

Middleware 指南 - 语言检测与路由
语言配置指南 - 配置支持语言
API 参考：

什么是本地翻译？

有两种方式：

存于应用 bundle 中（本地）：生成后将翻译保存到应用的 bundle
存于 CDN（默认）：在运行时从 CDN 获取翻译

默认情况下，gt-next 会从 General Translation 的翻译 CDN 获取翻译。使用我们的 API 为应用进行翻译时，翻译会自动保存到我们的 CDN。

默认行为： GT 默认使用 CDN 存储。仅在需要其特定优势时再切换到本地存储。

取舍权衡

本地翻译的优势

加载更快：本地翻译直接由应用提供，通常比通过 CDN（内容分发网络）加载更快
不依赖外部服务：应用加载翻译不受 CDN 可用性的影响。若某个 locale 没有找到对应翻译，应用会自动回退到默认语言
可离线工作：翻译随应用一起打包

本地翻译的缺点

更大的 bundle 体积：本地翻译会增加应用的 bundle 体积，可能导致应用的首屏加载变慢
内容管理：每次修改翻译后，都必须重新部署应用才能包含最新的翻译

安装与设置

步骤 1：创建加载函数

在 ./src 目录下添加一个 loadTranslations.[js|ts] 文件，内容如下：

src/loadTranslations.ts

export default async function loadTranslations(locale: string) {
  const translations = await import(`../public/_gt/${locale}.json`);
  return translations.default;
}

withGTConfig 会自动从你的 src/ 目录或项目根目录中检测并使用 loadTranslations.[js|ts] 文件。

步骤 2：配置 CLI

运行配置命令并选择本地存储：

npx gtx-cli configure

出现提示时：

保存到 CDN？ 选择“否”
翻译目录： 输入 ./public/_gt

或者，你也可以手动配置 gt.config.json 文件以使用本地翻译。更多信息请参阅 CLI 配置文档。

步骤 3：生成翻译

现在，当你运行 translate 命令时，翻译会自动下载并添加到你的代码库中：

npx gtx-cli translate

翻译将存放在 public/_gt/ 中，并随您的应用一起打包。

构建集成

Next.js 构建流程

在构建脚本中加入翻译生成步骤：

{
  "scripts": {
    "build": "npx gtx-cli translate && <...您的构建命令...>"
  }
}

CI/CD 管道

# .github/workflows/deploy.yml
- name: 生成翻译
  run: npx gtx-cli translate
  
- name: 构建应用程序  
  run: npm run build

常见问题

缺少翻译文件

请在构建前先生成翻译：

# ❌ 不生成翻译直接构建
<...YOUR_BUILD_COMMAND...>

# ✅ 先生成翻译
npx gtx-cli translate && <...YOUR_BUILD_COMMAND...>

导入路径错误

在 load 函数中确保与目录结构一致：

// ❌ 错误路径
const t = await import(`../translations/${locale}.json`);

// ✅ public/_gt 的正确路径
const t = await import(`../public/_gt/${locale}.json`);

包体过大

对于支持多语言的应用，建议使用代码拆分：

// 仅在需要时加载翻译
export default async function loadTranslations(locale: string) {
  // 仅在 locale 处于活动状态时加载
  if (locale === getCurrentLocale()) {
    const translations = await import(`../public/_gt/${locale}.json`);
    return translations.default;
  }
  return {};
}

本地存储更适合翻译内容稳定、无需频繁更新的应用。

后续步骤

Middleware 指南 - 语言检测与路由
语言配置指南 - 配置支持语言
API 参考：

本地翻译存储

本页内容

本地翻译存储

本页内容

本地翻译存储

本页内容

GitHub在 GitHub 上加星

GitHub在 GitHub 上加星

在 GitHub 上加星

在 GitHub 上加星