# vue: GTPlugin
URL: https://generaltranslation.com/zh/docs/vue/reference/types/gt-plugin.mdx
---

title: GTPlugin
description: 安装 Vue 翻译状态，并以命令式方式控制其区域设置和目录缓存。GTPlugin 的 API 参考。

---

[`createGT()`](/docs/vue/reference/functions/create-gt) 和 [`initializeGTSPA()`](/docs/vue/reference/functions/initialize-gt-spa) 会返回此 Vue 插件。其状态和行为由创建它的函数决定。

## 概览 [#overview]

```ts
type GTPlugin = {
  getLocale(): string;
  install(app: App): void;
  loadTranslations(locale: string): Promise<TranslationCatalog>;
  setLocale(locale: string): Promise<void>;
};
```

| 方法                                               | 描述                         | 返回类型                          |
| ------------------------------------------------ | -------------------------- | ----------------------------- |
| [`getLocale()`](#get-locale)                     | 返回当前由插件维护的区域设置。            | `string`                      |
| [`install(app)`](#install)                       | 将插件状态提供给 Vue 应用。           | `void`                        |
| [`loadTranslations(locale)`](#load-translations) | 预加载并缓存指定区域设置，但不更改当前活动区域设置。 | `Promise<TranslationCatalog>` |
| [`setLocale(locale)`](#set-locale)               | 根据插件的运行时模式更改或持久保存当前活动区域设置。 | `Promise<void>`               |

## `getLocale()` [#get-locale]

**类型** `() => string` · **必填**

对于浏览器中的 [`createGT()`](/docs/vue/reference/functions/create-gt) 插件，此方法会读取当前配置的区域设置 Cookie；若不可用，则回退到插件显式指定的区域设置或默认区域设置。在服务器端，它会返回实例本地的值。

对于 [`initializeGTSPA()`](/docs/vue/reference/functions/initialize-gt-spa) 插件，它会返回页面初始化时固定的区域设置。直接修改 Cookie 不会改变已挂载的 SPA；需等到下一次重新加载并完成引导后才会生效。

## `install(app)` [#install]

**类型** `(app: App) => void` · **必填**

通过 Vue 依赖注入向组件、格式化器和组合式函数提供翻译状态。调用 `app.use(plugin)` 时会调用此方法。

安装时会开始加载当前区域设置。通过 [`createGT()`](/docs/vue/reference/functions/create-gt) 创建的插件可立即使用源内容挂载，并在加载成功后重新渲染。由 [`initializeGTSPA()`](/docs/vue/reference/functions/initialize-gt-spa) 返回的插件已预加载。

请安装初始化返回的原 SPA 插件。创建并安装第二个插件会使组件查找与模块级 [`t()`](/docs/vue/reference/functions/t) 查找相互独立。未安装任何插件时使用组合式函数会抛出诊断错误。

## `loadTranslations()` [#load-translations]

**类型** `(locale: string) => Promise<`[`TranslationCatalog`](/docs/vue/reference/types/translation-catalog)`>` · **必填**

在不更改当前区域设置的情况下加载并缓存目标目录。对于默认区域设置，会直接返回现有的空目录，不会调用已配置的加载器。

成功结果会缓存在此插件中；针对同一解析后的区域设置的并发调用会共享同一个 Promise。在 SPA 插件中，加载前会应用区域设置别名和受支持区域设置的后备机制。

加载器被拒绝时，错误会被记录并重新抛出。失败结果不会被缓存，因此后续调用可以重试。

## `setLocale()` [#set-locale]

**类型** `(locale: string) => Promise<void>` · **必填**

其行为取决于插件的创建方式：

* **[`createGT()`](/docs/vue/reference/functions/create-gt) 插件：**加载未缓存的目录，然后更新 cookie 和响应式使用者。若加载失败，现有区域设置和 cookie 将保持不变。如果调用发生重叠，则仅应用最新请求。
* **[`initializeGTSPA()`](/docs/vue/reference/functions/initialize-gt-spa) 插件：**解析请求的区域设置，写入 cookie，然后重新加载文档。重新加载前，它不会加载目标目录，也不会更改当前页面中固定的区域设置。

[`useSetLocale()`](/docs/vue/reference/composables/use-set-locale) 通过已安装的插件提供此行为。

## 示例 [#example]

```ts
import { createApp } from 'vue';
import { createGT } from 'gt-vue';
import App from './App.vue';

const gt = createGT({ defaultLocale: 'en', loadTranslations });

await gt.loadTranslations('fr');
createApp(App).use(gt).mount('#app');

await gt.setLocale('fr');
console.log(gt.getLocale()); // "fr"
```