# vue: 使用 SPA translations 开发
URL: https://generaltranslation.com/zh/docs/vue/guides/developing-spa-translations.mdx
---

title: 使用 SPA translations 开发
description: 如何预加载 Vue SPA，并在模块作用域中使用 t() 翻译静态字符串。
related:
  links:
    - /docs/vue/guides/translating-strings
    - /docs/vue/guides/managing-locales
    - /docs/vue/guides/storing-translations
    - /docs/vue/guides/configuring

---

仅在浏览器端运行的单页应用可在应用模块运行前预加载当前 catalog。这样一来，便可在 Vue 组件外对常量、导航定义和其他字符串同步调用模块级的 [`t()`](/docs/vue/reference/functions/t)。

[`initializeGTSPA()`](/docs/vue/reference/functions/initialize-gt-spa) 是对 [`useGT()`](/docs/vue/reference/composables/use-gt) 的补充，并非替代。对于常规组件内容，以及需要响应式切换区域设置的 Vue 应用或服务器端渲染应用，请使用该组合式函数。

## 选择 SPA 运行时 [#choose]

仅当以下条件均满足时，才使用 [`initializeGTSPA()`](/docs/vue/reference/functions/initialize-gt-spa)：

* 应用完全在浏览器中运行。
* 模块必须在求值期间翻译字符串。
* 区域设置更改时可以重新加载页面。

如果应用在服务器端渲染，或需要在不重新加载页面的情况下响应式切换区域设置，请使用 [`createGT()`](/docs/vue/reference/functions/create-gt)。

## 导入应用前进行引导初始化 [#bootstrap]

初始化代码必须在任何调用 [`t()`](/docs/vue/reference/functions/t) 的模块之前运行。使用一个小型异步引导程序即可兼容默认的 Vite 6 构建目标，无需顶层 `await` 或 `build.target: 'esnext'`。

### 1. 导出挂载函数

修改常规 Vite 入口模块，使其导出一个接收已初始化 [`GTPlugin`](/docs/vue/reference/types/gt-plugin) 的函数：

```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');
}
```

### 2. 初始化并动态导入

创建一个引导模块，等待 [`initializeGTSPA()`](/docs/vue/reference/functions/initialize-gt-spa) 完成初始化后再导入应用，并安装初始化返回的原插件：

```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);
}

bootstrap().catch((error) => {
  console.error('Failed to initialize translations', error);
});
```

首次调用负责管理页面范围内的 SPA 运行时。并发调用会共享其初始化结果，后续调用则返回同一插件。请勿为已挂载的应用调用 [`createGT()`](/docs/vue/reference/functions/create-gt)，否则组件查找和模块级查找会使用不同的状态。

### 3. 将 Vite 指向引导文件

更新 `index.html` 中的模块脚本，使其加载 `src/index.ts`，而不是 `src/main.ts`：

```html title="index.html"
<script type="module" src="/src/index.ts"></script>
```

## 翻译模块级字符串 [#translate]

通过动态应用导入加载的模块可以同步调用 [`t()`](/docs/vue/reference/functions/t)：

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

export const message = t('Hello World');

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

调用必须使用静态源字符串，也可以传入静态 `$context`。提取器会注册这些字符串，预加载的目录可确保模块运行时查找为同步操作。

[`t()`](/docs/vue/reference/functions/t) 不支持标签模板字面量、ICU 语法、插值、`$format` 或 `$maxChars`。对于包含运行时值的内容，请结合使用 [`<T>`](/docs/vue/reference/components/t) 和 [`<Var>`](/docs/vue/reference/components/var)。

## 在已初始化的 SPA 中更改区域设置 [#locales]

将 `gt.config.json` 中的 `defaultLocale` 和 `locales` 传递给 [`initializeGTSPA()`](/docs/vue/reference/functions/initialize-gt-spa)。如果已保存的区域设置不受支持，则会在下次初始化时回退到默认区域设置。

当 [`useSetLocale()`](/docs/vue/reference/composables/use-set-locale) 更改区域设置时，SPA 运行时会写入区域设置 cookie 并重新加载页面。在重新加载前，当前页面会有意保持初始化时的区域设置。随后，引导过程会在模块级调用再次执行前预加载新的 catalog。

这一重新加载机制确保模块级常量可以安全使用。如果需要在不进行页面导航的情况下更改区域设置，请改用 [`createGT()`](/docs/vue/reference/functions/create-gt)，并在模板或计算属性中调用 [`useGT()`](/docs/vue/reference/composables/use-gt)。
## Next steps

- /docs/vue/guides/translating-strings
- /docs/vue/guides/managing-locales
- /docs/vue/guides/storing-translations
- /docs/vue/guides/configuring