# node: 本地译文存储
URL: https://generaltranslation.com/zh/docs/node/guides/local-tx.mdx
---
title: 本地译文存储
description: 将译文存储在应用 bundle 中，而不是从 CDN 获取
---

## 什么是本地译文？

默认情况下，`gt-node` 会在 runtime 从 General Translation CDN 拉取译文。启用本地译文后，你可以将翻译文件直接 bundle 到应用中，无需发起任何外部请求。

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

## 权衡取舍

### 本地译文的优势

* **响应更快**：无需在 runtime 发起网络请求来获取译文
* **不依赖外部服务**：即使 CDN 不可用，你的应用也能独立运行
* **支持离线使用**：译文是 deployment 产物的一部分

### 本地译文的缺点

* **bundle 体积增加**：每增加一个受支持的区域设置，都会增大 deployment 体积
* **更新时需要重新部署**：修改译文后需要重新进行一次 deployment

## 设置

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

编写一个加载函数，根据区域设置加载翻译 JSON 文件：

```js title="loadTranslations.js"
import { readFile } from 'fs/promises';
import path from 'path';

export default async function loadTranslations(locale) {
  const filePath = path.join(process.cwd(), 'translations', `${locale}.json`);
  const data = await readFile(filePath, 'utf-8');
  return JSON.parse(data);
}
```


### 第 2 步：将其传给 `initializeGT`

```js title="server.js"
import { initializeGT } from 'gt-node';
import loadTranslations from './loadTranslations.js';

initializeGT({
  defaultLocale: 'en',
  locales: ['en', 'es', 'fr', 'ja'],
  projectId: process.env.GT_PROJECT_ID,
  loadTranslations,
});
```


### 第 3 步：配置 CLI

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

```bash
npx gt configure
```

出现提示后：

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


### 第 4 步：生成译文

```bash
npx gt translate
```

这会将翻译文件下载到 `translations/` 目录中。


## 集成到 build 流程中

将译文生成添加到 build 脚本中，确保译文始终保持最新：

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


### CI/CD 处理流水线

```yaml title=".github/workflows/deploy.yml"
- name: Generate Translations
  run: npx gt translate

- name: Build Application
  run: npm run build
```


## 常见问题

### 缺少翻译文件

请始终在 build 前先生成译文：

```bash
# ❌ 构建时未生成译文
node server.js

# ✅ 先生成译文
npx gt translate && node server.js
```


### 文件路径错误

确保加载函数中的路径与 CLI 的输出目录一致：

```js
// ❌ 路径错误
const filePath = path.join(process.cwd(), 'public', `${locale}.json`);

// ✅ 与您配置的目录匹配
const filePath = path.join(process.cwd(), 'translations', `${locale}.json`);
```

<Callout>
  本地存储更适合译文较为稳定、无需频繁更新的应用。
</Callout>


## 下一步

* [CLI `translate` 命令](/docs/cli/translate) — 翻译生成参考文档
* [CLI 配置](/docs/cli/reference/config) — 配置输出目录和存储模式
* [字符串翻译模式](/docs/node/guides/strings) — 了解如何翻译内容