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

## 什么是本地翻译？

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

有两种方式可以实现：

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

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

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

## 权衡

### 本地翻译的优势

* **加载更快**：本地翻译直接由你的应用提供，加载速度比通过 CDN 提供的翻译更快
* **不依赖外部服务**：应用能否加载翻译不取决于 CDN 是否可用。若某个区域设置没有对应翻译，应用会自动回退到默认语言
* **支持离线使用**：翻译会随应用一同打包

### 本地翻译的缺点

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

## 设置

### 步骤 1：创建 loadTranslations 函数

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

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

[`withGTConfig`](/docs/next/api/config/with-gt-config) 会自动从你的 `src/` 目录或项目根目录读取 `loadTranslations.[js|ts]` 文件。


### 第 2 步：配置 CLI

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

```bash
npx gt configure
```

出现提示后：

* **保存到 CDN？** 选择 &quot;No&quot;
* **翻译目录：** 输入 `./public/_gt`

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


### 第 3 步：生成翻译

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

```bash
npx gt translate
```

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


## 构建集成

### Next.js 构建流程

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

```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...>
```


### 导入路径错误

确保 loadTranslations 函数与你的目录结构一致：

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

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


### 包体积过大

对于支持多种语言的应用，建议考虑进行代码拆分：

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

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


## 后续步骤

* [中间件指南](/docs/next/guides/middleware) - 语言检测与路由
* [语言指南](/docs/next/guides/languages) - 配置支持的语言
* API 参考：