Спросите свой вопрос и получите сводку документа, используя эту страницу и выбранного вами поставщика 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 и современными практиками разработки.
Оно охватывает как маршрутизацию на основе конфигурации (routes.ts), так и маршрутизацию на основе файловой системы (@react-router/fs-routes).
Table of Contents
Почему Intlayer лучше альтернатив?
По сравнению с основными решениями, такими как «react-i18next» или «i18next», Intlayer — это решение, которое включает в себя встроенные оптимизации, такие как:
Intlayer оптимизирован для идеальной работы с React Router, предлагая маршрутизацию с учетом локали, промежуточное ПО для определения локали и все функции, необходимые для масштабирования интернационализации (i18n).
Вместо загрузки огромных файлов JSON на свои страницы загружайте только необходимый контент. Intlayer помогает уменьшить размер бандла и страниц до 50 %.
Определение области содержимого вашего приложения облегчает обслуживание крупномасштабных приложений. Вы можете дублировать или удалить отдельную папку функций, не утруждав себя мысленным бременем проверки всей кодовой базы контента. Кроме того, Intlayer полностью типизирован, что обеспечивает точность вашего контента.
Совместное размещение контента уменьшает контекст, необходимый для моделей большого языка (LLM). Intlayer также поставляется с набором инструментов, таких как CLI для проверки отсутствия переводов,LSP, MCP, и agent skills, чтобы сделать работу разработчика (DX) еще более удобной для агентов ИИ.
Используйте автоматизацию для перевода в своем конвейере CI/CD, используя LLM по вашему выбору за счет вашего поставщика ИИ. Intlayer также предлагает компилятор для автоматизации извлечения контента, а также веб-платформу, которая помогает переводить в фоновом режиме.
Подключение больших файлов JSON к компонентам может привести к проблемам с производительностью и реактивностью. Intlayer оптимизирует загрузку контента во время сборки (build time).
Intlayer — это больше, чем просто решение i18n. Он предоставляет автономный визуальный редактор и полный CMS, чтобы помочь вам управлять многоязычным контентом в реальном времени, упрощая сотрудничество с переводчиками, копирайтерами и другими членами команды. Контент может храниться локально и/или удаленно.
Пошаговое руководство по настройке Intlayer в приложении React Router v7
See the Config-Based Routing Template or File-System Routes Template on GitHub.
Установка зависимостей
Установите необходимые пакеты с помощью предпочитаемого менеджера пакетов:
bashКопировать кодКопировать код в буфер обмена
флаг
--interactiveне является обязательным. Используйтеintlayer-cli init, если вы являетесь ИИ-агентом.Эта команда определит вашу среду и установит необходимые пакеты. Например:
bashКопировать кодКопировать код в буфер обмена
intlayer
Основной пакет, предоставляющий инструменты интернационализации для управления конфигурацией, перевода, объявления контента, транспиляции и CLI-команд.
react-intlayer Пакет, который интегрирует Intlayer с приложением React. Он предоставляет провайдеры контекста и хуки для интернационализации в React.
vite-intlayer Включает плагин Vite для интеграции Intlayer с сборщиком Vite, а также промежуточное ПО для определения предпочтительной локали пользователя, управления куки и обработки перенаправления URL.
Конфигурация вашего проекта
Архитектура
В этой архитектуре маршруты определяются программно в
app/routes.tsс необязательными динамическими сегментами/:locale?. Локализованные страницы, макеты и объявления контента организованы в каталогеapp/:bashКопировать кодКопировать код в буфер обмена
Конфигурация
Создайте файл конфигурации
intlayer.config.tsдля объявления поддерживаемых языков вашего приложения:intlayer.config.tsКопировать кодКопировать код в буфер обмена
import { type IntlayerConfig, Locales } from "intlayer"; const config: IntlayerConfig = { internationalization: { defaultLocale: Locales.ENGLISH, locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH], }, }; export default config;Архитектура
В этой архитектуре маршруты следуют соглашениям файловой системы React Router v7 с использованием
flatRoutes, где точки (.) представляют сегменты URL, а($locale)обозначает необязательный локализованный сегмент:bashКопировать кодКопировать код в буфер обмена
Конфигурация
Создайте файл конфигурации
intlayer.config.tsдля объявления поддерживаемых языков вашего приложения:intlayer.config.tsКопировать кодКопировать код в буфер обмена
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 в консоли и многое другое. Для полного списка доступных параметров обратитесь к документации по конфигурации.
Интеграция Intlayer в вашу конфигурацию Vite
Добавьте плагин intlayer в вашу конфигурацию:
vite.config.tsКопировать кодКопировать код в буфер обмена
Плагин Vite
intlayer()используется для интеграции Intlayer с Vite. Он обеспечивает сборку файлов деклараций контента и отслеживает их в режиме разработки. Определяет переменные окружения Intlayer внутри приложения Vite. Кроме того, предоставляет алиасы для оптимизации производительности.Настройка маршрутов React Router v7
Настройте конфигурацию маршрутов с учетом локализации:
app/routes.tsКопировать кодКопировать код в буфер обмена
Set up your routing configuration to use file-system based routes with
flatRoutes:app/routes.tsКопировать кодКопировать код в буфер обмена
The
flatRoutesfunction from@react-router/fs-routesenables file-system based routing, where the file structure in theroutes/directory determines your application's routes. TheignoredRouteFilesoption ensures that Intlayer content declaration files (.content.ts, etc.) are not treated as route files.Создайте компоненты Layout
Настройте корневой layout и layout для конкретных локалей:
Корневой Layout
app/root.tsxКопировать кодКопировать код в буфер обмена
Объявите ваш контент
Создайте и управляйте объявлениями контента для хранения переводов:
app/routes/[lang]/page.content.tsКопировать кодКопировать код в буфер обмена
Ваши объявления контента могут быть определены в любом месте вашего приложения, как только они включены в директорию
contentDir(по умолчанию,./app). И соответствовать расширению файла объявления контента (по умолчанию,.content.{json,ts,tsx,js,jsx,mjs,cjs,md,mdx,yaml,yml}).Could be placed in
app/routes/($locale)._index.content.tsin case of using file-system based routing.Для получения дополнительной информации обратитесь к документации по объявлениям контента.
Создайте компоненты с поддержкой локали
Создайте компонент
LocalizedLinkдля навигации с учётом локали:app/components/localized-link.tsxКопировать кодКопировать код в буфер обмена
Если вы хотите навигировать по локализованным маршрутам, вы можете использовать хук
useLocalizedNavigate:app/hooks/useLocalizedNavigate.tsКопировать кодКопировать код в буфер обмена
Использование Intlayer на ваших страницах
Получайте доступ к вашим словарям контента по всему приложению:
Локализованная главная страница
app/routes/page.tsxКопировать кодКопировать код в буфер обмена
app/routes/($locale)._index.tsxКопировать кодКопировать код в буфер обмена
Чтобы узнать больше о хуке
useIntlayer, обратитесь к документации.Если ваше приложение уже существует, вы можете использовать Intlayer Compiler в сочетании с командой extract, чтобы преобразовать тысячи компонентов за одну секунду.
Создайте компонент переключателя локали
Создайте компонент, позволяющий пользователям менять язык:
app/components/locale-switcher.tsxКопировать кодКопировать код в буфер обмена
app/components/locale-switcher.tsxКопировать кодКопировать код в буфер обмена
Чтобы узнать больше о хуке
useLocale, обратитесь к документации.Добавление управления атрибутами HTML
Создайте хук для управления атрибутами lang и dir в HTML:
app/hooks/useI18nHTMLAttributes.tsxКопировать кодКопировать код в буфер обмена
Затем используйте его в вашем корневом компоненте:
app/routes/layout.tsxКопировать кодКопировать код в буфер обмена
Добавить middleware
Вы также можете использовать
intlayerProxyдля добавления маршрутизации на стороне сервера в ваше приложение. Этот плагин автоматически определит текущую локаль на основе URL и установит соответствующую куку локали. Если локаль не указана, плагин определит наиболее подходящую локаль на основе предпочтений языка браузера пользователя. Если локаль не обнаружена, он перенаправит на локаль по умолчанию.Обратите внимание, что для использования
intlayerProxyв production, вам необходимо переместить пакетvite-intlayerизdevDependenciesвdependencies.Начиная с Intlayer v9,
intlayerProxy()встроена непосредственно в плагинintlayer()и включена по умолчанию через опциюrouting.enableProxy(по умолчаниюtrue). Регистрация её отдельно, как показано ниже, теперь опциональна — она сохранена для обратной совместимости и для конфигураций, которым нужно контролировать порядок плагинов. Установитеrouting.enableProxy: falseдля отказа. См. примечания к выпуску v9.vite.config.tsКопировать кодКопировать код в буфер обмена
Извлечение содержимого ваших компонентов
НеобязательноЕсли у вас есть существующая кодовая база, преобразование тысяч файлов может занять много времени.
Чтобы упростить этот процесс, Intlayer предлагает компилятор / экстрактор для преобразования ваших компонентов и извлечения содержимого.
Чтобы настроить его, вы можете добавить раздел
compilerв ваш файлintlayer.config.ts: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;Запустите экстрактор для преобразования компонентов и извлечения содержимого
bashКопировать кодКопировать код в буфер обмена
Since v9, the
intlayerCompileris included in theintlayerplugin. So you don't need to add it manually.Обновите ваш
vite.config.ts, чтобы включить плагинintlayerCompiler:vite.config.tsКопировать кодКопировать код в буфер обмена
bashКопировать кодКопировать код в буфер обмена
Configure TypeScript
Intlayer uses module augmentation to get benefits of TypeScript and make your codebase stronger.
Ensure your TypeScript configuration includes the autogenerated 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:
Копировать код в буфер обмена
VS 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.
Ссылки на документацию
- Документация Intlayer
- Документация React Router v7
- Хук useIntlayer
- Хук useLocale
- Объявление контента
- Конфигурация
Это подробное руководство содержит все необходимое для интеграции Intlayer с React Router v7 для полностью интернационализированного приложения с маршрутизацией, учитывающей локаль, и поддержкой TypeScript.
Часто задаваемые вопросы
React Router v7 не поставляется со слоем сообщений, поэтому вы соединяете его с библиотекой i18n:
react-i18next/i18next: пространства имён JSON, загружаемые во время выполнения, с отдельным детектором локали для подключения к маршрутизатору.react-intlиLingui: сообщения ICU с этапом извлечения.Intlayer: контент, объявленный рядом с каждым компонентом, скомпилированный во время сборки, типизированный от начала до конца, с помощниками для маршрутизации с учётом локали, ИИ-переводом, визуальным редактором и CMS.
См. почему Intlayer и бенчмарк.
Гораздо меньше, чем при подходе на основе пространств имён, потому что страница никогда не загружает каталог, который не отображает. Разметка, отрендеренная на сервере, разрешает свой контент на сервере, и компилятор во время сборки заменяет вызовы useIntlayer точными записями словаря, которые использует компонент, поэтому неиспользуемые ключи и неиспользуемые языки отбрасываются, а динамические словари разделяют остальное по локалям. По сравнению с обычными альтернативами Intlayer сокращает размер бандла и страницы до 50%. См. оптимизацию бандла и бенчмарк.
Да, и есть два пути. Вы можете мигрировать контент постепенно с помощью руководства по миграции с react-i18next или руководства по миграции с i18next. Или вы можете полностью сохранить свой текущий API: адаптеры совместимости предоставляют точно такой же API, как react-i18next, react-intl и i18next, но обслуживаемый словарями Intlayer, поэтому меняются импорты, а код компонентов - нет.
Да. Плагин синхронизации JSON сохраняет ваши файлы /messages/{locale}/{namespace}.json как источник истины и генерирует из них словари Intlayer, в обоих направлениях. Плагин синхронизации PO делает то же самое для каталогов gettext, а файлы по локали позволяют разделить контент по языкам вместо группировки локалей в одном файле.
Нет. Запустите npx intlayer extract, и Intlayer прочитает ваши компоненты, извлечёт строки, видимые пользователю, и запишет файл .content рядом с каждым из них, так что вы просматриваете diff вместо копирования строк в каталог по одной. Шаг 12 этого руководства проводит вас через это.
Для полностью автоматизированного конвейера Компилятор Intlayer делает то же самое во время сборки: он сканирует исходный код JSX, TSX, Vue и Svelte при каждом изменении, генерирует словари и поддерживает их синхронизацию через горячую замену модулей, поэтому вручную поддерживать ключи вообще не нужно.
Стоит знать о двух ограничениях, прежде чем включать компилятор. Он работает через статический анализ, поэтому строки, существующие только во время выполнения, такие как коды ошибок API или поля CMS, остаются недоступными. И ему нужно отличать текст, видимый пользователю, от логики приложения вроде className="active" или кода статуса, что требует нескольких аннотаций в большой кодовой базе. Команда extract избегает обоих ограничений, оставляя вас в процессе.
Пять компонентов, все опциональные:
- Расширение для VS Code: переход от ключа
useIntlayerк файлу контента, который его объявляет, извлечение контента из компонента и запуск build, fill, test, push и pull из палитры команд или отдельной вкладки Intlayer. - LSP-сервер: та же осведомлённость в любом редакторе, который говорит на LSP, с переходом к определению, поиском всех ссылок, предпросмотром переведённого значения при наведении, автодополнением ключей и полей и предупреждением, когда ключ нигде не объявлен. Он также разрешает вызовы
i18next,react-i18next,next-intlиuse-intl, что помогает при миграции. - MCP-сервер: предоставляет документацию и CLI Intlayer для Cursor, VS Code, Claude Desktop, Claude Code и ChatGPT, чтобы ассистент отвечал по актуальной документации, а не гадал, и мог сам запускать команды вроде
intlayer fill. - Навыки агентов: сфокусированные навыки, такие как
intlayer-config,intlayer-cliиintlayer-content, плюс по одному на фреймворк, которые обучают агента вашей настройке маршрутизации и типам узлов контента. - Плагин ESLint:
no-raw-textпомечает жёстко закодированные строки, с дополнительными правилами для статических ключей словаря и неиспользуемого контента.
