# vue: 加载翻译
URL: https://generaltranslation.com/zh/docs/vue/reference/types/load-translations.mdx
---

title: 加载翻译
description: 加载指定区域设置的完整翻译目录。LoadTranslations 的 API 参考。

---

当目标翻译目录位于应用文件、数据库、API 或其他主机上时，请将此回调传递给 [`createGT()`](/docs/vue/reference/functions/create-gt) 或 [`initializeGTSPA()`](/docs/vue/reference/functions/initialize-gt-spa)。

## 概览 [#overview]

```ts
type LoadTranslations = (
  locale: string
) => Promise<TranslationCatalog>;
```

插件仅针对未缓存的目标区域设置调用加载器。默认区域设置使用源文本，不会调用加载器。

## 参数 [#parameters]

| 参数       | 描述                   | 类型       | 可选 | 默认值 |
| -------- | -------------------- | -------- | -- | --- |
| `locale` | 要返回完整翻译目录的区域设置。 | `string` | 否  | —   |

普通的 [`createGT()`](/docs/vue/reference/functions/create-gt) 插件会原样传递请求的区域设置。[`initializeGTSPA()`](/docs/vue/reference/functions/initialize-gt-spa) 插件会先根据配置的 `locales` 和 `customMapping` 解析区域设置，并保留配置中用于文件路径的拼写。

## 返回值 [#returns]

**类型** `Promise<`[`TranslationCatalog`](/docs/vue/reference/types/translation-catalog)`>`

解析为 `locale` 对应的完整哈希键翻译目录。当没有可用翻译且应用程序应使用源内容时，解析为 `{}`。

请勿返回 `null`、`undefined` 或结构不同的部分值。公开的回调类型要求返回翻译目录对象。

## 加载行为 [#loading-behavior]

* 成功的加载结果会在该插件的整个生命周期内缓存。
* 针对同一区域设置的并发加载会共享同一个 Promise。
* `plugin.loadTranslations(locale)` 会预加载，但不会更改当前活动区域设置。
* 响应式 `plugin.setLocale(locale)` 会先加载再切换。
* [`initializeGTSPA()`](/docs/vue/reference/functions/initialize-gt-spa) 会在其 Promise 兑现前加载初始目标区域设置。
* 安装 [`createGT()`](/docs/vue/reference/functions/create-gt) 插件会在后台启动初始目标区域设置的加载，因此可以先渲染源内容。

## 失败 [#failures]

当回调被拒绝时，`gt-vue` 会记录诊断信息，重新抛出同一异常，移除正在处理的条目，并且不缓存结果。后续调用可以重试。

因此，命令式调用 `loadTranslations()`、响应式区域设置变更或 SPA 初始化都会被拒绝。由 `app.use(createGT(...))` 启动的后台加载会在记录日志后捕获该异常，以便应用程序能够继续使用源内容。

## 示例 [#example]

```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 (error) {
    console.error(`No translation catalog for ${locale}`, error);
    return {};
  }
};

export default loadTranslations;
```

上述加载器会将缺失的文件视为成功加载的空翻译目录。当缺失或无效的翻译目录应中止初始化时，请移除 `try`/`catch`。