Обзор

В этом руководстве описаны шаги по миграции проекта, который уже использует библиотеку i18n, на gt-react.

Мы также поделимся советами и рекомендациями, чтобы сделать миграцию максимально гладкой.

Предварительные требования

• Проект, который сейчас использует другую библиотеку i18n.
• Базовое понимание библиотеки gt-react.

Зачем мигрировать?

Существует множество причин, по которым вы можете захотеть перенести свой проект на gt-react.

Вот лишь некоторые из них:

• Никаких JSON‑файлов: Больше не нужно управлять переводами в JSON‑файлах. Всё содержимое хранится прямо в коде — там, где ему и место.
• Автоматические переводы: Генерируйте высококачественные, контекстно‑зависимые переводы с помощью нашего CLI‑инструмента. Вам больше не придётся ждать, пока переводы будут готовы.
• Эксперименты в dev: Легко экспериментируйте с переводами в процессе разработки благодаря горячей перезагрузке.

Настройка

npm i gt-react
npm i gtx-cli

yarn add gt-react
yarn add --dev gtx-cli

bun add gt-react
bun add --dev gtx-cli

pnpm add gt-react
pnpm add --save-dev gtx-cli

{
  "defaultLocale": "en",
  "locales": ["en", "fr", "es"]
}

import { GTProvider } from 'gt-react'
import config from './gt.config.json'

<GTProvider {...config}>
  <App />
</GTProvider>

Стратегии миграции

Вариант 1: Полностью перенесите весь проект

Этот вариант самый простой, но потребует наибольших изменений в коде за один раз.

После настройки проекта найдите все упоминания вашей прежней библиотеки i18n и замените их на gt-react.

Если приложение использует хуки React, например useTranslation, найдите все вхождения useTranslation в кодовой базе и замените их на useGT.

Затем замените все строковые ключи на их фактические текстовые значения.

Например, если ваш старый код выглядит так:

{
  "hello": {
    "description": "Привет, мир!"
  }
}

export default function MyComponent() {
  const { t } = useTranslation()
  return <div>{t('hello.description')}</div>
}

Вам нужно будет заменить это на:

export default function MyComponent() {
  const { t } = useGT()
  return <div>{t('Привет, мир!')}</div>
}
// ИЛИ
export default function MyComponent() {
  return <T>Привет, мир!</T>
}

Сделайте это для всех мест, где используется ваша старая библиотека i18n.

Вариант 2: Полностью перенесите проект, но продолжайте использовать словари из старой библиотеки i18n

Предположим, вы хотите перейти на gt-react, но при этом сохранить словари из старой библиотеки i18n и использовать встроенные возможности GT только для нового контента.

В этом случае вы можете сделать так же, как в Варианте 1:

Найдите все места, где используется ваша старая библиотека i18n (например, хуки useTranslation), и замените их на хуки useTranslations.

Хук useTranslations ведёт себя очень похоже на useTranslation, и вы можете использовать его тем же образом.

import { useTranslation } from 'react-i18next'
export default function MyComponent() {
  const { t } = useTranslation()
  return <div>{t('hello.description')}</div>
}

import { useTranslations } from 'gt-react'
export default function MyComponent() {
  const t = useTranslations()
  return <div>{t('hello.description')}</div>
}

С точки зрения конфигурации вам нужно создать файл dictionary.[js|ts|json] в корне проекта или в директории src. Скопируйте содержимое вашего старого словаря в этот новый файл, затем передайте его компоненту GTProvider.

import { GTProvider } from 'gt-react'
import dictionary from './dictionary.json'
import config from './gt.config.json'

<GTProvider {...config} dictionary={dictionary}>
  <App />
</GTProvider>

См. руководство по словарям для получения дополнительной информации.

Вариант 3: Пока продолжать использовать старую библиотеку i18n и перенести на gt-react только часть проекта

Этот вариант самый гибкий и потребует наименьшего объёма правок за один раз.

В таком случае можно сделать как в варианте 2, но перенести на gt-react лишь часть проекта.

Например, вы можете продолжать использовать старую библиотеку i18n для некоторых компонентов, а gt-react — для других и для нового контента.

Рекомендации по миграции

1. По возможности используйте хук useGT или компонент <T>

Где это применимо, мы рекомендуем использовать хук useGT или компонент <T>.

Это упростит дальнейшее редактирование контента и сделает кодовую базу значительно более читаемой.

2. Используйте хук useTranslations для уже существующего контента

Хук useTranslations — отличный способ продолжать работать с вашими текущими словарями.

Мы предлагаем его для упрощения миграции, но не рекомендуем использовать его для нового контента.

3. Использование ИИ

Если вы используете ИИ для миграции проекта, у нас есть файлы LLMs.txt и LLMs-full.txt, доступные по адресам:

• LLMs.txt
• LLMs-full.txt

Эти файлы содержат полное содержание этой документации, поэтому вашему инструменту на базе ИИ будет доступна вся информация, необходимая для помощи в миграции проекта.