Спросите свой вопрос и получите сводку документа, используя эту страницу и выбранного вами поставщика AI
История версий
- "Обновление использования API useIntlayer в Solid для прямого доступа к свойствам"v8.9.004.05.2026
- "Добавить команду init"v7.5.930.12.2025
- "Начальная история"v7.3.408.12.2025
Содержимое этой страницы было переведено с помощью ИИ.
Смотреть последнюю версию оригинального контента на английскомЕсли у вас есть идея по улучшению этой документации, не стесняйтесь внести свой вклад, подав запрос на вытягивание на GitHub.
Ссылка на документацию GitHubКопировать Markdown документа в буфер обмена
Переведите ваш React Router v7 (File-System Routes) с Intlayer | Интернационализация (i18n)
Это руководство демонстрирует, как интегрировать Intlayer для бесшовной интернационализации в проектах на React Router v7 с использованием маршрутизации на основе файловой системы (@react-router/fs-routes) с маршрутизацией, учитывающей локаль, поддержкой TypeScript и современными практиками разработки.
Для клиентской маршрутизации обратитесь к руководству Intlayer с React Router v7.
Table of Contents
Что такое Intlayer?
Intlayer, это инновационная, открытая библиотека интернационализации (i18n), созданная для упрощения поддержки многоязычности в современных веб-приложениях.
С помощью Intlayer вы можете:
- Легко управлять переводами с использованием декларативных словарей на уровне компонентов.
- Динамически локализовать метаданные, маршруты и контент.
- Обеспечить поддержку TypeScript с автогенерируемыми типами, улучшая автодополнение и обнаружение ошибок.
- Воспользоваться расширенными возможностями, такими как динамическое определение и переключение локали.
- Включить маршрутизацию с учетом локали с помощью системы маршрутизации на основе конфигурации React Router v7.
Пошаговое руководство по настройке Intlayer в приложении React Router v7 с маршрутами на основе файловой системы
See Application Template on GitHub.
Шаг 1: Установка зависимостей
Установите необходимые пакеты с помощью предпочитаемого менеджера пакетов:
Копировать код в буфер обмена
npm install intlayer react-intlayernpm install vite-intlayer --save-devnpm install @react-router/fs-routes --save-devnpx intlayer initintlayer
Основной пакет, предоставляющий инструменты интернационализации для управления конфигурацией, перевода, объявления контента, транспиляции и CLI-команд.
react-intlayer Пакет, который интегрирует Intlayer с приложением React. Он предоставляет провайдеры контекста и хуки для интернационализации в React.
vite-intlayer Включает плагин Vite для интеграции Intlayer с сборщиком Vite, а также промежуточное ПО для определения предпочтительной локали пользователя, управления куки и обработки перенаправления URL.
@react-router/fs-routes Пакет, который обеспечивает маршрутизацию на основе файловой системы для React Router v7.
Шаг 2: Конфигурация вашего проекта
Создайте файл конфигурации для настройки языков вашего приложения:
Копировать код в буфер обмена
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
Настройте конфигурацию маршрутов для использования маршрутов на основе файловой системы с flatRoutes:
Копировать код в буфер обмена
import type { RouteConfig } from "@react-router/dev/routes";import { flatRoutes } from "@react-router/fs-routes";import { configuration } from "intlayer";const routes: RouteConfig = flatRoutes({ // Игнорировать файлы декларации контента, чтобы они не обрабатывались как маршруты ignoredRouteFiles: configuration.content.fileExtensions.map( (fileExtension) => `**/*${fileExtension}` ),});export default routes;ФункцияflatRoutesиз@react-router/fs-routesвключает маршрутизацию на основе файловой системы, где структура файлов в директорииroutes/определяет маршруты вашего приложения. ОпцияignoredRouteFilesгарантирует, что файлы декларации контента Intlayer (.content.ts, и т.д.) не обрабатываются как файлы маршрутов.
Шаг 5: Создайте файлы маршрутов с соглашениями файловой системы
При маршрутизации на основе файловой системы вы используете плоское соглашение об именовании, где точки (.) представляют сегменты пути, а скобки () обозначают необязательные сегменты.
Создайте следующие файлы в директории app/routes/:
Структура файлов
Копировать код в буфер обмена
app/├── root.tsx # Обертка layout для маршрутов локали└──routes/ ├── ($locale)._index.tsx # Главная страница (/, /es, и т.д.) ├── ($locale)._index.content.ts # Контент главной страницы ├── ($locale).about.tsx # Страница "О нас" (/about, /es/about, и т.д.) └── ($locale).about.content.ts # Контент страницы "О нас"Соглашения об именовании:
($locale)- Необязательный динамический сегмент для параметра локали_layout- Маршрут layout, который оборачивает дочерние маршруты_index- Индексный маршрут (отображается на родительском пути).(точка) - Разделяет сегменты пути (например,($locale).about→/:locale?/about)
Компонент Layout
Копировать код в буфер обмена
import { getLocaleFromPath } from "intlayer";import { IntlayerProvider } from "react-intlayer";import { isRouteErrorResponse, Meta, Outlet, Scripts, ScrollRestoration, useLoaderData,} from "react-router";import type { Route } from "./+types/root";import "./app.css";// links and ErrorBoundary codeexport async function loader({ request }: Route.LoaderArgs) { const locale = getLocaleFromPath(request.url); 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> );}Индексная страница
Копировать код в буфер обмена
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/($locale)._index";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> );}Страница "О нас"
Копировать код в буфер обмена
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/($locale).about";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("about", params.locale); return [ { title: content.title }, { content: content.description, name: "description" }, ];};export default function AboutPage() { const { title, content, homeLink } = useIntlayer("about"); return ( <div> <h1>{title}</h1> <p>{content}</p> );}Если ваше приложение уже существует, вы можете использовать Intlayer Compiler в сочетании с командой extract, чтобы преобразовать тысячи компонентов за одну секунду.
Шаг 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: "Learn About Us", es: "Aprender Sobre Nosotros", fr: "En savoir plus sur nous", }), },} satisfies Dictionary;export default pageContent;Копировать код в буфер обмена
import { t, type Dictionary } from "intlayer";const aboutContent = { key: "about", content: { title: t({ en: "About Us", es: "Sobre Nosotros", fr: "À propos de nous", }), content: t({ en: "This is the about page content.", es: "Este es el contenido de la página de información.", fr: "Ceci est le contenu de la page à propos.", }), homeLink: t({ en: "Home", es: "Inicio", fr: "Accueil", }), },} satisfies Dictionary;export default aboutContent;Ваши объявления контента могут быть определены в любом месте вашего приложения, как только они включены в директорию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: Создайте компонент переключателя локали
Создайте компонент, позволяющий пользователям менять язык:
Копировать код в буфер обмена
import type { FC } from "react";import { getHTMLTextDir, getLocaleName, getLocalizedUrl, getPathWithoutLocale, Locales,} from "intlayer";import { 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)}`} reloadDocument // Перезагрузить страницу для применения новой локали 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, обратитесь к документации.
Шаг 9: Добавление управления атрибутами 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]);};Этот хук уже используется в компоненте layout (root.tsx), показанном в Шаге 5.
(Опционально) Шаг 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
- React Router fs-routes Documentation
- useIntlayer hook
- useLocale hook
- Content Declaration
- Configuration
This comprehensive guide provides everything you need to integrate Intlayer with React Router v7 using file-system based routing for a fully internationalized application with locale-aware routing and TypeScript support.
Шаг 10: Добавьте 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
- Документация React Router fs-routes
- Хук useIntlayer
- Хук useLocale
- Объявление контента
- Конфигурация
Это подробное руководство содержит все необходимое для интеграции Intlayer с React Router v7 с использованием маршрутизации на основе файловой системы для полностью интернационализированного приложения с маршрутизацией, учитывающей локаль, и поддержкой TypeScript.