# General Translation React SDKs (gt-react, gt-next, gt-react-native): 配置 esbuild SPA
URL: https://generaltranslation.com/zh/docs/react/guides/spa/configuring-esbuild-spa.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: 如何在由 esbuild 驱动的单页 React 应用中配置 gt-react。

配置应用程序运行时，并可选择将生成的翻译目录与 esbuild 构建一起打包。

本指南用于准备应用程序运行时。请单独标记需要翻译的面向用户内容。

## React esbuild SPA 设置 [#setup]

在应用入口文件运行之前初始化 `gt-react`。

### 1. 安装 gt-react

请使用 repository 首选的包管理器安装最新版本的 `gt-react`。如果已安装，请跳过此步骤。

### 2. 在项目根目录添加 `gt.config.json` 文件

在项目根目录添加 `gt.config.json` 文件。此文件包含 `gt-react` 包的配置。

以项目中已有的区域设置或提供给设置任务的区域设置为准。保留任何现有的 `locales` 和 `defaultLocale` 值。以下值仅作示例。如果项目没有区域设置配置，请勿根据这些示例推断区域设置要求。

```json title="gt.config.json"
{
  "defaultLocale": "en",
  "locales": ["fr", "de"]
}
```

可选的 [`src`](/docs/cli/reference/config#src) 字段用于指定 GT 扫描内联内容的源文件；省略时，默认使用 `src`、`app`、`pages` 和 `components` 下的以下 JavaScript 和 TypeScript glob 模式：

```json title="gt.config.json"
{
  "defaultLocale": "en",
  "locales": ["fr", "de"],
  "src": [
    "src/**/*.{js,jsx,ts,tsx}",
    "app/**/*.{js,jsx,ts,tsx}",
    "pages/**/*.{js,jsx,ts,tsx}",
    "components/**/*.{js,jsx,ts,tsx}"
  ]
}
```

### 3. 初始化库

在应用渲染或导入使用模块级翻译函数的模块之前，使用 [`initializeGTSPA`](/docs/react/reference/config#initialize-spa) 初始化库。

在应用现有入口文件旁创建一个引导文件。本示例中，原入口文件为 `src/main.tsx`，新引导文件为 `src/index.ts`。将 esbuild 现有的 `entryPoints` 配置指向该引导文件。保留所有其他构建设置。

```js title="esbuild.config.mjs"
const buildOptions = {
  // ...项目已有的选项
  entryPoints: ['src/index.ts'],
};
```

如果开发用 HTML 直接引用原始源条目，也请一并更新：

```html title="index.html"
<!-- <script type="module" src="/src/main.tsx"></script> -->
<script type="module" src="/src/index.ts"></script>
```

然后初始化 GT，并仅在初始化完成后动态导入入口文件。esbuild 参考应用会生成 ESM，并支持顶层 await：

```ts title="src/index.ts"
import { initializeGTSPA } from 'gt-react';
import gtConfig from '../gt.config.json';

await initializeGTSPA(gtConfig);

await import('./main'); // 仅在 GT 已就绪后再渲染应用
```

如果现有的 esbuild 输出目标不支持顶层 await，请勿仅为此设置更改应用程序的输出格式。请改用异步引导函数：

```ts title="src/index.ts"
import { initializeGTSPA } from 'gt-react';
import gtConfig from '../gt.config.json';

async function bootstrap() {
  await initializeGTSPA(gtConfig);
  await import('./main');
}

void bootstrap();
```

## 加载翻译 [#translations]

当调用 [`initializeGTSPA`](/docs/react/reference/config#initialize-spa) 时未提供 [`loadTranslations`](/docs/react/reference/functions/load-translations) 函数，运行时仅在有可用的 [`projectId`](/docs/react/reference/config#project-id) 时才从 General Translation CDN 加载翻译。若要将翻译目录打包到应用 bundle 中，请配置输出路径及相应的加载器。以下步骤使用 `src/_gt/[locale].json`。

### 1. 更新配置

将 `files.gt.output` 设置为 CLI 应写入生成的翻译文件的位置。

仅添加或合并 `files.gt.output` 设置。保留项目现有的 `locales` 和 `defaultLocale`；下方所示的值仅为示例，不得替换项目中已配置的区域设置。

通常，在由 esbuild 驱动的应用中，翻译文件会存储在 `src/_gt` 目录中。这样 esbuild 就能将翻译模块打包到应用程序 bundle 中。

```json title="gt.config.json"
{
  "locales": ["fr", "zh"],
  "defaultLocale": "en",
  "files": {
    "gt": {
      "output": "src/_gt/[locale].json"
    }
  }
}
```

### 2. 添加存根文件

请为 `gt.config.json` 中已配置的每个目标区域设置创建一个空的 JSON 文件，但不包括默认区域设置。这些存根文件可让 `import` 在翻译包存在之前完成解析。下方的 `fr` 和 `zh` 文件仅用于说明本指南中的示例配置；请根据项目实际配置的目标区域设置创建相应文件。如果未配置目标区域设置，请勿自行添加区域设置或创建占位符文件。

<Files>
  <Folder name="src">
    <Folder name="_gt">
      <File name="fr.json" />

      <File name="zh.json" />
    </Folder>
  </Folder>
</Files>

```json title="src/_gt/fr.json"
{}
```

```json title="src/_gt/zh.json"
{}
```

### 3. 添加加载器

创建 `src/loadTranslations.ts` 以加载翻译。它必须解析为与 `files.gt.output` 中配置的输出位置相同的位置。

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

### 4. 更新初始化器

更新初始化器以使用新的加载器函数。保留应用当前使用的顶层 await 或异步函数引导形式。

```ts title="src/index.ts"
import { initializeGTSPA } from 'gt-react';
import gtConfig from '../gt.config.json';
import loadTranslations from './loadTranslations';

await initializeGTSPA({ ...gtConfig, loadTranslations });

await import('./main');
```

## Next steps

- /docs/react/guides/spa/internationalizing-react-spa
- /docs/react/guides/developing-spa-translations
- /docs/react/guides/storing-translations
- /docs/react/guides/managing-locales

## Sitemap

See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.