Обзор
Обзор SDK General Translation для Next.js
Введение
General Translation Next.js SDK — это библиотека интернационализации (i18n) с открытым исходным кодом для приложений Next.js.
Она предоставляет полный набор инструментов для интернационализации вашего приложения Next.js простым и удобным для поддержки способом, с функционалом, сопоставимым с другими популярными библиотеками i18n. Построенная поверх React SDK, она предлагает дополнительные возможности, специфичные для Next.js.
SDK можно использовать автономно, без платформы General Translation, и он ведет себя аналогично другим библиотекам i18n.
При этом он также интегрируется с нашей платформой и открывает расширенные возможности:
- Горячая перезагрузка переводов в режиме разработки
- Автоматические AI‑переводы
- Синхронизация переводов с платформой General Translation
- Нативная интеграция с нашим CDN переводов
- По требованию серверная локализация компонентов React в продакшене
Основные понятия
Есть 6 ключевых понятий, которые нужно знать об SDK.
Инициализация с помощью withGTConfig
Компонент <GTProvider>
Компонент <T>
Хук useGT
Функция msg для общих строк
(Необязательно) хук useTranslations
Инициализация с withGTConfig
Функция withGTConfig инициализирует SDK в вашем приложении Next.js.
Добавьте её в файл next.config.[js|ts], чтобы настроить SDK:
import { withGTConfig } from 'gt-next/config';
const nextConfig = {
// Ваши параметры для next.config.ts
};
export default withGTConfig(nextConfig, {
// Ваша конфигурация GT
});См. справочник по API withGTConfig для получения дополнительной информации.
Компонент <GTProvider>
Компонент <GTProvider> предоставляет приложению контекст локализации, включая текущий язык и соответствующие переводы.
import { GTProvider } from 'gt-next';
export default function RootLayout({ children }) {
return (
<html>
<body>
<GTProvider>
{children}
</GTProvider>
</body>
</html>
);
}Важно: Провайдер должен оборачивать всё приложение и располагаться как можно выше в дереве компонентов, например в корневом макете.
Провайдер нужен только для клиентских возможностей. Приложения, работающие исключительно на сервере, в нём не нуждаются, но его всё равно можно добавить.
См. справочник API по GTProvider для получения дополнительной информации.
Компонент <T>
Компонент <T> — рекомендуемый способ перевода контента в приложении.
Это React‑компонент, которым можно оборачивать любые элементы JSX; он автоматически отрисует содержимое элемента на поддерживаемом языке.
Примеры
<T>
<div>Привет, мир!</div>
</T><T>
<div>
<h1> Вот изображение </h1>
<img src="https://example.com/image.png" alt="Пример" />
</div>
</T><T>
Форматирование можно просто выполнять с помощью компонента `<T>`.
<Num>{1000}</Num>
<DateTime>{new Date()}</DateTime>
<Currency currency="USD">{1000}</Currency>
</T>Компонент <T> работает с переменными компонентами — такими как <Num>, <DateTime> и <Currency> — для динамического форматирования данных.
См. руководство по компоненту <T>, чтобы узнать о различных способах использования компонента <T>.
Хук useGT
Хук useGT — это React-хук, который можно использовать аналогично компоненту <T>, с некоторыми оговорками.
Хук возвращает функцию для перевода строк.
const t = useGT();
t('Привет, мир!');По сравнению с компонентом <T>, хук useGT обеспечивает большую гибкость в кодовой базе.
Например, если у вас сложная структура данных со вложенными строками, использовать компонент <T> будет труднее.
const t = useGT();
const data = {
title: t('Привет, мир!'),
description: t('Это описание'),
};См. руководство strings, чтобы узнать больше о хуке useGT.
Функция msg
Функция msg используется для пометки строк для перевода, которые используются в нескольких компонентах или хранятся в объектах конфигурации.
Это особенно полезно для общего содержимого, например для меток навигации, сообщений форм или любого текста, который встречается в нескольких местах вашего приложения.
// Пометьте строки для перевода
import { msg } from 'gt-next';
const navItems = [
{ label: msg('Главная'), href: '/' },
{ label: msg('О компании'), href: '/about' },
{ label: msg('Связаться'), href: '/contact' }
];// Декодируйте и используйте помеченные строки
import { useMessages } from 'gt-next';
function Navigation() {
const m = useMessages();
return (
<nav>
{navItems.map(item => (
<a key={item.href} href={item.href}>
{m(item.label)}
</a>
))}
</nav>
);
}Функция msg кодирует строки с метаданными перевода, а useMessages (или getMessages для серверных компонентов) их декодирует.
См. руководство Shared strings, чтобы узнать больше о функции msg.
Хук useTranslations
Хук useTranslations — это React‑хук, который возвращает функцию для получения перевода по заданному ключу.
const dictionary = {
hello: {
world: 'Привет, мир!',
},
};const translate = useTranslations();
translate('hello.world');Это поведение похоже на другие библиотеки для локализации, такие как react-i18next и next-intl.
Мы не рекомендуем использовать хук useTranslations в вашем приложении. Частое применение useTranslations усложнит сопровождение кодовой базы
и приведёт к росту технического долга.
Вместо этого рекомендуем использовать компонент <T> или хук useGT.
Если вы переходите с другой i18n‑библиотеки, хук useTranslations является полноценной заменой и может быть полезен для поэтапной миграции кодовой базы.
См. руководство dictionaries, чтобы узнать больше о хуке useTranslations.
См. справочник API по useTranslations для получения дополнительной информации.
Дальнейшие шаги
- Узнайте, как настроить проект Next.js с помощью SDK: Быстрый старт
- Узнайте, как переводить JSX‑контент с помощью компонента
<T>: Руководство по переводу JSX - Узнайте, как переводить строки с помощью хука
useGT: Руководство по переводу строк - Узнайте об общих строках с помощью функции
msg: Руководство по общим строкам
Насколько полезно это руководство?