# react-native: 本地翻译存储
URL: https://generaltranslation.com/zh/docs/react-native/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-native` 会从 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` 作为属性传递给 [`<GTProvider>`](/docs/react-native/api/components/gtprovider) 组件：

```tsx title="src/App.tsx"
import { GTProvider } from 'gt-react-native';
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...>
```


### 导入路径错误

在 `load` 函数中使用与你的目录结构一致的路径：

```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-native/guides/languages) - 配置支持的语言