# Vue: 快速入门
URL: https://generaltranslation.com/zh/docs/vue/quickstart.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: 在 10 分钟内为 Vue 应用添加多语言支持。

完成本指南后，你的 Vue 应用将能够以多种语言显示内容，用户无需重新加载页面即可切换当前区域设置。

`gt-vue` 以 Vue 插件的形式运行。该插件会加载一次并缓存每个翻译目录，并在区域设置变更时以响应式方式重新渲染翻译后的内容。

**前提条件：**

* Vue 3.3 或更高版本的应用
* 当前 Vite 工具链所需的 Node.js `^20.19.0 || >=22.12.0`

<Callout type="info">
  **0.x 版本包：** `gt-vue` 尚不稳定，其 API 和行为可能随版本更新而变化，且不与稳定版 React packages 的发布保持一致。
</Callout>

## 快速入门 [#quickstart]

### 1. 安装依赖包

`gt-vue` 为你的应用提供翻译功能。[`gt`](/docs/cli/quickstart) 会提取源内容并生成翻译目录。

<Tabs items={['npm', 'yarn', 'bun', 'pnpm']}>
  <Tab value="npm">
    ```bash
    npm install gt-vue
    npm install --save-dev gt
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn add gt-vue
    yarn add --dev gt
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    bun add gt-vue
    bun add --dev gt
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm add gt-vue
    pnpm add --save-dev gt
    ```
  </Tab>
</Tabs>

### 2. 创建翻译配置文件

在项目根目录中创建 `gt.config.json`。设置源内容的区域设置、要翻译成的区域设置，以及生成 翻译目录 的输出路径。

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

* `defaultLocale` 是源内容的语言。
* `locales` 列出目标语言。从[支持的区域设置列表](/docs/platform/dashboard/reference/supported-locales)中选择任意区域设置。
* `files.gt.output` 指定 CLI 将每个 翻译目录 写入的位置。请在路径中保留 `[locale]` 占位符。

### 3. 创建翻译加载器

创建一个加载器，用于返回所请求区域设置对应的生成翻译目录：

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

由于源内容本身就是默认区域设置的内容翻译目录，因此不会为默认区域设置调用加载器。目标内容翻译目录不可用时，返回空对象可让应用渲染源内容。

### 4. 注册插件

创建一个 [`createGT()`](/docs/vue/reference/functions/create-gt) 插件，并在挂载应用之前安装该插件：

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

该插件会在存在已保存的区域设置 cookie 时使用它，否则以 `defaultLocale` 作为初始值。它会立即以源内容挂载，并在所请求的翻译目录加载完成后响应式更新。

### 5. 标记需要翻译的内容

富模板内容使用 [`<T>`](/docs/vue/reference/components/t)，输入属性等独立字符串使用 [`useGT()`](/docs/vue/reference/composables/use-gt)：

```vue title="src/App.vue"
<script setup lang="ts">
import { T, useGT } from 'gt-vue';

const gt = useGT();
</script>

<template>
  <main>
    <T>
      <h1>Welcome to my app</h1>
      <p>This content will be translated automatically.</p>
    </T>

    <input :placeholder="gt('Search products')" />
  </main>
</template>
```

请保持 [`<T>`](/docs/vue/reference/components/t) 内的内容静态不变。对于运行时值和条件分支内容，请使用[变量和分支组件](/docs/vue/guides/formatting-variables)。

### 6. 添加语言切换器

使用 [`useLocale()`](/docs/vue/reference/composables/use-locale) 获取当前区域设置，并使用 [`useSetLocale()`](/docs/vue/reference/composables/use-set-locale) 进行切换：

```vue title="src/App.vue"
<script setup lang="ts">
import { T, useGT, useLocale, useSetLocale } from 'gt-vue';
import gtConfig from '../gt.config.json';

const gt = useGT();
const locale = useLocale();
const setLocale = useSetLocale();
const locales = [gtConfig.defaultLocale, ...gtConfig.locales];

async function changeLocale(event: Event) {
  const target = event.target as HTMLSelectElement;
  await setLocale(target.value);
}
</script>

<template>
  <main>
    <label>
      Language
      <select :value="locale" @change="changeLocale">
        <option v-for="code in locales" :key="code" :value="code">
          {{ code }}
        </option>
      </select>
    </label>

    <T>
      <h1>Welcome to my app</h1>
      <p>This content will be translated automatically.</p>
    </T>

    <input :placeholder="gt('Search products')" />
  </main>
</template>
```

[`useSetLocale()`](/docs/vue/reference/composables/use-set-locale) 会先加载缺失的翻译目录，然后保存区域设置 cookie 并重新渲染响应式消费者。使用上述加载器时，如果文件缺失，会返回空翻译目录、切换区域设置，并渲染源内容。如果加载器改为返回拒绝状态，则当前区域设置保持不变。

### 7. 身份验证并翻译

使用 General Translation 进行身份验证：

```bash
npx gt auth
```

该命令会引导你登录并创建凭据。请将生成的生产环境 API 密钥保存在本地环境文件中，切勿将其写入浏览器代码或提交到版本控制系统。

然后生成翻译目录：

```bash
npx gt translate
```

CLI 会扫描你的 Vue 源代码，翻译提取出的内容，并在 `src/_gt/` 中为每个目标区域设置写入一个 JSON 文件。源内容发生变化时，请再次运行该命令。

### 8. 运行并验证

启动应用：

<Tabs items={['npm', 'yarn', 'bun', 'pnpm']}>
  <Tab value="npm">
    ```bash
    npm run dev
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn dev
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    bun run dev
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm dev
    ```
  </Tab>
</Tabs>

打开开发服务器输出的本地 URL。在语言选择器中选择 `es`、`fr` 或 `ja`，确认标题和搜索框占位符已显示为翻译后的文本。

## 故障排除 [#troubleshooting]

<Accordions>
  <Accordion title="应用始终使用源区域设置">
    当前区域设置存储在 `generaltranslation.locale` cookie 中。请清除过期的 cookie，然后重新选择目标区域设置。还请确认对应的 JSON 文件位于 `src/_gt/` 下，并且加载器返回其默认导出。
  </Accordion>

  <Accordion title="切换区域设置后，翻译字符串未更新">
    请在模板或 Vue 计算属性中调用 [`useGT()`](/docs/vue/reference/composables/use-gt) 返回的函数。在 setup 阶段只翻译一次的字符串属于翻译快照，不会在响应式区域设置状态变化时重新执行。
  </Accordion>
</Accordions>

## Next steps

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

## Sitemap

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