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

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

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

## React Vite SPA 设置 [#setup]

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

### 1. 安装 gt-react

请使用该 repository 首选的 package manager 安装最新版 `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/index.ts` 作为引导文件，在初始化后导入现有的 `src/main.tsx` 入口文件，并更新 HTML 入口：

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

创建 `src/index.ts`，然后在库初始化并加载翻译内容之后，动态导入入口文件。

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

await initializeGTSPA(gtConfig);

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

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

通常，在由 Vite 驱动的应用中，翻译文件会存储在 `src/_gt` 目录中，以便在应用代码中使用。

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

### 2. 添加存根文件

对于 `gt.config.json` 中已配置的每个目标区域设置 (默认区域设置除外) ，创建一个空的 JSON 文件。这些存根文件可让 import 在翻译 bundle 尚不存在时完成解析。下方的 `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`); // 需解析到与 `files.gt.output` 中配置的输出位置一致
  return translations.default;
}
```

### 4. 更新初始化程序

更新初始化程序以使用新的加载器函数。

```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'); // 仅在 GT 已就绪后再渲染应用
```

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