# General Translation Knowledge Base: Как мигрировать с vue-i18n на gt-vue?
URL: https://generaltranslation.com/ru/kb/migrate-from-vue-i18n.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Установите gt-vue рядом с vue-i18n, синхронизируйте активную локаль и переводите компоненты по одному с ключей $t на встроенный текст в `<T>` и useGT. General Translation переводит перенесённый текст, используя структуру шаблона как контекст, а ваша команда может исправить перевод в панели управления. Компоненты, которые ещё не перенесены, продолжают использовать проверенные сообщения vue-i18n.
Category: Интернационализация
Last updated: 2026-11-11
Authors: Kevin Wu
Published: 2026-11-11

vue-i18n выполняет рендеринг переводов, которые вы записываете в отдельный файл сообщений для каждого языка. gt-vue выполняет рендеринг текста, встроенного в шаблоны, а переводы генерирует General Translation с помощью [`npx gt translate`](/docs/cli/reference/commands/translate). При миграции каждый поиск по ключу `$t('key')` заменяется исходным текстом, на который он указывает. Компоненты переносятся по одному, а оба плагина тем временем работают в одном приложении.

## Как API vue-i18n соотносятся с gt-vue?

| vue-i18n                                           | gt-vue                                                                                                                                                                                                            |
| -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `createI18n({ locale, fallbackLocale, messages })` | [`createGT`](/docs/vue/reference/functions/create-gt)`({ defaultLocale, loadTranslations })`, а локали задаются в `gt.config.json`                                                                                |
| `app.use(i18n)`                                    | `app.use(gt)`                                                                                                                                                                                                     |
| `$t('key')` в шаблонах                             | [`<T>`](/docs/vue/reference/components/t) вокруг текста или строка из [`useGT`](/docs/vue/reference/composables/use-gt)                                                                                           |
| `t('key')` в `<script setup>`                      | `const gt = useGT()`, затем `gt('Inbox')` внутри `computed`                                                                                                                                                       |
| Именованная интерполяция `{name}`                  | [`<Var>`](/docs/vue/reference/components/var) внутри [`<T>`](/docs/vue/reference/components/t)                                                                                                                    |
| `<i18n-t keypath="...">` со слотами                | [`<T>`](/docs/vue/reference/components/t), в который обёрнута сама разметка                                                                                                                                       |
| `'no apples \| one apple \| {count} apples'`       | [`<Plural>`](/docs/vue/reference/components/plural) со слотами `#zero`, `#singular` и `#plural`                                                                                                                   |
| `n()` и `d()` с именованными форматами             | [`<Num>`](/docs/vue/reference/components/num), [`<Currency>`](/docs/vue/reference/components/currency) и [`<DateTime>`](/docs/vue/reference/components/datetime) с параметрами `Intl`, встроенными в разметку |
| `locale.value = 'fr'`                              | [`useSetLocale`](/docs/vue/reference/composables/use-set-locale)`()('fr')`; текущую локаль можно получить через [`useLocale`](/docs/vue/reference/composables/use-locale)                                         |
| Ленивая загрузка через `setLocaleMessage`          | Параметр `loadTranslations(locale)` загружает и кэширует каждую локаль                                                                                                                                            |
| `fallbackLocale`                                   | `defaultLocale`; если перевода нет, выполняется рендеринг исходного текста                                                                                                                                                   |

Ключи сообщений, пользовательские блоки SFC `<i18n>` и связанные сообщения (`@:key`) заменяются встроенным текстом: перенесите текст каждого сообщения в шаблон, где выполняется его рендеринг, а связанные сообщения распишите полностью.

## Шаг 1: Установите gt-vue вместе с vue-i18n

gt-vue (сейчас версии 0.x) поддерживает Vue 3.3 и новее. Следуйте руководству [Быстрый старт для Vue](/docs/vue/quickstart). Вкратце:

1. Установите `gt-vue` и CLI `gt` как dev-зависимость.

2. Создайте `gt.config.json` с той же исходной локалью и теми же целевыми локалями, что и в конфигурации vue-i18n, и укажите путь для выходных файлов, например `src/_gt/[locale].json`.

3. Добавьте функцию `loadTranslations` и подключите плагин рядом с vue-i18n:

   ```ts title="src/main.ts"
   import { createApp } from 'vue';
   import { createGT, type LoadTranslations } from 'gt-vue';
   import App from './App.vue';
   import i18n from './i18n'; // ваш существующий экземпляр createI18n

   const loadTranslations: LoadTranslations = async (locale) => {
     try {
       return (await import(`./_gt/${locale}.json`)).default;
     } catch {
       return {};
     }
   };

   createApp(App)
     .use(i18n)
     .use(createGT({ defaultLocale: 'en', loadTranslations }))
     .mount('#app');
   ```

