# vue: createGT
URL: https://generaltranslation.com/ru/docs/vue/reference/functions/create-gt.mdx
---

title: createGT
description: Создаёт изолированный плагин перевода для Vue с реактивным состоянием локали и кэшем каталогов. Справочник API createGT.

---

Каждый вызов создаёт независимое состояние локали, выполняющиеся загрузки и кэшированные каталоги. Используйте его в обычных клиентских приложениях, а для серверного рендеринга создавайте отдельный экземпляр для каждого запроса.

## Обзор [#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` поддерживает следующие поля:

| Параметр           | Описание                                                                    | Тип                                                               | Необязательный | По умолчанию                       |
| ------------------ | --------------------------------------------------------------------------- | ----------------------------------------------------------------- | -------------- | ---------------------------------- |
| `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`; вызывающий код и загрузчик определяют, какие коды локалей доступны.

## Возвращаемое значение [#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-файлом браузера, который, в свою очередь, имеет приоритет над `defaultLocale`. На сервере cookie-файл браузера отсутствует. В браузере явно заданная локаль также записывается в cookie-файл для согласованности при гидратации.
* **Начальная загрузка:** `app.use(gt)` начинает загружать активную целевую локаль, не блокируя монтирование. Пока каталог не загрузится, отображается исходный контент; затем компоненты, выполнившие lookup, перерисовываются.
* **Кэширование:** успешно загруженные каталоги кэшируются на время жизни плагина. Параллельные запросы одной и той же локали используют один promise. Локаль по умолчанию представлена исходным текстом и уже кэшируется как пустой каталог.
* **Изменение локали:** `setLocale(locale)` загружает отсутствующий в кэше каталог, прежде чем обновить cookie-файл и реактивные компоненты. Если запросы локали перекрываются, активную локаль изменяет только последний запрос; успешно загруженные ранее каталоги остаются в кэше.
* **Внешние изменения cookie-файла:** `getLocale()` считывает текущий cookie-файл браузера. Браузеры не генерируют реактивное событие изменения cookie-файла, поэтому прямое изменение `document.cookie` не запускает рендеринг; вызовите сеттер плагина или [`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"
```