# Vue: 配置
URL: https://generaltranslation.com/zh/docs/vue/reference/config.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: 配置 Vue 应用的翻译目录生成和运行时初始化。Vue 配置参考。

配置有两个独立的使用者。`gt` CLI 会读取 `gt.config.json` 来查找源内容并写入翻译目录，而应用程序则会将运行时选项传递给 [`createGT()`](/docs/vue/reference/functions/create-gt) 或 [`initializeGTSPA()`](/docs/vue/reference/functions/initialize-gt-spa)。

`gt-vue` 不会自动查找或读取 `gt.config.json`。请显式导入共享值，并在应用程序代码中提供 [`loadTranslations`](/docs/vue/reference/types/load-translations) 等函数。

## 概览 [#overview]

| 使用位置                                                                   | 用途                                                              | 配置                                                                                            |
| ---------------------------------------------------------------------- | --------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| `gt.config.json`                                                       | 提取源内容并生成翻译目录。                                                   | 可序列化为 JSON 的 CLI 字段，例如 `projectId`、`defaultLocale`、`locales`、`src`、`files` 和 `customMapping`。 |
| [`createGT()`](/docs/vue/reference/functions/create-gt)                | 为响应式客户端渲染或按请求作用域的服务器端渲染创建独立插件。                                  | [`CreateGTOptions`](/docs/vue/reference/types/create-gt-options)                              |
| [`initializeGTSPA()`](/docs/vue/reference/functions/initialize-gt-spa) | 创建并预加载供模块级 [`t()`](/docs/vue/reference/functions/t) 使用的浏览器全局插件。 | [`InitializeGTSPAOptions`](/docs/vue/reference/types/initialize-gt-spa-options)               |

仅限 CLI 使用的字段 `projectId`、`src` 和 `files` 会被运行时忽略。仅限运行时使用的字段 `locale`、`localeCookieName` 和 `loadTranslations` 无法完全用 JSON 表示。`defaultLocale` 和 `customMapping` 由所有使用位置共用，而 `locales` 由 SPA 初始化器接受。

## `gt.config.json` [#config-file]

将 `gt.config.json` 放在项目根目录下。此 Vue 配置会扫描明确指定的源文件 glob，并为每个目标区域设置写入一个翻译目录：

```json title="gt.config.json"
{
  "$schema": "https://assets.gtx.dev/config-schema.json",
  "defaultLocale": "en",
  "locales": ["es", "fr"],
  "src": ["src/**/*.{vue,js,jsx,mjs,cjs,ts,tsx,mts,cts}"],
  "files": {
    "gt": {
      "output": "src/_gt/[locale].json"
    }
  }
}
```

`src` 条目是 glob 模式。像 `"src"` 这样仅指定目录，并不代表递归匹配文件；请包含 CLI 要扫描的文件及其扩展名。省略 `src` 时，Vue 默认配置会涵盖根目录中的单文件组件，以及常规的 Vue 和 Nuxt 目录。