4. Войдите с помощью [`npx gt login`](/docs/cli/reference/commands/login) и укажите идентификатор проекта.

Плагин для Vite gt-vue не нужен: при запуске [`npx gt translate`](/docs/cli/reference/commands/translate) CLI сам находит [`<T>`](/docs/vue/reference/components/t) и [`useGT`](/docs/vue/reference/composables/use-gt) в файлах `.vue`.

## Шаг 2: Сохраняйте единую активную локаль

Используйте gt-vue в качестве переключателя языка и передавайте его локаль в vue-i18n, чтобы ещё не мигрированные компоненты переключались вместе с ним:

```vue title="src/App.vue"
<script setup lang="ts">
import { watchEffect } from 'vue';
import { useI18n } from 'vue-i18n';
import { useLocale } from 'gt-vue';

const gtLocale = useLocale();
const { locale } = useI18n({ useScope: 'global' });

watchEffect(() => {
  locale.value = gtLocale.value;
});
</script>
```

Замените меню выбора языка элементом управления, который вызывает [`useSetLocale`](/docs/vue/reference/composables/use-set-locale). При использовании [`createGT`](/docs/vue/reference/functions/create-gt) при переключении загружаются переводы для новой локали и выполняется повторный рендеринг без перезагрузки страницы, а gt-vue сохраняет выбранную локаль в cookie-файле `generaltranslation.locale`.

## Шаг 3: Переносите компоненты по одному

Скопируйте текст на исходном языке из файла сообщений в шаблон. Было:

```json title="src/locales/en.json"
{
  "greeting": "Hello, {name}!",
  "unread": "You have no messages | You have {count} message | You have {count} messages",
  "inbox": "Inbox"
}
```

```vue title="src/components/InboxHeader.vue"
<script setup lang="ts">
import { useI18n } from 'vue-i18n';
defineProps<{ name: string; count: number }>();
const { t } = useI18n();
</script>

<template>
  <h1>{{ t('inbox') }}</h1>
  <p>{{ t('greeting', { name }) }}</p>
  <p>{{ t('unread', count) }}</p>
</template>
```

После:

```vue title="src/components/InboxHeader.vue"
<script setup lang="ts">
import { computed } from 'vue';
import { T, Var, Num, Plural, useGT } from 'gt-vue';
defineProps<{ name: string; count: number }>();

const gt = useGT();
const title = computed(() => gt('Inbox')); // computed сохраняет реактивность при смене локали
</script>

<template>
  <h1>{{ title }}</h1>
  <T>
    <p>Hello, <Var>{{ name }}</Var>!</p>
    <p>
      <Plural :n="count">
        <template #zero>You have no messages</template>
        <template #singular>You have <Num :value="count" /> message</template>
        <template #plural>You have <Num :value="count" /> messages</template>
      </Plural>
    </p>
  </T>
</template>
```

На основе слотов `singular` и `plural` General Translation генерирует формы, которые нужны каждому языку перевода (например, `few` и `many` для русского), а [`<Plural>`](/docs/vue/reference/components/plural) выбирает подходящую с помощью `Intl.PluralRules`; при синтаксисе с вертикальной чертой в vue-i18n для таких языков требуется пользовательское правило обработки форм множественного числа. Слот `zero` сохраняет вашу формулировку для пустого почтового ящика. Используйте [`useGT`](/docs/vue/reference/composables/use-gt) для статических строк, например заголовков и плейсхолдеров, а любое предложение со значением, известным только во время выполнения, оборачивайте в [`<T>`](/docs/vue/reference/components/t) вместе с [`<Var>`](/docs/vue/reference/components/var). После каждого пакета компонентов запускайте [`npx gt translate`](/docs/cli/reference/commands/translate) и проверяйте все локали.

## Что происходит с существующими переводами?

Компоненты, которые вы ещё не перенесли, по-прежнему выполняют рендеринг проверенных сообщений vue-i18n, поэтому поэтапная миграция затрагивает только те экраны, с которыми вы работаете. gt-vue определяет переводы по исходному содержимому, а не по ключу сообщения, поэтому для текста, перенесённого в [`<T>`](/docs/vue/reference/components/t) или [`useGT`](/docs/vue/reference/composables/use-gt), [`npx gt translate`](/docs/cli/reference/commands/translate) сгенерирует новые переводы, используя окружающий шаблон в качестве контекста. Glossary и пользовательские промпты [контекстной группы](/docs/platform/dashboard/guides/defining-context-for-translations) помогают сохранить вашу терминологию и тон. После этого рецензенты могут поправить любые формулировки в [панели управления](/docs/platform/dashboard/guides/reviewing-translations).

## Шаг 4: Удалите vue-i18n

