# vue: InitializeGTSPAOptions
URL: https://generaltranslation.com/zh/docs/vue/reference/types/initialize-gt-spa-options.mdx
---

title: InitializeGTSPAOptions
description: 配置供预加载模块级翻译使用的仅限浏览器的单例。InitializeGTSPAOptions 的 API 参考。

---

将此对象传递给 [`initializeGTSPA()`](/docs/vue/reference/functions/initialize-gt-spa)。它在 [`CreateGTOptions`](/docs/vue/reference/types/create-gt-options) 的基础上扩展了可直接从 `gt.config.json` 读取的区域设置列表和别名。

## 概述 [#overview]

```ts
type InitializeGTSPAOptions = CreateGTOptions & {
  customMapping?: CustomMapping;
  locales?: readonly string[];
};
```

| 选项                                      | 描述                                  | 类型                                                                    | 可选 | 默认                          |
| --------------------------------------- | ----------------------------------- | --------------------------------------------------------------------- | -- | --------------------------- |
| [`defaultLocale`](#defaultlocale)       | 源区域设置和后备区域设置。                       | `string`                                                              | 是  | `en`                        |
| [`loadTranslations`](#loadtranslations) | 异步目标目录加载器。                          | [`LoadTranslations`](/docs/vue/reference/types/load-translations)     | 是  | 空目录                         |
| [`locale`](#locale)                     | 显式指定的初始区域设置。                        | `string`                                                              | 是  | Cookie，其次为 `defaultLocale`  |
| [`localeCookieName`](#localecookiename) | 用于保存区域设置选择的 Cookie。                 | `string`                                                              | 是  | `generaltranslation.locale` |
| [`customMapping`](#custommapping)       | 用于区域设置匹配和格式化程序区域设置解析的 `code` 值映射对象。 | [`CustomMapping`](/docs/platform/core/reference/types/custom-mapping) | 是  | 无                           |
| [`locales`](#locales)                   | 此 SPA 支持的目标区域设置。                    | `readonly string[]`                                                   | 是  | 不受限制                        |

## 通用选项 [#shared-options]

### `defaultLocale`

**类型** `string` · **可选** · **默认值** `en`

源区域设置及后备区域设置。它会自动包含在受支持的区域设置集合中，并使用源内容，而不会调用加载器。

### `loadTranslations`

**类型** [`LoadTranslations`](/docs/vue/reference/types/load-translations) · **可选** · **默认** 空目录

加载完整的目标目录。SPA 初始化会在完成前等待活动区域设置的目录加载完毕。如果加载被拒绝，会记录诊断信息、导致初始化失败，并允许后续的初始化调用重试。

### `locale`

**类型** `string` · **可选** · **默认** 浏览器 cookie，其次为 `defaultLocale`

显式指定初始区域设置。它的优先级高于 cookie，会根据 `locales` 解析，并被持久保存。随后，当前页面将固定使用解析后的区域设置，直到文档重新加载。

### `localeCookieName`

**类型** `string` · **可选** · **默认值** `generaltranslation.locale`

指定在初始化期间读取，并在 SPA 重新加载区域设置前写入的适用于整个路径的会话 Cookie。

## SPA 选项 [#spa-options]

### `customMapping`

**类型** `Record<string, string | Partial<LocaleProperties>>` · **可选** · **默认值** 无

声明 General Translation 配置中的区域设置别名。SPA 会使用对象映射中有效的 `code` 来匹配受支持的区域设置，并将其作为富内容和格式化组件的格式化器区域设置。`gt-vue` 不会读取对象映射中的字符串值或其他属性。

加载器路径仍会使用所匹配的已配置 `defaultLocale` 或 `locales` 条目中的拼写形式。

### `locales`

**类型** `readonly string[]` · **可选** · **默认** 不受限制

应用程序声明的目标区域设置。初始化程序会对 `[defaultLocale, ...locales]` 去重，以不区分大小写的方式匹配请求，并通过规范区域设置解析进行匹配；如果没有匹配的已配置区域设置，则回退到 `defaultLocale`。

省略此选项时，不会拒绝非默认区域设置代码。`defaultLocale` 的大小写变体或别名仍会解析为配置的默认拼写形式。

## 单例行为 [#singleton]

只有首次初始化尝试中提供的选项会用于创建页面级运行时环境。并发调用会共享该尝试。初始化成功后，后续调用将返回现有 plugin，且不会应用新的选项值。

如果首次尝试被拒绝，其正在进行的单例条目会被清除，后续调用可使用新选项重试。

## 示例 [#example]

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

const options: InitializeGTSPAOptions = {
  defaultLocale: gtConfig.defaultLocale,
  locales: gtConfig.locales,
  customMapping: gtConfig.customMapping,
  loadTranslations,
};

async function bootstrap() {
  const gt = await initializeGTSPA(options);
  const { mount } = await import('./main');
  mount(gt);
}

void bootstrap().catch((error: unknown) => {
  console.error(error);
});
```

此 API 仅可在浏览器中使用。若需进行服务器端渲染，请使用请求级的 [`CreateGTOptions`](/docs/vue/reference/types/create-gt-options) 和 [`createGT()`](/docs/vue/reference/functions/create-gt)。