# vue: initializeGTSPA
URL: https://generaltranslation.com/ru/docs/vue/reference/functions/initialize-gt-spa.mdx
---

title: initializeGTSPA
description: Инициализирует и предварительно загружает среду выполнения Vue SPA, работающую только в браузере, для переводов на уровне модуля. Справочник API для initializeGTSPA.

---

Этот инициализатор управляет единой средой выполнения для всей страницы и предоставляет её загруженный каталог синхронным вызовам [`t()`](/docs/vue/reference/functions/t). Он дополняет callback [`useGT()`](/docs/vue/reference/composables/use-gt) внутри компонентов; он не заменяет composable и не поддерживает серверный рендеринг.

## Обзор [#overview]

```ts
function initializeGTSPA(
  options?: InitializeGTSPAOptions
): Promise<GTPlugin>;
```

Дождитесь завершения инициализации перед импортом любого модуля, вызывающего [`t()`](/docs/vue/reference/functions/t), затем установите именно возвращённый плагин:

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

## Параметры [#parameters]

| Параметр  | Описание                                                                                                  | Тип                                                                             | Необязательный | По умолчанию |
| --------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | -------------- | ------------ |
| `options` | Конфигурация локали SPA, загрузчика каталога, cookie-файлов, сопоставлений и списка разрешённых значений. | [`InitializeGTSPAOptions`](/docs/vue/reference/types/initialize-gt-spa-options) | Да             | `{}`         |

| Параметр           | Описание                                                                                                          | Тип                                                                   | Необязательный | По умолчанию                       |
| ------------------ | ----------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | -------------- | ---------------------------------- |
| `defaultLocale`    | Исходная и резервная локаль.                                                                                      | `string`                                                              | Да             | `en`                               |
| `loadTranslations` | Асинхронный загрузчик целевого каталога.                                                                          | [`LoadTranslations`](/docs/vue/reference/types/load-translations)     | Да             | Пустой каталог                     |
| `locale`           | Явно заданная начальная локаль. Имеет приоритет над cookie-файлом браузера.                                       | `string`                                                              | Да             | Cookie-файл, затем `defaultLocale` |
| `localeCookieName` | Cookie-файл для сохранения выбранной локали.                                                                      | `string`                                                              | Да             | `generaltranslation.locale`        |
| `locales`          | Целевые локали, принимаемые из конфигурации, cookie-файлов и сеттеров.                                            | `readonly string[]`                                                   | Да             | Без ограничений                    |
| `customMapping`    | Объект сопоставления значений `code`, используемых для сопоставления локалей и разрешения локалей для форматтера. | [`CustomMapping`](/docs/platform/core/reference/types/custom-mapping) | Да             | Нет                                |

`locales` обычно содержит целевые локали из `gt.config.json`; инициализатор добавляет `defaultLocale` к поддерживаемому набору. Подробнее о разрешении локалей см. в [`InitializeGTSPAOptions`](/docs/vue/reference/types/initialize-gt-spa-options).

## Инициализация [#initialization]

Первый вызов запускает инициализацию для всей страницы и определяет её параметры. Параллельные вызовы используют тот же промис. После успешной инициализации каждый последующий вызов возвращает тот же [`GTPlugin`](/docs/vue/reference/types/gt-plugin) и игнорирует новые параметры.

Перед завершением инициализация выполняет следующие шаги:

1. Разрешает явную локаль, сохранённый cookie-файл или локаль по умолчанию на основе `locales` и `customMapping`.
2. Создаёт среду выполнения, активная локаль которой остаётся фиксированной в течение всего времени существования страницы.
3. Загружает и кэширует каталог для активной целевой локали. Для локали по умолчанию используется исходный контент, поэтому загрузчик не вызывается.
4. Делает среду выполнения доступной для вызовов [`t()`](/docs/vue/reference/functions/t) на уровне модуля.

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

## Изменения локали [#locale-changes]

Возвращаемый плагин использует переход с перезагрузкой. Вызов `plugin.setLocale(locale)` или [`useSetLocale()`](/docs/vue/reference/composables/use-set-locale) разрешает запрошенную локаль, записывает её в настроенный cookie-файл и перезагружает документ.

Текущая страница сохраняет закреплённую локаль до перезагрузки. При следующей инициализации разрешается локаль из нового cookie-файла и до запуска модулей приложения предварительно загружается соответствующий каталог, поэтому все переводы на уровне модуля вычисляются заново. Сеттер не загружает целевой каталог на текущую страницу перед перезагрузкой.

Если указано `locales`, сопоставление выполняется без учёта регистра и поддерживает канонические алиасы. Для путей загрузчика сохраняется написание из `gt.config.json`. Неподдерживаемые сохранённые или запрошенные локали разрешаются в `defaultLocale`. Если `locales` не указан, коды локалей, отличные от локали по умолчанию, остаются без ограничений.

## Возвращаемое значение и ошибки [#return-errors]

**Возвращает** `Promise<`[`GTPlugin`](/docs/vue/reference/types/gt-plugin)`>`

Промис разрешается только после того, как начальная локаль будет готова. Установите именно этот плагин: при создании отдельного экземпляра [`createGT()`](/docs/vue/reference/functions/create-gt) компоненты будут использовать локаль и кэш каталога, отличающиеся от тех, что используются [`t()`](/docs/vue/reference/functions/t).

В среде серверного рендеринга возвращаемый промис отклоняется, поскольку глобальное состояние браузера и перезагрузки документа небезопасны в контексте запросов. Для серверного рендеринга используйте один плагин [`createGT({ locale })`](/docs/vue/reference/functions/create-gt#server-rendering), привязанный к области действия запроса, и [`useGT()`](/docs/vue/reference/composables/use-gt) внутри компонентов.

## Пример [#example]

Поместите обычную точку входа Vue в функцию монтирования:

```ts title="src/main.ts"
import { createApp } from 'vue';
import type { GTPlugin } from 'gt-vue';
import App from './App.vue';

export function mount(gt: GTPlugin) {
  createApp(App).use(gt).mount('#app');
}
```

Любой модуль, доступный через последующий динамический импорт, может выполнять перевод во время вычисления:

```ts title="src/navigation.ts"
import { t } from 'gt-vue';

export const navigation = [
  { label: t('Documentation'), href: '/docs' },
  { label: t('Settings'), href: '/settings' },
];
```