GitHub

什么是本地翻译？

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

有两种实现方式：

随应用打包（本地）：在生成后将翻译保存进应用的 bundle
存放于 CDN（默认）：在运行时从 CDN 拉取翻译

默认情况下，gt-react 会从 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 t = await import(`./_gt/${locale}.json`);
  return t.default;
}

步骤 2：配置 GTProvider

将 loadTranslations 作为 prop 传入 <GTProvider> 组件：

src/App.tsx

import { GTProvider } from 'gt-react';
import loadTranslations from './loadTranslations';

export default function App() {
  return (
    <GTProvider loadTranslations={loadTranslations} locales={['es', 'fr']}>
      <YourApp />
    </GTProvider>
  );
}

步骤 3：配置 CLI

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

npx gtx-cli configure

当出现提示时：

保存到 CDN？ 选择“否”
Translation directory: CLI 将自动使用 ./src/_gt

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

步骤 4：生成翻译

现在，当你运行 translate 命令时，系统会自动下载翻译并将其包含到你的代码库中：

npx gtx-cli translate

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

构建集成

React 构建流程

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

{
  "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`);

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

Bundle 体积过大

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

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

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

下一步

语言指南 - 配置支持的语言

什么是本地翻译？

有两种实现方式：

随应用打包（本地）：在生成后将翻译保存进应用的 bundle
存放于 CDN（默认）：在运行时从 CDN 拉取翻译

默认情况下，gt-react 会从 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 t = await import(`./_gt/${locale}.json`);
  return t.default;
}

步骤 2：配置 GTProvider

将 loadTranslations 作为 prop 传入 <GTProvider> 组件：

src/App.tsx

import { GTProvider } from 'gt-react';
import loadTranslations from './loadTranslations';

export default function App() {
  return (
    <GTProvider loadTranslations={loadTranslations} locales={['es', 'fr']}>
      <YourApp />
    </GTProvider>
  );
}

步骤 3：配置 CLI

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

npx gtx-cli configure

当出现提示时：

保存到 CDN？ 选择“否”
Translation directory: CLI 将自动使用 ./src/_gt

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

步骤 4：生成翻译

现在，当你运行 translate 命令时，系统会自动下载翻译并将其包含到你的代码库中：

npx gtx-cli translate

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

构建集成

React 构建流程

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

{
  "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`);

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

Bundle 体积过大

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

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

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

下一步

语言指南 - 配置支持的语言

什么是本地翻译？

有两种实现方式：

随应用打包（本地）：在生成后将翻译保存进应用的 bundle
存放于 CDN（默认）：在运行时从 CDN 拉取翻译

默认情况下，gt-react 会从 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 t = await import(`./_gt/${locale}.json`);
  return t.default;
}

步骤 2：配置 GTProvider

将 loadTranslations 作为 prop 传入 <GTProvider> 组件：

src/App.tsx

import { GTProvider } from 'gt-react';
import loadTranslations from './loadTranslations';

export default function App() {
  return (
    <GTProvider loadTranslations={loadTranslations} locales={['es', 'fr']}>
      <YourApp />
    </GTProvider>
  );
}

步骤 3：配置 CLI

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

npx gtx-cli configure

当出现提示时：

保存到 CDN？ 选择“否”
Translation directory: CLI 将自动使用 ./src/_gt

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

步骤 4：生成翻译

现在，当你运行 translate 命令时，系统会自动下载翻译并将其包含到你的代码库中：

npx gtx-cli translate

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

构建集成

React 构建流程

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

{
  "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`);

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

Bundle 体积过大

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

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

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

下一步

语言指南 - 配置支持的语言

本地翻译存储

本页内容

本地翻译存储

本页内容

本地翻译存储

本页内容

GitHub在 GitHub 上加星

GitHub在 GitHub 上加星

在 GitHub 上加星

在 GitHub 上加星