Спросите свой вопрос и получите сводку документа, используя эту страницу и выбранного вами поставщика AI
Интеграция сервера MCP Intlayer в ваш любимый AI-ассистент позволяет получать все документы непосредственно из ChatGPT, DeepSeek, Cursor, VSCode и т.д.
Просмотр документации сервера MCPСодержимое этой страницы было переведено с помощью ИИ.
Смотреть последнюю версию оригинального контента на английскомЕсли у вас есть идея по улучшению этой документации, не стесняйтесь внести свой вклад, подав запрос на вытягивание на GitHub.
Ссылка на документацию GitHubКопировать Markdown документа в буфер обмена
Начало работы с интернационализацией (i18n) с Intlayer и Tanstack Start
Это руководство демонстрирует, как интегрировать Intlayer для бесшовной интернационализации в проектах Tanstack Start с маршрутизацией, учитывающей локаль, поддержкой TypeScript и современными практиками разработки.
Что такое Intlayer?
Intlayer — это инновационная, открытая библиотека интернационализации (i18n), созданная для упрощения поддержки многоязычности в современных веб-приложениях.
С помощью Intlayer вы можете:
- Легко управлять переводами с использованием декларативных словарей на уровне компонентов.
- Динамически локализовать метаданные, маршруты и контент.
- Обеспечить поддержку TypeScript с автогенерируемыми типами, улучшая автодополнение и обнаружение ошибок.
- Воспользоваться расширенными возможностями, такими как динамическое определение и переключение локали.
- Включите маршрутизацию с учётом локали с помощью файловой системы маршрутизации Tanstack Start.
Пошаговое руководство по настройке Intlayer в приложении Tanstack Start
Шаг 1: Создайте проект
Начните с создания нового проекта TanStack Start, следуя руководству Start new project на сайте TanStack Start.
Шаг 2: Установите пакеты Intlayer
Установите необходимые пакеты с помощью предпочитаемого менеджера пакетов:
Копировать код в буфер обмена
npm install intlayer react-intlayernpm install vite-intlayer --save-dev
intlayer
intlayer
Основной пакет, предоставляющий инструменты интернационализации для управления конфигурацией, перевода, объявления контента, транспиляции и CLI-команд.
react-intlayer Пакет, который интегрирует Intlayer с приложением React. Он предоставляет провайдеры контекста и хуки для интернационализации в React.
vite-intlayer Включает плагин Vite для интеграции Intlayer с сборщиком Vite, а также промежуточное ПО для определения предпочтительной локали пользователя, управления cookie и обработки перенаправления URL.
Шаг 3: Конфигурация вашего проекта
Создайте файл конфигурации для настройки языков вашего приложения:
Копировать код в буфер обмена
import type { IntlayerConfig } from "intlayer";import { Locales } from "intlayer";const config: IntlayerConfig = { internationalization: { defaultLocale: Locales.ENGLISH, // Язык по умолчанию locales: [ Locales.ENGLISH, // Английский Locales.FRENCH, // Французский Locales.SPANISH, // Испанский // Ваши другие языки ], },};export default config;
Через этот конфигурационный файл вы можете настроить локализованные URL, перенаправления в middleware, имена cookie, расположение и расширение ваших деклараций контента, отключить логи Intlayer в консоли и многое другое. Для полного списка доступных параметров обратитесь к документации по конфигурации.
Шаг 4: Интеграция Intlayer в вашу конфигурацию Vite
Добавьте плагин intlayer в вашу конфигурацию:
Копировать код в буфер обмена
import { reactRouter } from "@react-router/dev/vite";import { defineConfig } from "vite";import { intlayerMiddlewarePlugin, intlayerPlugin } from "vite-intlayer";import tsconfigPaths from "vite-tsconfig-paths";export default defineConfig({ plugins: [ reactRouter(), tsconfigPaths(), intlayerPlugin(), intlayerMiddlewarePlugin(), ],});
Плагин Vite intlayerPlugin() используется для интеграции Intlayer с Vite. Он обеспечивает сборку файлов деклараций контента и их мониторинг в режиме разработки. Также он определяет переменные окружения Intlayer внутри приложения Vite. Кроме того, он предоставляет алиасы для оптимизации производительности.
Шаг 5: Создайте компоненты макета
Настройте корневой макет и макеты для конкретных локалей:
Корневой макет
Копировать код в буфер обмена
// src/routes/{-$locale}/route.tsximport { createFileRoute, Navigate, Outlet } from "@tanstack/react-router";import { configuration } from "intlayer";import { IntlayerProvider, useLocale } from "react-intlayer";import { useI18nHTMLAttributes } from "@/hooks/useI18nHTMLAttributes";export const Route = createFileRoute("/{-$locale}")({ component: LayoutComponent,});function LayoutComponent() { const { locale } = Route.useParams(); return ( <IntlayerProvider locale={locale}> <Outlet /> </IntlayerProvider> );}
Шаг 6: Объявите Ваш Контент
Создайте и управляйте декларациями контента для хранения переводов:
Копировать код в буфер обмена
import type { Dictionary } from "intlayer";import { t } from "intlayer";const appContent = { content: { links: { about: t({ en: "About", es: "Acerca de", fr: "À propos", }), home: t({ en: "Главная", es: "Inicio", fr: "Accueil", }), }, meta: { description: t({ en: "Это пример использования Intlayer с TanStack Router", es: "Este es un ejemplo de uso de Intlayer con TanStack Router", fr: "Ceci est un exemple d'utilisation d'Intlayer avec TanStack Router", }), }, title: t({ en: "Добро пожаловать в Intlayer + TanStack Router", es: "Bienvenido a Intlayer + TanStack Router", fr: "Bienvenue à Intlayer + TanStack Router", }), }, key: "app",} satisfies Dictionary;export default appContent;
Ваши объявления контента могут быть определены в любом месте вашего приложения, как только они будут включены в каталог contentDir (по умолчанию, ./app). И соответствовать расширению файла объявления контента (по умолчанию, .content.{json,ts,tsx,js,jsx,mjs,mjx,cjs,cjx}).
Для получения дополнительной информации обратитесь к документации по объявлениям контента.
Шаг 7: Создайте компоненты и хуки с поддержкой локализации
Создайте компонент LocalizedLink для навигации с учетом локали:
Копировать код в буфер обмена
// src/components/localized-link.tsx// eslint-disable-next-line no-restricted-importsimport { Link, type LinkProps } from "@tanstack/react-router";import { getLocalizedUrl } from "intlayer";import { useLocale } from "react-intlayer";type LocalizedLinkProps = { to: string;} & Omit<LinkProps, "to">;export function LocalizedLink(props: LocalizedLinkProps) { const { locale } = useLocale(); const isExternal = (to: string) => { return /^(https?:)?\/\//.test(to); }; const to = isExternal(props.to) ? props.to : getLocalizedUrl(props.to, locale); return <Link {...props} to={to as LinkProps["to"]} />;}
Создайте хук useLocalizedNavigate для программной навигации:
Копировать код в буфер обмена
// src/hooks/useLocalizedNavigate.tsx// eslint-disable-next-line no-restricted-importsimport { NavigateOptions, useNavigate } from "@tanstack/react-router";import { getLocalizedUrl } from "intlayer";import { useLocale } from "react-intlayer";type LocalizedNavigateOptions = { to: string;} & Omit<NavigateOptions, "to">;export const useLocalizedNavigate = () => { const navigate = useNavigate(); const { locale } = useLocale(); const isExternal = (to: string) => { return /^(https?:)?\/\//.test(to); }; const localizedNavigate = (options: LocalizedNavigateOptions) => { const to = isExternal(options.to) ? options.to : getLocalizedUrl(options.to, locale); navigate({ ...options, to: to as NavigateOptions["to"] }); }; return localizedNavigate;};
Шаг 8: Использование Intlayer на ваших страницах
Получайте доступ к вашим словарям контента по всему приложению:
Страница перенаправления корня
Копировать код в буфер обмена
// src/routes/page.tsximport { useLocale } from "react-intlayer";import { Navigate } from "react-router";export default function Page() { const { locale } = useLocale(); return <Navigate replace to={locale} />;}
Локализованная главная страница
Копировать код в буфер обмена
import { createFileRoute } from "@tanstack/react-router";import { getIntlayer } from "intlayer";import { useIntlayer } from "react-intlayer";import LocaleSwitcher from "@/components/locale-switcher";import { LocalizedLink } from "@/components/localized-link";import { useLocalizedNavigate } from "@/hooks/useLocalizedNavigate";export const Route = createFileRoute("/{-$locale}/")({ component: RouteComponent, head: ({ params }) => { const { locale } = params; const metaContent = getIntlayer("app", locale); return { meta: [ { title: metaContent.title }, { content: metaContent.meta.description, name: "description" }, ], }; },});function RouteComponent() { const content = useIntlayer("app"); const navigate = useLocalizedNavigate(); return ( <div className="grid place-items-center h-screen"> <div className="flex flex-col gap-4 items-center text-center"> {content.title} <LocaleSwitcher /> <div className="flex gap-4"> <a href="/">Индекс</a> <LocalizedLink to="/">{content.links.home}</LocalizedLink> <LocalizedLink to="/about">{content.links.about}</LocalizedLink> </div> <div className="flex gap-4"> <button onClick={() => navigate({ to: "/" })}> {content.links.home} </button> <button onClick={() => navigate({ to: "/about" })}> {content.links.about} </button> </div> </div> </div> );}
Чтобы узнать больше о хуке useIntlayer, обратитесь к документации.
Шаг 9: Создайте компонент переключения локали
Создайте компонент, который позволит пользователям менять язык:
Копировать код в буфер обмена
import { useLocation } from "@tanstack/react-router";import { getHTMLTextDir, getLocaleName, getLocalizedUrl, Locales,} from "intlayer";import { useIntlayer, useLocale } from "react-intlayer";export default function LocaleSwitcher() { const { pathname, searchStr } = useLocation(); const content = useIntlayer("locale-switcher"); const { availableLocales, locale, setLocale } = useLocale({ onLocaleChange: (newLocale) => { const pathWithLocale = getLocalizedUrl(pathname + searchStr, newLocale); location.replace(pathWithLocale); }, }); return ( <select aria-label={content.label.toString()} onChange={(e) => setLocale(e.target.value)} value={locale} > {availableLocales.map((localeItem) => ( <option dir={getHTMLTextDir(localeItem)} key={localeItem} lang={localeItem} value={localeItem} > {/* Пример: Français (Французский) */} {getLocaleName(localeItem, locale)} ( {getLocaleName(localeItem, Locales.ENGLISH)}) </option> ))} </select> );}
Чтобы узнать больше о хуке useLocale, обратитесь к документации.
Шаг 10: Добавление управления атрибутами HTML (необязательно)
Создайте хук для управления атрибутами lang и dir в HTML:
Копировать код в буфер обмена
// src/hooks/useI18nHTMLAttributes.tsximport { getHTMLTextDir } from "intlayer";import { useEffect } from "react";import { useLocale } from "react-intlayer";export const useI18nHTMLAttributes = () => { const { locale } = useLocale(); useEffect(() => { document.documentElement.lang = locale; document.documentElement.dir = getHTMLTextDir(locale); // установка атрибута dir для документа }, [locale]);};
Затем используйте его в вашем корневом компоненте:
Копировать код в буфер обмена
import { createFileRoute, Navigate, Outlet } from "@tanstack/react-router";import { configuration } from "intlayer";import { IntlayerProvider, useLocale } from "react-intlayer";import { useI18nHTMLAttributes } from "@/hooks/useI18nHTMLAttributes"; // импорт хукаexport const Route = createFileRoute("/{-$locale}")({ component: LayoutComponent,});function LayoutComponent() { useI18nHTMLAttributes(); // добавьте эту строку const { locale } = Route.useParams(); return ( <IntlayerProvider locale={locale}> <Outlet /> </IntlayerProvider> );}
Шаг 11: Сборка и запуск вашего приложения
Соберите словари контента и запустите ваше приложение:
Копировать код в буфер обмена
# Сборка словарей Intlayernpm run intlayer:build# Запуск сервера разработкиnpm run dev
Шаг 12: Настройка TypeScript (необязательно)
Intlayer использует расширение модулей (module augmentation), чтобы использовать преимущества TypeScript и сделать ваш код более надежным.
Убедитесь, что ваша конфигурация TypeScript включает автоматически сгенерированные типы:
Копировать код в буфер обмена
{ compilerOptions: { // ... ваши существующие настройки TypeScript }, include: [ // ... ваши существующие включения ".intlayer/**/*.ts", // Включить автоматически сгенерированные типы ],}
Конфигурация Git
Рекомендуется игнорировать файлы, сгенерированные Intlayer. Это позволит избежать их коммита в ваш репозиторий Git.
Для этого вы можете добавить следующие инструкции в ваш файл .gitignore:
Копировать код в буфер обмена
# Игнорировать файлы, сгенерированные Intlayer.intlayer
Шаг 13: Создание перенаправления (опционально)
Копировать код в буфер обмена
function LayoutComponent() { useI18nHTMLAttributes(); const { locale } = Route.useParams(); const { locale: selectedLocale } = useLocale(); const { defaultLocale } = configuration.internationalization; const { prefixDefault } = configuration.middleware; // Перенаправление на локаль по умолчанию, если в URL отсутствует локаль и prefixDefault установлен в true if (selectedLocale === defaultLocale && !locale && prefixDefault) { return <Navigate replace to={defaultLocale} />; } // Перенаправление на выбранную локаль, если локаль в URL не совпадает с выбранной локалью if (selectedLocale !== defaultLocale && !locale) { return <Navigate replace to={selectedLocale} />; } return ( <IntlayerProvider locale={locale}> <Outlet /> </IntlayerProvider> );}
Развертывание в продакшн
При развертывании вашего приложения:
Соберите ваше приложение:
bashКопировать кодКопировать код в буфер обмена
npm run build
Соберите словари Intlayer:
bashКопировать кодКопировать код в буфер обмена
npm run intlayer:build
Переместите vite-intlayer в зависимости, если используете middleware в продакшн:
bashКопировать кодКопировать код в буфер обмена
npm install vite-intlayer --save
Теперь ваше приложение будет поддерживать:
- Структуру URL: /en, /en/about, /tr, /tr/about
- Автоматическое определение локали на основе настроек браузера
- Маршрутизацию с учётом локали с использованием Tanstack Start
- Поддержку TypeScript с автогенерируемыми типами
- Серверный рендеринг с правильной обработкой локали
Расширение для VS Code
Чтобы улучшить ваш опыт разработки с Intlayer, вы можете установить официальное расширение Intlayer для VS Code.
Установить из VS Code Marketplace
Это расширение предоставляет:
- Автозаполнение ключей переводов.
- Обнаружение ошибок в реальном времени для отсутствующих переводов.
- Встроенный просмотр переведённого контента.
- Быстрые действия для удобного создания и обновления переводов.
Для получения дополнительной информации о том, как использовать расширение, обратитесь к документации по расширению Intlayer для VS Code.
Продвинутые возможности
Чтобы продвинуться дальше, вы можете реализовать визуальный редактор или вынести ваш контент, используя CMS.
Ссылки на документацию
- Документация Intlayer
- Документация Tanstack Start
- Хук useIntlayer
- Хук useLocale
- Объявление контента
- Конфигурация
Это подробное руководство содержит все необходимое для интеграции Intlayer с Tanstack Start для полностью интернационализированного приложения с маршрутизацией, учитывающей локаль, и поддержкой TypeScript.
История документации
Версия | Дата | Изменения |
---|---|---|
5.8.1 | 2025-09-09 | Добавлено для Tanstack Start |