Когда поиск по `$t(`, `useI18n`, `<i18n-t` и `vue-i18n` больше ничего не находит, удалите настройку `createI18n`, файлы сообщений, синхронизацию локали и зависимость `vue-i18n`. Затем добавьте [`npx gt translate`](/docs/cli/reference/commands/translate) в процесс сборки или в [CI](/kb/translations-in-ci), чтобы новые тексты попадали в каждый релиз уже переведёнными.

## Частые вопросы

### Поддерживает ли gt-vue Nuxt?

У gt-vue нет модуля для Nuxt, и, в отличие от `@nuxtjs/i18n`, он не предоставляет локализованные маршруты, теги hreflang и определение языка браузера. При этом CLI сканирует папки `pages/` и `layouts/` в Nuxt, а [`createGT`](/docs/vue/reference/functions/create-gt) поддерживает рендеринг на сервере, если создавать отдельный плагин для каждого запроса.

### Поддерживает ли gt-vue ключи сообщений?

Нет. gt-vue переводит текст, встроенный в [`<T>`](/docs/vue/reference/components/t) и [`useGT`](/docs/vue/reference/composables/use-gt). Если ключи занимают центральное место в вашем рабочем процессе, оставайтесь на vue-i18n.

### Можно ли мигрировать по одному компоненту?

Да. Оба плагина могут работать в одном приложении, если у них общая активная локаль. Удалите vue-i18n, когда он перестанет где-либо использоваться.

### Является ли gt-vue бесплатным?

gt-vue распространяется по лицензии MIT и выполняет рендеринг переводов, включённых в сборку, без учётной записи. Генерация переводов с помощью General Translation [оплачивается по факту использования](https://generaltranslation.com/pricing).

## Ключевые выводы

* Запустите gt-vue параллельно с vue-i18n, переключайте языки через gt-vue и передавайте его локаль в vue-i18n до завершения миграции.
* Замените ключи `$t` встроенным текстом: используйте [`<T>`](/docs/vue/reference/components/t) вместе с [`<Var>`](/docs/vue/reference/components/var) в шаблонах, слоты `singular` и `plural` компонента [`<Plural>`](/docs/vue/reference/components/plural) — для форм множественного числа, записанных через вертикальную черту, и [`useGT`](/docs/vue/reference/composables/use-gt) внутри `computed` — для статических строк в скриптах.
* Ещё не перенесённые компоненты сохраняют проверенные сообщения vue-i18n, а перенесённый текст переводится с учётом шаблона как контекста и проходит проверку в панели управления. Если ключи сообщений или маршрутизация `@nuxtjs/i18n` играют в вашем приложении ключевую роль, оставьте vue-i18n.
* Удалите vue-i18n, когда его больше ничто не использует, а затем запускайте [`npx gt translate`](/docs/cli/reference/commands/translate) в CI.

## Related questions

- [General Translation или vue-i18n: что выбрать?](https://generaltranslation.com/ru/kb/general-translation-vs-vue-i18n.mdx): General Translation позволяет командам Vue писать исходные тексты прямо в шаблонах и создавать переводы с помощью CLI. Плагин gt-vue выполняет рендеринг этого контента с учётом локали, включая формы множественного числа и форматирование чисел. Выбирайте его, если хотите избавиться от поддержки исходных файлов с ключами; vue-i18n по-прежнему подходит командам, которые используют модуль i18n для Nuxt и уже сложившийся рабочий процесс с каталогами.
- [Как перевести приложение на Vue?](https://generaltranslation.com/ru/kb/translate-vue-app.mdx): Чтобы перевести приложение на Vue, нужно заменить каждую строку шаблона поиском по ключу для активного языка и перевести её на все языки перевода. Плагин gt-vue от General Translation переводит контент, обёрнутый в компонент `<T>`, а npx gt translate создаёт отдельный каталог для каждого языка перевода.
- [Как поддерживать переводы в актуальном состоянии при каждом развёртывании?](https://generaltranslation.com/ru/kb/translations-in-ci.mdx): Запускайте перевод как этап конвейера перед каждой сборкой для рабочей среды — тогда новые тексты попадут в то же развёртывание, что и сами изменения, уже переведёнными. В CLI gt от General Translation для этого служит команда npx gt translate, которая использует ключ API проекта и идентификатор проекта, сохранённые как секреты CI.

## Previous and next questions

- Previous question: [Как мигрировать с react-i18next на gt-react?](https://generaltranslation.com/ru/kb/migrate-from-react-i18next.mdx)
- Next question: [AI-агент для написания кода или конвейер перевода: что выбрать для автоматизации локализации?](https://generaltranslation.com/ru/kb/ai-coding-agent-vs-translation-pipeline.mdx)

## Sitemap

See the [Knowledge Base sitemap](https://generaltranslation.com/ru/kb/sitemap.md) for every article.