Спросите свой вопрос и получите сводку документа, используя эту страницу и выбранного вами поставщика AI
История версий
- "Обновление использования API useIntlayer в Solid для прямого доступа к свойствам"v8.9.004.05.2026
- "Добавить команду init"v7.5.930.12.2025
- "Обновить Layout и обработать 404"v7.5.627.12.2025
- "Обновлена документация"v6.1.503.10.2025
- "Добавлено для React Router v7"v5.8.204.09.2025
Содержимое этой страницы было переведено с помощью ИИ.
Смотреть последнюю версию оригинального контента на английскомЕсли у вас есть идея по улучшению этой документации, не стесняйтесь внести свой вклад, подав запрос на вытягивание на GitHub.
Ссылка на документацию GitHubКопировать Markdown документа в буфер обмена
Переведите ваш React Router v7 с Intlayer | Интернационализация (i18n)
Это руководство демонстрирует, как интегрировать Intlayer для бесшовной интернационализации в проектах на React Router v7 с маршрутизацией, учитывающей локаль, поддержкой TypeScript и современными практиками разработки.
Table of Contents
Что такое Intlayer?
Intlayer, это инновационная, открытая библиотека интернационализации (i18n), созданная для упрощения поддержки многоязычности в современных веб-приложениях.
С помощью Intlayer вы можете:
- Легко управлять переводами с использованием декларативных словарей на уровне компонентов.
- Динамически локализовать метаданные, маршруты и контент.
- Обеспечить поддержку TypeScript с автогенерируемыми типами, улучшая автодополнение и обнаружение ошибок.
- Воспользоваться расширенными возможностями, такими как динамическое определение и переключение локали.
- Включить маршрутизацию с учетом локали с помощью системы маршрутизации на основе конфигурации React Router v7.
Пошаговое руководство по настройке Intlayer в приложении React Router v7
Шаг 1: Установка зависимостей
Установите необходимые пакеты с помощью предпочитаемого менеджера пакетов:
Копировать код в буфер обмена
npm install intlayer react-intlayernpm install vite-intlayer --save-devnpx intlayer initintlayer
Основной пакет, предоставляющий инструменты интернационализации для управления конфигурацией, перевода, объявления контента, транспиляции и CLI-команд.
react-intlayer Пакет, который интегрирует Intlayer с приложением React. Он предоставляет провайдеры контекста и хуки для интернационализации в React.
vite-intlayer Включает плагин Vite для интеграции Intlayer с сборщиком Vite, а также промежуточное ПО для определения предпочтительной локали пользователя, управления куки и обработки перенаправления URL.
Шаг 2: Конфигурация вашего проекта
Пошаговое руководство по настройке Intlayer в приложении React Router v7 с маршрутами на основе файловой системы
See Application Template on GitHub.
Создайте файл конфигурации для настройки языков вашего приложения:
Копировать код в буфер обмена
import { type IntlayerConfig, Locales } from "intlayer";
const config: IntlayerConfig = {
internationalization: {
defaultLocale: Locales.ENGLISH, // Язык по умолчанию
locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH], // Поддерживаемые языки
},
};
export default config;С помощью этого файла конфигурации вы можете настроить локализованные URL-адреса, перенаправления в middleware, имена cookie, расположение и расширение ваших деклараций контента, отключить логи Intlayer в консоли и многое другое. Для полного списка доступных параметров обратитесь к документации по конфигурации.
Шаг 3: Интеграция Intlayer в вашу конфигурацию Vite
Добавьте плагин intlayer в вашу конфигурацию:
Копировать код в буфер обмена
import { reactRouter } from "@react-router/dev/vite";import { defineConfig } from "vite";import { intlayer } from "vite-intlayer";export default defineConfig({ plugins: [reactRouter(), intlayer()],});Плагин Vite intlayer() используется для интеграции Intlayer с Vite. Он обеспечивает сборку файлов деклараций контента и отслеживает их в режиме разработки. Определяет переменные окружения Intlayer внутри приложения Vite. Кроме того, предоставляет алиасы для оптимизации производительности.
Шаг 4: Настройка маршрутов React Router v7
Настройте конфигурацию маршрутов с учетом локализации:
Копировать код в буфер обмена
import { layout, route, type RouteConfig } from "@react-router/dev/routes";export default [ route("/:lang?", "routes/page.tsx"), // Локализованная главная страница route("/:lang?/about", "routes/about/page.tsx"), // Локализованная страница "О нас"] satisfies RouteConfig;Шаг 5: Создайте компоненты Layout
Настройте корневой layout и layout для конкретных локалей:
Корневой Layout
Копировать код в буфер обмена
import { getLocaleFromPath } from "intlayer";import { IntlayerProvider } from "react-intlayer";import { data, Meta, Scripts, ScrollRestoration, useLoaderData,} from "react-router";import type { Route } from "./+types/root";// ... Unchanged App, links and ErrorBoundary codeexport async function loader({ request }: Route.LoaderArgs) { const locale = getLocaleFromPath(request.url); if (!locale) { throw data("Language not supported", { status: 404 }); } return { locale };}export function Layout({ children,}: { children: React.ReactNode } & Route.ComponentProps) { const data = useLoaderData<typeof loader>(); const { locale } = data ?? {}; return ( <html lang={locale}> <head> <meta charSet="utf-8" /> <meta content="width=device-width, initial-scale=1" name="viewport" /> <Meta /> <Links /> </head> <body> <IntlayerProvider locale={locale}>{children}</IntlayerProvider> <ScrollRestoration /> <Scripts /> </body> </html> );}Шаг 6: Объявите ваш контент
Создайте и управляйте объявлениями контента для хранения переводов:
Копировать код в буфер обмена
import { t, type Dictionary } from "intlayer";const pageContent = { key: "page", content: { title: t({ en: "Welcome to React Router v7 + Intlayer", es: "Bienvenido a React Router v7 + Intlayer", fr: "Bienvenue sur React Router v7 + Intlayer", }), description: t({ en: "Build multilingual applications with ease using React Router v7 and Intlayer.", es: "Cree aplicaciones multilingües fácilmente usando React Router v7 y Intlayer.", fr: "Créez des applications multilingues facilement avec React Router v7 et Intlayer.", }), aboutLink: t({ en: "Узнайте о нас", es: "Aprender Sobre Nosotros", fr: "En savoir plus sur nous", }), homeLink: t({ en: "Главная", es: "Inicio", fr: "Accueil", }), },} satisfies Dictionary;export default pageContent;Ваши объявления контента могут быть определены в любом месте вашего приложения, как только они включены в директориюcontentDir(по умолчанию,./app). И соответствовать расширению файла объявления контента (по умолчанию,.content.{json,ts,tsx,js,jsx,mjs,cjs}).
Для получения дополнительной информации обратитесь к документации по объявлениям контента.
Шаг 7: Создайте компоненты с поддержкой локали
Создайте компонент LocalizedLink для навигации с учётом локали:
Копировать код в буфер обмена
import type { FC } from "react";import { getLocalizedUrl, type LocalesValues } from "intlayer";import { useLocale } from "react-intlayer";import { Link, type LinkProps, type To } from "react-router";const isExternalLink = (to: string) => /^(https?:)?\/\//.test(to);// Проверяет, является ли ссылка внешнейexport const locacalizeTo = (to: To, locale: LocalesValues): To => { if (typeof to === "string") { if (isExternalLink(to)) { return to; } return getLocalizedUrl(to, locale); } if (isExternalLink(to.pathname ?? "")) { return to; } return { ...to, pathname: getLocalizedUrl(to.pathname ?? "", locale), };};// Компонент локализованной ссылки, учитывающий текущую локальexport const LocalizedLink: FC<LinkProps> = (props) => { const { locale } = useLocale(); return <Link {...props} to={locacalizeTo(props.to, locale)} />;};Если вы хотите навигировать по локализованным маршрутам, вы можете использовать хук useLocalizedNavigate:
Копировать код в буфер обмена
import { useLocale } from "react-intlayer";import { type NavigateOptions, type To, useNavigate } from "react-router";import { locacalizeTo } from "~/components/localized-link";export const useLocalizedNavigate = () => { const navigate = useNavigate(); const { locale } = useLocale(); const localizedNavigate = (to: To, options?: NavigateOptions) => { const localedTo = locacalizeTo(to, locale); navigate(localedTo, options); }; return localizedNavigate;};Шаг 8: Использование Intlayer на ваших страницах
Получайте доступ к вашим словарям контента по всему приложению:
Локализованная главная страница
Копировать код в буфер обмена
import { getIntlayer, validatePrefix } from "intlayer";import { useIntlayer } from "react-intlayer";import { data } from "react-router";import { LocaleSwitcher } from "~/components/locale-switcher";import { Navbar } from "~/components/navbar";import type { Route } from "./+types/page";export const loader = ({ params }: Route.LoaderArgs) => { const { locale } = params; const { isValid } = validatePrefix(locale); if (!isValid) { throw data("Locale not supported", { status: 404 }); }};export const meta: Route.MetaFunction = ({ params }) => { const content = getIntlayer("page", params.locale); return [ { title: content.title }, { content: content.description, name: "description" }, ];};export default function Page() { const { title, description, aboutLink } = useIntlayer("page"); return ( <div> <h1>{title}</h1> <p>{description}</p> <nav> <LocalizedLink to="/about">{aboutLink}</LocalizedLink> </nav> </div> );}Чтобы узнать больше о хуке useIntlayer, обратитесь к документации.
Если ваше приложение уже существует, вы можете использовать Intlayer Compiler в сочетании с командой extract, чтобы преобразовать тысячи компонентов за одну секунду.
Шаг 9: Создайте компонент переключателя локали
Создайте компонент, позволяющий пользователям менять язык:
Копировать код в буфер обмена
import type { FC } from "react";import { getHTMLTextDir, getLocaleName, getLocalizedUrl, getPathWithoutLocale, Locales,} from "intlayer";import { setLocaleInStorage, useIntlayer, useLocale } from "react-intlayer";import { Link, useLocation } from "react-router";export const LocaleSwitcher: FC = () => { const { localeSwitcherLabel } = useIntlayer("locale-switcher"); const { pathname } = useLocation(); const { availableLocales, locale } = useLocale(); const pathWithoutLocale = getPathWithoutLocale(pathname); return ( <ol> {availableLocales.map((localeItem) => ( <li key={localeItem}> <Link aria-current={localeItem === locale ? "page" : undefined} aria-label={`${localeSwitcherLabel.value} ${getLocaleName(localeItem)}`} onClick={() => setLocale(localeItem)} to={getLocalizedUrl(pathWithoutLocale, localeItem)} > <span> {/* Локаль - например, FR */} {localeItem} </span> <span> {/* Язык на его собственной локали - например, Français */} {getLocaleName(localeItem, locale)} </span> <span dir={getHTMLTextDir(localeItem)} lang={localeItem}> {/* Язык на текущей локали - например, Francés при установленной локали Locales.SPANISH */} {getLocaleName(localeItem)} </span> <span dir="ltr" lang={Locales.ENGLISH}> {/* Язык на английском - например, French */} {getLocaleName(localeItem, Locales.ENGLISH)} </span> </Link> </li> ))} </ol> );};Чтобы узнать больше о хуке useLocale, обратитесь к документации.
Шаг 10: Добавление управления атрибутами HTML (необязательно)
Создайте хук для управления атрибутами lang и dir в HTML:
Копировать код в буфер обмена
import { 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); }, [locale]);};Затем используйте его в вашем корневом компоненте:
Копировать код в буфер обмена
import { Outlet } from "react-router";import { IntlayerProvider } from "react-intlayer";import { useI18nHTMLAttributes } from "app/hooks/useI18nHTMLAttributes"; // импорт хукаexport default function RootLayout() { useI18nHTMLAttributes(); // вызов хука return ( <IntlayerProvider> <Outlet /> </IntlayerProvider> );}(Опционально) Шаг 1 : Извлечение содержимого ваших компонентов
Если у вас есть существующая кодовая база, преобразование тысяч файлов может занять много времени.
Чтобы упростить этот процесс, Intlayer предлагает компилятор / экстрактор для преобразования ваших компонентов и извлечения содержимого.
Чтобы настроить его, вы можете добавить раздел compiler в ваш файл intlayer.config.ts:
Копировать код в буфер обмена
import { type IntlayerConfig } from "intlayer";
const config: IntlayerConfig = {
// ... Остальная часть вашей конфигурации
compiler: {
/**
* Указывает, должен ли быть включен компилятор.
*/
enabled: true,
/**
* Определяет путь к выходным файлам
*/
output: ({ fileName, extension }) => `./${fileName}${extension}`,
/**
* Указывает, должны ли компоненты сохраняться после преобразования. Таким образом, компилятор можно запустить только один раз для преобразования приложения, а затем удалить.
*/
saveComponents: false,
/**
* Префикс ключа словаря
*/
dictionaryKeyPrefix: "",
},
};
export default config;Запустите экстрактор для преобразования компонентов и извлечения содержимого
Копировать код в буфер обмена
npx intlayer extractConfigure TypeScript
Intlayer uses module augmentation to get benefits of TypeScript and make your codebase stronger.
Ensure your TypeScript configuration includes the autogenerated types:
Копировать код в буфер обмена
{ // ... your existing configurations include: [ // ... your existing includes ".intlayer/**/*.ts", // Include the auto-generated types ],}Git Configuration
It is recommended to ignore the files generated by Intlayer. This allows you to avoid committing them to your Git repository.
To do this, you can add the following instructions to your .gitignore file:
Копировать код в буфер обмена
# Ignore the files generated by Intlayer.intlayerVS Code Extension
To improve your development experience with Intlayer, you can install the official Intlayer VS Code Extension.
Install from the VS Code Marketplace
This extension provides:
- Autocompletion for translation keys.
- Real-time error detection for missing translations.
- Inline previews of translated content.
- Quick actions to easily create and update translations.
For more details on how to use the extension, refer to the Intlayer VS Code Extension documentation.
Go Further
To go further, you can implement the visual editor or externalize your content using the CMS.
Documentation References
- Intlayer Documentation
- React Router v7 Documentation
- useIntlayer hook
- useLocale hook
- Content Declaration
- Configuration
This comprehensive guide provides everything you need to integrate Intlayer with React Router v7 for a fully internationalized application with locale-aware routing and TypeScript support.
Шаг 11: Добавьте middleware (необязательно)
Вы также можете использовать intlayerProxy для добавления маршрутизации на стороне сервера в ваше приложение. Этот плагин автоматически определит текущую локаль на основе URL и установит соответствующее cookie с локалью. Если локаль не указана, плагин определит наиболее подходящую локаль на основе языковых предпочтений браузера пользователя. Если локаль не будет обнаружена, произойдет перенаправление на локаль по умолчанию.
Обратите внимание, что для использованияintlayerProxyв продакшене необходимо переместить пакетvite-intlayerизdevDependenciesвdependencies.
Копировать код в буфер обмена
import { reactRouter } from "@react-router/dev/vite";import { defineConfig } from "vite";import { intlayer, intlayerProxy } from "vite-intlayer";export default defineConfig({ plugins: [ intlayerProxy(), // should be placed first reactRouter(), intlayer(), ],});Настройка TypeScript
Intlayer использует расширение модулей (module augmentation), чтобы использовать преимущества TypeScript и сделать ваш код более надежным.
Убедитесь, что ваша конфигурация TypeScript включает автоматически сгенерированные типы:
Копировать код в буфер обмена
{ // ... ваши существующие настройки include: [ // ... ваши существующие включения ".intlayer/**/*.ts", // Включить автоматически сгенерированные типы ],}Конфигурация Git
Рекомендуется игнорировать файлы, сгенерированные Intlayer. Это позволит избежать их коммита в ваш Git-репозиторий.
Для этого вы можете добавить следующие инструкции в ваш файл .gitignore:
Копировать код в буфер обмена
# Игнорировать файлы, сгенерированные Intlayer.intlayerРасширение VS Code
Для улучшения вашего опыта разработки с Intlayer вы можете установить официальное расширение Intlayer для VS Code.
Установить из VS Code Marketplace
Это расширение предоставляет:
- Автозаполнение ключей переводов.
- Обнаружение ошибок в реальном времени для отсутствующих переводов.
- Встроенный просмотр переведённого контента.
- Быстрые действия для простого создания и обновления переводов.
Для получения дополнительной информации о том, как использовать расширение, обратитесь к документации расширения Intlayer для VS Code.
Продвинутые возможности
Чтобы пойти дальше, вы можете реализовать визуальный редактор или вынести ваш контент, используя CMS.
Ссылки на документацию
- Документация Intlayer
- Документация React Router v7
- Хук useIntlayer
- Хук useLocale
- Объявление контента
- Конфигурация
Это подробное руководство содержит все необходимое для интеграции Intlayer с React Router v7 для полностью интернационализированного приложения с маршрутизацией, учитывающей локаль, и поддержкой TypeScript.