| 字段                                                           | Vue 用法                                    | 运行时用法                                                                                                                                                                                     |
| ------------------------------------------------------------ | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `$schema`                                                    | 提供编辑器验证和自动补全。                             | 无                                                                                                                                                                                         |
| `projectId`                                                  | 选择 CLI 使用的 General Translation 项目。        | 无                                                                                                                                                                                         |
| [`defaultLocale`](/docs/cli/reference/config#default-locale) | 声明源区域设置。                                  | 传递给任一运行时初始化器。                                                                                                                                                                             |
| [`locales`](/docs/cli/reference/config#locales)              | 声明由 CLI 生成的目标区域设置。                        | 传递给 [`initializeGTSPA()`](/docs/vue/reference/functions/initialize-gt-spa)，以拒绝不受支持的已保存或请求的区域设置。[`createGT()`](/docs/vue/reference/functions/create-gt) 插件不会限制区域设置代码。                      |
| [`src`](/docs/cli/reference/config#src)                      | 选择要提取内容的 Vue、JavaScript 和 TypeScript 源文件。 | 无                                                                                                                                                                                         |
| [`files.gt.output`](/docs/cli/reference/config#files)        | 设置生成的翻译目录路径。请保留 `[locale]` 占位符。           | 让加载器从同一目录导入。                                                                                                                                                                              |
| [`customMapping`](/docs/cli/reference/config#custom-mapping) | 在生成翻译时应用区域设置别名。                           | 传递给任一运行时。[`createGT()`](/docs/vue/reference/functions/create-gt) 会使用具有有效 `code` 的对象映射来处理格式化和复数规则；[`initializeGTSPA()`](/docs/vue/reference/functions/initialize-gt-spa) 还会将其用于受支持区域设置的匹配。 |

有关项目、文件、发布、审校和分支的所有字段，请参阅 [CLI 配置参考](/docs/cli/reference/config)。请将 `GT_API_KEY` 保留在 CLI 环境中；不要将生产凭据放入 `gt.config.json` 或浏览器代码中。

## Vue 提取 [#vue-extraction]

Vue 模板编译器设置会影响提取的内容及其翻译哈希值。默认情况下，提取器会从当前生效的 Vite 或 Nuxt 配置中自动识别这些设置。当自动识别结果存在歧义，或应用使用了自定义值时，请显式配置这些选项：

| 选项                                                    | 说明                     | 类型                         | 可选 | 默认值                         |
| ----------------------------------------------------- | ---------------------- | -------------------------- | -- | --------------------------- |
| `files.gt.parsingFlags.vueCompilerOptions.whitespace` | 与 Vue 的模板空白处理方式保持一致。   | `'condense' \| 'preserve'` | 是  | 自动识别到的设置，否则为 Vue 默认值        |
| `files.gt.parsingFlags.vueCompilerOptions.delimiters` | 与自定义模板插值分隔符保持一致。       | `[string, string]`         | 是  | 自动识别到的设置，否则为 `['{{', '}}']` |
| `files.gt.parsingFlags.viteConfigPath`                | 指定一个相对于项目根目录的 Vite 配置。 | `string`                   | 是  | 自动识别                        |

```json title="gt.config.json"
{
  "files": {
    "gt": {
      "parsingFlags": {
        "vueCompilerOptions": {
          "whitespace": "preserve",
          "delimiters": ["${", "}"]
        },
        "viteConfigPath": "config/vite.app.ts"
      }
    }
  }
}
```

请保持这些值与应用编译器中的配置完全一致。修改空白字符或分隔符会改变源内容，并导致现有的翻译哈希值失效。

对于 TypeScript 或 JavaScript 的路径别名 (path aliases) ，请将配置文件传递给 CLI：

```bash
npx gt translate --tsconfig config/tsconfig.app.json
```

`--tsconfig` 及其别名 `--jsconfig` 是命令行选项，而非 `gt.config.json` 中的字段。若省略，提取时会自动查找最近的可用配置文件。

## 运行时选项 [#runtime-options]

| 选项                 | [`createGT()`](/docs/vue/reference/functions/create-gt) | [`initializeGTSPA()`](/docs/vue/reference/functions/initialize-gt-spa) | 默认值                            |
| ------------------ | ------------------------------------------------------- | ---------------------------------------------------------------------- | ------------------------------ |
| `defaultLocale`    | [`createGT()`](/docs/vue/reference/functions/create-gt) | [`initializeGTSPA()`](/docs/vue/reference/functions/initialize-gt-spa) | `en`                           |
| `loadTranslations` | [`createGT()`](/docs/vue/reference/functions/create-gt) | [`initializeGTSPA()`](/docs/vue/reference/functions/initialize-gt-spa) | 空翻译目录                          |
| `locale`           | [`createGT()`](/docs/vue/reference/functions/create-gt) | [`initializeGTSPA()`](/docs/vue/reference/functions/initialize-gt-spa) | 浏览器 cookie，其次为 `defaultLocale` |
| `localeCookieName` | [`createGT()`](/docs/vue/reference/functions/create-gt) | [`initializeGTSPA()`](/docs/vue/reference/functions/initialize-gt-spa) | `generaltranslation.locale`    |
| `locales`          | 否                                                       | [`initializeGTSPA()`](/docs/vue/reference/functions/initialize-gt-spa) | 不限                             |
| `customMapping`    | [`createGT()`](/docs/vue/reference/functions/create-gt) | [`initializeGTSPA()`](/docs/vue/reference/functions/initialize-gt-spa) | 无                              |

有关完整的选项定义，请参阅 [`CreateGTOptions`](/docs/vue/reference/types/create-gt-options) 和 [`InitializeGTSPAOptions`](/docs/vue/reference/types/initialize-gt-spa-options)。支持将 `{ ...gtConfig, loadTranslations }` 传递给 SPA 初始化器：它会使用重叠字段，并在运行时忽略其他 CLI 字段。

## 翻译目录加载 [#catalog-loading]

输出路径和加载器路径必须指向相同的文件：

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

默认区域设置使用源文本，且从不调用加载器。成功加载的目标翻译目录会按插件缓存；针对同一区域设置的并发请求会共享同一个 Promise。被拒绝的加载器调用会被记录并重新抛出；该调用不会被缓存，因此后续调用可以重试。

安装 [`createGT()`](/docs/vue/reference/functions/create-gt) 插件后，会在后台启动初始加载，并在翻译目录加载完成前渲染源内容。[`initializeGTSPA()`](/docs/vue/reference/functions/initialize-gt-spa) 则会在返回前等待初始加载完成。

## 响应式配置 [#reactive-setup]

对于普通客户端应用，请使用 [`createGT()`](/docs/vue/reference/functions/create-gt)。由于 `locales`、`src` 和 `files` 不属于 [`CreateGTOptions`](/docs/vue/reference/types/create-gt-options)，请显式传入这些运行时字段：

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

对于服务器端渲染，请为每个请求创建新的插件，显式传入请求区域设置，并在渲染前进行预加载：

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

在客户端水合前，使用相同的显式区域设置和预加载的翻译目录。共享的服务器端插件可能会导致区域设置和翻译目录状态在不同请求之间泄漏。

## 浏览器 SPA [#browser-spa]

仅当纯浏览器单页应用会在模块作用域中调用 [`t()`](/docs/vue/reference/functions/t) 时，才使用 [`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);
}

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

首次调用会接管整个页面的运行时。区域设置变更会更新 cookie 并重新加载文档，使模块级翻译能够借助新预加载的翻译目录再次运行。若要在不重新加载页面的情况下响应区域设置变更，请使用 [`createGT()`](/docs/vue/reference/functions/create-gt)，并通过 [`useGT()`](/docs/vue/reference/composables/use-gt) 翻译组件中的字符串。

## Sitemap

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