# gt-react: General Translation React SDK: 本地翻译存储
URL: https://generaltranslation.com/zh/docs/react/guides/local-tx.mdx
---
title: 本地翻译存储
description: 将翻译存储在应用 bundle 中，而不是通过 CDN 提供
---

{/* 自动生成：请勿直接编辑。请改为编辑 content/docs-templates/ 中的模板。 */}


## 什么是本地翻译？

本地翻译存储在应用的 bundle 中，而不是从 CDN (内容分发网络) 拉取。当你将 `gt translate` 命令加入构建流程后，它会生成 JSON 格式的翻译文件。最后一步，就是将这些翻译集成到应用中，以便实际使用。

有两种实现方式：

1. **放在应用的 bundle 中** (本地) ：生成后将翻译保存到应用的 bundle 中
2. **放在 CDN 中** (默认) ：在 runtime 时从 CDN 拉取翻译

默认情况下，`gt-react` 会从 General Translation 的 CDN 拉取翻译。使用我们的 API 翻译应用时，翻译也会自动保存到我们的 CDN。

<Callout>
  **默认行为：** GT 默认使用 CDN 存储。只有在你确实需要本地存储所带来的特定优势时，才应切换到本地存储。
</Callout>

## 权衡

### 本地翻译的优势

* **加载更快**：本地翻译直接由你的应用提供，加载速度比通过 CDN 提供的翻译更快
* **不依赖外部服务**：应用加载翻译不受 CDN 可用性的影响。如果某个区域设置找不到对应翻译，应用会自动回退到默认语言
* **可离线使用**：翻译会随应用一同打包

### 本地翻译的缺点

* **Bundle 体积增大**：本地翻译会增大应用的 bundle 体积，可能导致应用初次加载变慢
* **内容管理**：要修改翻译内容，你每次更改后都必须重新部署应用以更新翻译

## 设置

### 第 1 步：创建加载函数

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

```ts title="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>`](/docs/react/api/components/gtprovider) 组件：

```tsx title="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

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

```bash
npx gt configure
```

出现提示时：

* **保存到 CDN？** 选择 &quot;No&quot;
* **翻译目录：** CLI 会自动使用 `./src/_gt`

或者，你也可以手动配置 `gt.config.json` 文件以使用本地翻译。更多信息请参阅 [CLI 配置文档](/docs/cli/reference/config)。


### 第 4 步：生成翻译

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

```bash
npx gt translate
```

翻译内容会存储在 `src/_gt/` 中，并随应用一同打包。


## 构建集成

### React 构建流程

将翻译生成功能添加到构建脚本中：

```json
{
  "scripts": {
    "build": "npx gt translate && <...YOUR_BUILD_COMMAND...>"
  }
}
```


### CI/CD 流程

```yaml
# .github/workflows/deploy.yml
- name: Generate Translations
  run: npx gt translate
  
- name: Build Application  
  run: npm run build
```


## 常见问题

### 翻译文件缺失

请确保在构建前已生成翻译：

```bash
# ❌ 构建时未生成翻译
<...YOUR_BUILD_COMMAND...>

# ✅ 先生成翻译
npx gt translate && <...YOUR_BUILD_COMMAND...>
```


### 导入路径错误

在 `加载` 函数中让路径与目录结构保持一致：

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

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


### bundle 体积过大

如果应用支持多种语言，可考虑进行代码拆分：

```ts
// 仅在需要时加载翻译
export default async function loadTranslations(locale: string) {
  // 仅在区域设置激活时加载
  if (locale === getCurrentLocale()) {
    const translations = await import(`./_gt/${locale}.json`);
    return translations.default;
  }
  return {};
}
```

<Callout>
  对于翻译内容稳定且无需频繁更新的应用，本地存储效果最佳。
</Callout>


## 后续步骤

* [语言指南](/docs/react/guides/languages) - 配置受支持的语言