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

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

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

## React webpack SPA 设置 [#setup]

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

### 1. 安装 gt-react

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

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

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

项目中已有的区域设置，或提供给 setup 任务的区域设置，均应作为依据。保留现有的 `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`。将 webpack 现有的 `entry` 配置指向该引导文件。保留所有其他构建设置及现有的入口对象结构。

```js title="webpack.config.mjs"
export default {
  // ...项目现有的配置项
  entry: './src/index.ts',
};
```

webpack 通常会通过 `HtmlWebpackPlugin` 将构建产物的入口注入 HTML，因此如果项目已使用 HTML 插件，请勿再添加第二个脚本标签。如果 HTML 直接引用原始源入口，请将该引用改为引导文件。

然后初始化 GT，并仅在初始化完成后动态导入原始入口。webpack 参考应用支持顶层 await：

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

await initializeGTSPA(gtConfig);

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

如果现有 webpack 编译目标不支持顶层 await，请勿仅为此配置而更改它。请改用 async 引导函数：

```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`；下方所示的值仅为示例，不得替换项目已配置的区域设置。

通常，在使用 webpack 的应用中，翻译文件会存储在 `src/_gt` 目录中。这样，webpack 就可以将翻译模块打包到应用程序中。

```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 或 async 函数引导形式。

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