# Vue: createGT
URL: https://generaltranslation.com/zh/docs/vue/reference/functions/create-gt.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: 创建具有响应式区域设置状态和目录缓存的独立 Vue 翻译插件。createGT 的 API 参考。

每次调用都会创建独立的区域设置状态、进行中的加载任务和缓存的目录。适用于常规客户端应用；对于服务器端渲染，请为每个请求创建一个实例。

## 概览 [#overview]

```ts
function createGT(options?: CreateGTOptions): GTPlugin;
```

[`createGT()`](#overview) 会立即返回。使用 `app.use()` 安装插件，或在渲染前通过其返回的 [`GTPlugin`](/docs/vue/reference/types/gt-plugin) 预加载区域设置。

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

const gt = createGT({
  defaultLocale: 'en',
  loadTranslations: async (locale) =>
    (await import(`./_gt/${locale}.json`)).default,
});

createApp(App).use(gt).mount('#app');
```

## 参数 [#parameters]

| 参数        | 描述                         | 类型                                                               | 可选 | 默认值  |
| --------- | -------------------------- | ---------------------------------------------------------------- | -- | ---- |
| `options` | 初始区域设置、Cookie 和 目录 加载器的配置。 | [`CreateGTOptions`](/docs/vue/reference/types/create-gt-options) | 是  | `{}` |

`options` 对象接受以下字段：

| 选项                 | 描述                        | 类型                                                                    | 可选 | 默认值                         |
| ------------------ | ------------------------- | --------------------------------------------------------------------- | -- | --------------------------- |
| `customMapping`    | 用于格式化和复数选择的区域设置别名。        | [`CustomMapping`](/docs/platform/core/reference/types/custom-mapping) | 是  | 无                           |
| `defaultLocale`    | 源区域设置和后备区域设置。             | `string`                                                              | 是  | `en`                        |
| `loadTranslations` | 异步目标 目录 加载器。              | [`LoadTranslations`](/docs/vue/reference/types/load-translations)     | 是  | 空 目录                        |
| `locale`           | 显式指定初始区域设置，优先于浏览器 Cookie。 | `string`                                                              | 是  | Cookie，其次为 `defaultLocale`  |
| `localeCookieName` | 用于持久保存区域设置的浏览器 Cookie。    | `string`                                                              | 是  | `generaltranslation.locale` |

默认区域设置始终渲染源内容，因此不会调用其加载器。与 [`initializeGTSPA()`](/docs/vue/reference/functions/initialize-gt-spa) 不同，[`createGT()`](#overview) 不接受 `locales` 允许列表；可用的目录键由调用方和加载器决定。其 `customMapping` 选项会影响区域设置相关的格式化和复数选择，但不会改变目录键或 Cookie 键。

## 返回值 [#returns]

**类型** [`GTPlugin`](/docs/vue/reference/types/gt-plugin)

返回的插件提供 `install()`、`getLocale()`、`loadTranslations()` 和 `setLocale()`。请安装与调用命令式方法时所用实例相同的实例。

此插件未连接到 [`t()`](/docs/vue/reference/functions/t) 使用的浏览器全局状态。需要模块级翻译的客户端应用必须改为安装 [`initializeGTSPA()`](/docs/vue/reference/functions/initialize-gt-spa) 返回的同一插件实例。

## 工作原理 [#how-it-works]

* **初始区域设置：**显式指定的 `locale` 优先于浏览器 cookie，浏览器 cookie 又优先于 `defaultLocale`。服务器端没有浏览器 cookie。在浏览器中，显式指定的区域设置也会写入 cookie，以确保水合一致。
* **初始加载：**`app.use(gt)` 会开始加载当前目标区域设置，且不会阻塞挂载。在目录到达前会渲染源内容；目录到达后，执行过查找的消费者将重新渲染。
* **缓存：**成功加载的目录会在插件的整个生命周期内缓存。针对同一区域设置的并发请求会共享同一个 promise。默认区域设置以源文本表示，并且已作为空目录缓存。
* **区域设置变更：**`setLocale(locale)` 会在更新 cookie 和响应式消费者之前加载尚未缓存的目录。当区域设置请求重叠时，只有最新的请求会更改当前区域设置；之前成功加载的目录仍会保留在缓存中。
* **外部 cookie 变更：**`getLocale()` 会读取当前浏览器 cookie。浏览器不会触发响应式的 cookie 变更事件，因此直接修改 `document.cookie` 不会触发渲染；请调用插件的 setter 或 [`useSetLocale()`](/docs/vue/reference/composables/use-set-locale)。

如果加载器发生拒绝，插件会记录 `gt-vue` 诊断信息、重新抛出错误，并且不会缓存失败结果。被拒绝的 `setLocale()` 会保留原有的区域设置和 cookie。由 `install()` 启动的后台加载会记录失败，但会捕获其拒绝，以便应用能够继续渲染源内容。

## 服务器端渲染 [#server-rendering]

每个请求都应创建一个新的插件，并显式传入请求区域设置。渲染前，请等待 `loadTranslations(locale)` 或 `setLocale(locale)` 完成：

```ts title="src/gt-server.ts"
import { createGT } from 'gt-vue';
import loadTranslations from './loadTranslations';

export async function createRequestGT(locale: string) {
  const gt = createGT({
    defaultLocale: 'en',
    locale,
    loadTranslations,
  });

  await gt.loadTranslations(locale);
  return gt;
}
```

请勿跨请求共享此插件。其区域设置和 目录 缓存仅属于单个应用实例。在 水合 之前，请创建并预加载具有相同显式区域设置的客户端插件；如果针对未加载的 目录 进行 水合，可能会渲染源内容并导致不匹配。

## 示例 [#example]

当宿主应用负责切换区域设置时，可在组件外使用返回的插件方法：

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

await gt.loadTranslations('fr'); // 预加载，不切换区域设置
await gt.setLocale('fr'); // 使用已缓存的 目录，并重新渲染各个使用方

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

## Sitemap

See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.