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

配置应用运行时，并可选择通过 Bazel 构建打包生成的翻译目录。

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

## React Bazel SPA 设置 [#setup]

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

### 1. 安装 gt-react

使用代码仓库首选的包管理器安装最新版 `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.js` 作为引导文件，并在初始化后导入现有的 `src/main.jsx` 入口文件。

找到用于构建浏览器 bundle 的 Bazel 目标。保留项目'现有规则、依赖项、源文件声明和构建选项。不要替换其 bundler，也不要新增第二条构建流水线。

该 target 必须包含新引导文件导入的所有文件。将已安装的 `gt-react` npm 标签添加到依赖项列表。如果 `gt.config.json` 尚未包含在已声明的 input 中，请将其添加到 `srcs` 或 `data`。如果 target 已通过 glob 包含源目录，则会自动包含引导文件。

然后，将 target 的浏览器入口文件从现有的 React 入口文件改为新的引导文件。对于在代码仓库根目录使用 Aspect's `esbuild` 规则的应用程序，最终的 target 可以如下所示：

```python title="BUILD.bazel"
load("@aspect_rules_esbuild//esbuild:defs.bzl", "esbuild")

esbuild(
    name = "app",
    srcs = glob(["src/**"]) + ["gt.config.json"],
    deps = [
        ":node_modules/react",
        ":node_modules/react-dom",
        ":node_modules/gt-react",
    ],
    entry_point = "src/index.js",
    format = "esm",
    output = "app.js",
)
```

使用项目中已有的标签和属性。例如，子 Bazel package 中的 Target 可以使用 `//:gt.config.json` 和 `//:node_modules/gt-react`，而非相对于 root package 的标签。如果 bundle 依赖第一方 `js_library`，请在拥有导入 source 的 Target 上声明 `gt-react`，不要随意重复声明。

除非现有 Bazel bundle 已支持 top-level await，否则请使用 async 引导函数。不要仅为启用 top-level await 而更改 output format 或 JavaScript Target。

```js title="src/index.js"
import { initializeGTSPA } from 'gt-react';

import gtConfig from '../gt.config.json';

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

void bootstrap();
```

不要将原始 entry 配置为第二个浏览器 entry。它只能在 [`initializeGTSPA`](/docs/react/reference/config#initialize-spa) 完成后渲染。请运行该应用在代码仓库中常规的 Bazel 构建或测试目标。不要启动持续运行的开发或预览服务器。

## 加载翻译 [#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 加载翻译。若要将目录随应用程序包一起发布，请配置输出路径及相应的加载器。以下步骤使用 `src/_gt/[locale].json`。

### 1. 更新配置

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

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

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

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

### 2. 添加存根文件

为 `gt.config.json` 中已配置的每个目标区域设置创建一个空 JSON 文件，但默认区域设置除外。这些存根文件可让导入在翻译包尚不存在时正常解析。下方的 `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"
{}
```

确保所属的 Bazel 目标声明了这些 JSON 文件。现有的 `glob(["src/**"])` 会将其包含在内；否则，请根据规则的 API 将这些文件添加到目标的 `srcs` 或 `data` 中。

### 3. 添加加载器

创建 `src/loadTranslations.js` 来加载翻译。它必须解析到 `files.gt.output` 中配置的同一输出位置。

在 `translationLoaders` 中显式列出每个已配置的目标区域设置。每个加载器都必须使用字面量导入路径，以便 Bazel 和底层打包工具能在构建时发现所有翻译文件。下面的 `fr` 和 `zh` 条目与本指南的示例配置一致；请改用项目实际配置的目标区域设置。

```js title="src/loadTranslations.js"
const translationLoaders = {
  fr: () => import('./_gt/fr.json'),
  zh: () => import('./_gt/zh.json'),
};

export default async function loadTranslations(locale) {
  const loader = translationLoaders[locale];
  if (!loader) {
    console.warn(`No translations found for locale "${locale}"`);
    return {};
  }

  const translations = await loader();
  return translations.default;
}
```

### 4. 更新初始化器

更新初始化器以使用新的加载器函数。保留异步引导方式以及原始应用程序入口导入。

```js title="src/index.js"
import { initializeGTSPA } from 'gt-react';

import gtConfig from '../gt.config.json';
import loadTranslations from './loadTranslations';

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

void bootstrap();
```

添加打包的翻译后，再次运行 Bazel 构建或测试目标。

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