# vue: 配置 gt-vue
URL: https://generaltranslation.com/zh/docs/vue/guides/configuring.mdx
---

title: 配置 gt-vue
description: 如何创建 Vue 翻译插件、加载翻译目录，并配置浏览器端或服务器端渲染。
related:
  links:
    - /docs/vue/guides/translating-content
    - /docs/vue/guides/translating-strings
    - /docs/vue/guides/managing-locales
    - /docs/vue/guides/storing-translations

---

每个相互独立的 Vue 应用都应创建一个插件。插件负责管理其当前区域设置、已加载的翻译目录和响应式翻译状态。

对于常规 Vue 应用，请使用 [`createGT()`](/docs/vue/reference/functions/create-gt)，包括无需重新加载即可切换区域设置的应用，以及在服务器端渲染的应用。仅在浏览器端运行且需要模块级 [`t()`](/docs/vue/reference/functions/t) 的 SPA 则采用另一种启动方式，详见[使用 SPA 翻译进行开发](/docs/vue/guides/developing-spa-translations)。

## 创建插件 [#create]

向 [`createGT()`](/docs/vue/reference/functions/create-gt) 传入源区域设置和 [`loadTranslations`](/docs/vue/reference/types/load-translations) 回调，然后使用 `app.use()` 安装返回的插件：

```ts title="src/main.ts"
import { createApp } from 'vue';
import { createGT } from 'gt-vue';
import App from './App.vue';
import gtConfig from '../gt.config.json';
import loadTranslations from './loadTranslations';

const gt = createGT({
  defaultLocale: gtConfig.defaultLocale,
  loadTranslations,
});

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

该插件只需安装一次。创建另一个实例会使其拥有独立的区域设置和翻译目录缓存。

## 解析初始区域设置 [#initial-locale]

[`createGT()`](/docs/vue/reference/functions/create-gt) 会按以下顺序解析初始区域设置：

1. 显式指定的 `locale` 选项。
2. 浏览器中已配置的区域设置 cookie 值。
3. `defaultLocale`。

在服务器端渲染和 hydration 期间，显式指定的区域设置具有最高优先级。在浏览器中，它会替换过时的 cookie，确保客户端以与服务器端相同的区域设置启动。

```ts
const gt = createGT({
  defaultLocale: 'en',
  locale: serverLocale,
  localeCookieName: 'my-app.locale',
  loadTranslations,
});
```

默认的 cookie 名称为 `generaltranslation.locale`。仅当路由或服务器端需要共享其他 cookie 时，才更改 `localeCookieName`。

## 加载翻译目录 [#load]

默认区域设置直接渲染源内容，因此不会调用其加载器。其他区域设置通过 [`loadTranslations`](/docs/vue/reference/types/load-translations) 加载：

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

const loadTranslations: LoadTranslations = async (locale) => {
  try {
    return (await import(`./_gt/${locale}.json`)).default;
  } catch {
    return {};
  }
};

export default loadTranslations;
```

成功加载的翻译目录会在插件的整个生命周期内缓存；针对同一区域设置的并发请求会共享同一次加载。在客户端，首次加载翻译目录时，应用可以先使用源内容挂载；翻译目录加载完成后，已翻译的组件会重新渲染。

返回空对象时，会将源内容用作后备内容。如果回调被拒绝，区域设置切换也会被拒绝，当前区域设置将保持不变。

## 保持 CLI 与运行时配置同步 [#shared-config]

使用 `gt.config.json` 统一记录源区域设置、目标区域设置和生成文件的位置：

```json title="gt.config.json"
{
  "defaultLocale": "en",
  "locales": ["es", "fr"],
  "files": {
    "gt": {
      "output": "src/_gt/[locale].json"
    }
  }
}
```

CLI 会直接读取此文件。[`createGT()`](/docs/vue/reference/functions/create-gt) 接受自己的运行时选项，因此请显式传入 `defaultLocale` 和加载器。`locales` 列表对语言切换器和 CLI 仍然有用，但响应式插件不会拒绝其他区域设置代码；可用的区域设置由 UI 和加载器决定。

生产环境 API 凭据应由生成翻译的 CLI 进程使用。请勿在浏览器代码中暴露 `GT_API_KEY`。

## 配置服务器端渲染 [#ssr]

为每个请求创建一个新的插件实例，避免区域设置和翻译目录状态在不同用户之间泄漏。解析请求区域设置后，显式传入该设置，并在渲染前预加载相应翻译目录：

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

在请求对应的 Vue 应用中安装返回的插件。在浏览器中进行水合前，使用相同的显式区域设置创建并预加载客户端插件。如果在目标翻译目录就绪前进行水合，可能会短暂渲染源内容并导致不匹配。
## Next steps

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