# vue: initializeGTSPA
URL: https://generaltranslation.com/zh/docs/vue/reference/functions/initialize-gt-spa.mdx
---

title: initializeGTSPA
description: 初始化并预加载仅在浏览器中运行的 Vue SPA 运行时，以支持模块级翻译。initializeGTSPA 的 API 参考。

---

此初始化器管理页面级唯一的运行时，并将已加载的目录提供给同步 [`t()`](/docs/vue/reference/functions/t) 调用。它可与组件内的 [`useGT()`](/docs/vue/reference/composables/use-gt) 回调配合使用；但不能替代该组合式函数，也不支持服务器端渲染。

## 概览 [#overview]

```ts
function initializeGTSPA(
  options?: InitializeGTSPAOptions
): Promise<GTPlugin>;
```

在导入任何调用 [`t()`](/docs/vue/reference/functions/t) 的模块前，先等待初始化器完成，再安装其返回的插件：

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

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

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

## 参数 [#parameters]

| 参数        | 描述                                | 类型                                                                              | 可选 | 默认值  |
| --------- | --------------------------------- | ------------------------------------------------------------------------------- | -- | ---- |
| `options` | SPA 的区域设置、Cookie、映射、允许列表和目录加载器配置。 | [`InitializeGTSPAOptions`](/docs/vue/reference/types/initialize-gt-spa-options) | 是  | `{}` |

| 选项                 | 描述                                     | 类型                                                                    | 可选 | 默认值                         |
| ------------------ | -------------------------------------- | --------------------------------------------------------------------- | -- | --------------------------- |
| `defaultLocale`    | 源区域设置和后备区域设置。                          | `string`                                                              | 是  | `en`                        |
| `loadTranslations` | 异步目标目录加载器。                             | [`LoadTranslations`](/docs/vue/reference/types/load-translations)     | 是  | 空目录                         |
| `locale`           | 显式指定初始区域设置，优先于浏览器 Cookie。              | `string`                                                              | 是  | Cookie，其次为 `defaultLocale`  |
| `localeCookieName` | 用于持久保存区域设置选择的 Cookie。                  | `string`                                                              | 是  | `generaltranslation.locale` |
| `locales`          | 可从配置、Cookie 和区域设置函数中接受的目标区域设置。         | `readonly string[]`                                                   | 是  | 不限                          |
| `customMapping`    | 将用于区域设置匹配和格式化器区域设置解析的 `code` 值进行映射的对象。 | [`CustomMapping`](/docs/platform/core/reference/types/custom-mapping) | 是  | 无                           |

`locales` 通常包含 `gt.config.json` 中的目标区域设置；初始化器会将 `defaultLocale` 添加到支持的集合中。有关解析详情，请参阅 [`InitializeGTSPAOptions`](/docs/vue/reference/types/initialize-gt-spa-options)。

## 初始化 [#initialization]

首次调用会启动页面级初始化，并确定其选项。并发调用会共享同一个 Promise。初始化成功后，后续所有调用都会返回同一个 [`GTPlugin`](/docs/vue/reference/types/gt-plugin)，并忽略新的选项。

初始化在完成前会执行以下步骤：

1. 根据 `locales` 和 `customMapping` 解析显式指定的区域设置、已保存的 cookie 或默认区域设置。
2. 创建一个运行时，其活动区域设置在整个页面生命周期内保持固定。
3. 加载并缓存活动目标目录。默认区域设置使用源内容，并跳过加载器。
4. 将运行时提供给模块级 [`t()`](/docs/vue/reference/functions/t) 调用。

如果加载被拒绝，初始化会记录加载器诊断信息并返回拒绝状态。失败的尝试不会成为单例，因此后续调用可以重试。

## 区域设置变更 [#locale-changes]

返回的插件采用重新加载过渡机制。调用 `plugin.setLocale(locale)` 或 [`useSetLocale()`](/docs/vue/reference/composables/use-set-locale) 会解析所请求的区域设置，将其写入配置的 cookie，然后重新加载文档。

当前页面会在重新加载前保持固定的区域设置。下一次引导会解析新的 cookie，并在应用模块运行前预加载对应的目录，因此所有模块级翻译都会重新求值。区域设置函数不会在重新加载前将目标目录加载到当前页面。

如果提供了 `locales`，匹配不区分大小写，并支持规范别名。`gt.config.json` 中的拼写会保留在加载器路径中。不受支持的已保存或请求区域设置会解析为 `defaultLocale`。省略 `locales` 时，非默认区域设置代码不受限制。

## 返回值和错误 [#return-errors]

**返回值** `Promise<`[`GTPlugin`](/docs/vue/reference/types/gt-plugin)`>`

只有在初始区域设置准备就绪后，此 Promise 才会兑现。请安装此插件；如果创建单独的 [`createGT()`](/docs/vue/reference/functions/create-gt) 实例，组件将使用与 [`t()`](/docs/vue/reference/functions/t) 不同的区域设置和目录缓存。

在服务器端渲染环境中，返回的 Promise 会被拒绝，因为浏览器全局状态和文档重新加载无法保证请求安全。进行服务器端渲染时，请为每个请求使用一个 [`createGT({ locale })`](/docs/vue/reference/functions/create-gt#server-rendering) 插件，并在组件内使用 [`useGT()`](/docs/vue/reference/composables/use-gt)。

## 示例 [#example]

将常规 Vue 入口文件封装在挂载函数中：

```ts title="src/main.ts"
import { createApp } from 'vue';
import type { GTPlugin } from 'gt-vue';
import App from './App.vue';

export function mount(gt: GTPlugin) {
  createApp(App).use(gt).mount('#app');
}
```

随后通过动态导入加载的任何模块，都可以在求值期间进行翻译：

```ts title="src/navigation.ts"
import { t } from 'gt-vue';

export const navigation = [
  { label: t('Documentation'), href: '/docs' },
  { label: t('Settings'), href: '/settings' },
];
```