Спросите свой вопрос и получите сводку документа, используя эту страницу и выбранного вами поставщика AI
История версий
- "Обновление использования API useIntlayer в Solid для прямого доступа к свойствам"v8.9.004.05.2026
- "Добавлено для Tanstack Start Solid.js"v8.5.125.03.2026
Содержимое этой страницы было переведено с помощью ИИ.
Смотреть последнюю версию оригинального контента на английскомЕсли у вас есть идея по улучшению этой документации, не стесняйтесь внести свой вклад, подав запрос на вытягивание на GitHub.
Ссылка на документацию GitHubКопировать Markdown документа в буфер обмена
Переведите ваш сайт на Tanstack Start с Solid.js, используя Intlayer | Интернационализация (i18n)
Содержание
Это руководство демонстрирует, как интегрировать Intlayer для бесшовной интернационализации в проектах Tanstack Start с Solid.js, маршрутизацией с учетом локали, поддержкой TypeScript и современными практиками разработки.
Почему Intlayer лучше альтернатив?
По сравнению с основными решениями, такими как «react-i18next» или «i18next», Intlayer — это решение, которое включает в себя встроенные оптимизации, такие как:
Intlayer оптимизирован для идеальной работы с TanStack Start и Solid, предлагая многоязычную маршрутизацию, карту сайта и все функции, необходимые для масштабирования интернационализации (i18n).
Вместо загрузки огромных файлов JSON на свои страницы загружайте только необходимый контент. Intlayer помогает уменьшить размер бандла и страниц до 50 %.
Определение области содержимого вашего приложения облегчает обслуживание крупномасштабных приложений. Вы можете дублировать или удалить отдельную папку функций, не утруждав себя мысленным бременем проверки всей кодовой базы контента. Кроме того, Intlayer полностью типизирован, что обеспечивает точность вашего контента.
Совместное размещение контента уменьшает контекст, необходимый для моделей большого языка (LLM). Intlayer также поставляется с набором инструментов, таких как CLI для проверки отсутствия переводов,LSP, MCP, и навыки агента, чтобы сделать работу разработчика (DX) еще более удобной для агентов ИИ.
Используйте автоматизацию для перевода в своем конвейере CI/CD, используя LLM по вашему выбору за счет вашего поставщика ИИ. Intlayer также предлагает компилятор для автоматизации извлечения контента, а также веб-платформу, которая помогает переводить в фоновом режиме.
Подключение больших файлов JSON к компонентам может привести к проблемам с производительностью и реактивностью. Intlayer оптимизирует загрузку контента во время сборки (build time).
Intlayer — это больше, чем просто решение i18n. Он предоставляет автономный визуальный редактор и полный CMS, чтобы помочь вам управлять многоязычным контентом в реальном времени, упрощая сотрудничество с переводчиками, копирайтерами и другими членами команды. Контент может храниться локально и/или удаленно.
Пошаговое руководство по настройке Intlayer в приложении Tanstack Start
См. Шаблон приложения на GitHub.
Создание проекта
Начните с создания нового проекта TanStack Start, следуя руководству Запуск нового проекта на сайте TanStack Start.
Установка пакетов Intlayer
Установите необходимые пакеты с помощью вашего любимого менеджера пакетов:
bashКопировать кодКопировать код в буфер обмена
intlayer
Основной пакет, предоставляющий инструменты интернационализации для управления конфигурацией, перевода, декларации контента, транспиляции и команд CLI.
solid-intlayer Пакет, интегрирующий Intlayer в приложение Solid. Он предоставляет провайдеры контекста и хуки для интернационализации Solid.
vite-intlayer Включает плагин Vite для интеграции Intlayer с сборщиком Vite, а также промежуточное ПО (middleware) для определения предпочтительной локали пользователя, управления куки и обработки перенаправлений URL.
Конфигурация вашего проекта
Создайте файл конфигурации для настройки языков вашего приложения:
intlayer.config.tsКопировать кодКопировать код в буфер обмена
Через этот файл конфигурации вы можете настроить локализованные URL-адреса, перенаправление middleware, имена куки, местоположение и расширение ваших деклараций контента, отключить логи Intlayer в консоли и многое другое. Полный список доступных параметров см. в документации по конфигурации.
Интеграция Intlayer в конфигурацию Vite
Добавьте плагин intlayer в вашу конфигурацию:
vite.config.tsКопировать кодКопировать код в буфер обмена
Плагин Vite
intlayer()используется для интеграции Intlayer с Vite. Он обеспечивает сборку файлов декларации контента и отслеживает их изменения в режиме разработки. Он определяет переменные окружения Intlayer внутри приложения Vite. Кроме того, он предоставляет псевдонимы (aliases) для оптимизации производительности.Создание корневого макета
Настройте ваш корневой макет для поддержки интернационализации, используя
useParamsдля определения текущей локали и устанавливая атрибутыlangиdirдля тегаhtml.src/routes/__root.tsxКопировать кодКопировать код в буфер обмена
Создание макета локали
Создайте макет, который обрабатывает префикс локали и выполняет валидацию. Этот макет гарантирует, что будут обрабатываться только допустимые локали.
Этот шаг является необязательным, если вам не нужно проверять префикс локали на уровне маршрута.
src/routes/{-$locale}/route.tsxКопировать кодКопировать код в буфер обмена
Здесь
{-$locale}- это динамический параметр маршрута, который заменяется текущей локалью. Такая нотация делает сегмент необязательным, позволяя ему работать с такими режимами маршрутизации, как'prefix-no-default'и т.д.Имейте в виду, что этот сегмент может вызвать проблемы, если вы используете несколько динамических сегментов в одном маршруте (например,
/{-$locale}/other-path/$anotherDynamicPath/...). Для режима'prefix-all'вы можете предпочесть заменить сегмент на$locale. Для режима'no-prefix'или'search-params'вы можете полностью удалить сегмент.Декларация вашего контента
Создавайте и управляйте декларациями контента для хранения переводов:
src/contents/page.content.tsКопировать кодКопировать код в буфер обмена
Ваши декларации контента могут быть определены в любом месте вашего приложения, при условии, что они включены в каталог
contentDir(по умолчанию./app). И соответствуют расширению файлов декларации контента (по умолчанию.content.{json,ts,tsx,js,jsx,mjs,cjs,md,mdx,yaml,yml}).Подробнее см. в документации по декларации контента.
Использование локально-зависимых компонентов и хуков
Создайте компонент
LocalizedLinkдля навигации с учетом локали:src/components/LocalizedLink.tsxКопировать кодКопировать код в буфер обмена
Этот компонент преследует две цели:
- Удаление ненужного префикса
{-$locale}из URL. - Внедрение параметра локали в URL, чтобы пользователь был напрямую перенаправлен на локализованный маршрут.
Затем мы можем создать хук
useLocalizedNavigateдля программной навигации:src/hooks/useLocalizedNavigate.tsxКопировать кодКопировать код в буфер обмена
- Удаление ненужного префикса
Использование Intlayer на ваших страницах
Получайте доступ к вашим словарям контента во всем приложении:
Локализованная домашняя страница
src/routes/{-$locale}/index.tsxКопировать кодКопировать код в буфер обмена
Если вы хотите использовать ваш контент в атрибуте типа
string, таком какalt,title,href,aria-labelи т.д., вы должны вызвать значение функции, например:htmlКопировать кодКопировать код в буфер обмена
В Solid
useIntlayerвозвращает реактивный контент (например,content). Вы можете обращаться к его свойствам напрямую.Чтобы узнать больше о хуке
useIntlayer, обратитесь к документации.Создание компонента переключения локали
Создайте компонент, позволяющий пользователям менять языки:
src/components/LocaleSwitcher.tsxКопировать кодКопировать код в буфер обмена
В Solid
localeизuseLocale- это аксессор сигнала. Используйтеlocale()(со скобками) для реактивного чтения текущего значения.Чтобы узнать больше о хуке
useLocale, обратитесь к документации.Управление HTML-атрибутами
Как показано на шаге 5, вы можете управлять атрибутами
langиdirтегаhtml, используяuseParamsв вашем корневом компоненте. Это гарантирует правильную установку атрибутов как на сервере, так и на клиенте.src/routes/__root.tsxКопировать кодКопировать код в буфер обмена
Добавление промежуточного ПО
Вы также можете использовать
intlayerProxyдля добавления серверной маршрутизации в ваше приложение. Этот плагин будет автоматически определять текущую локаль на основе URL и устанавливать соответствующую локаль в куки. Если локаль не указана, плагин будет определять наиболее подходящую локаль на основе языковых предпочтений браузера пользователя. Если локаль не обнаружена, произойдет перенаправление на локаль по умолчанию.Обратите внимание, что для использования
intlayerProxyв режиме production вам необходимо перенести пакетvite-intlayerизdevDependenciesвdependencies.vite.config.tsКопировать кодКопировать код в буфер обмена
Интернационализация ваших метаданных
Вы также можете использовать функцию
getIntlayerдля доступа к вашим словарям контента внутри загрузчикаheadдля метаданных с учетом локали:src/routes/{-$locale}/index.tsxКопировать кодКопировать код в буфер обмена
Получение локали в ваших серверных действиях
Возможно, вы захотите получить доступ к текущей локали внутри ваших серверных действий (server actions) или конечных точек API. Вы можете сделать это с помощью помощника
getLocaleизintlayer.Вот пример использования серверных функций TanStack Start:
src/routes/{-$locale}/index.tsxКопировать кодКопировать код в буфер обмена
Управление страницами 404
Когда пользователь посещает несуществующую страницу, вы можете отобразить кастомную страницу 404. Префикс локали может влиять на то, как срабатывает страница "Запрашиваемый ресурс не найден".
Понимание обработки 404 в TanStack Router с префиксами локалей
В TanStack Router обработка страниц 404 с локализованными маршрутами требует многоуровневого подхода:
- Выделенный маршрут 404: Специальный маршрут для отображения интерфейса 404.
- Валидация на уровне маршрута: Проверяет префиксы локалей и перенаправляет невалидные на 404.
- Универсальный маршрут (Catch-all): Перехватывает любые несовпадающие пути внутри сегмента локали.
src/routes/{-$locale}/404.tsxКопировать кодКопировать код в буфер обмена
src/routes/{-$locale}/route.tsxКопировать кодКопировать код в буфер обмена
src/routes/{-$locale}/$.tsxКопировать кодКопировать код в буфер обмена
Извлечение контента из ваших компонентов
НеобязательноЕсли у вас есть существующая кодовая база, трансформация тысяч файлов может занять много времени.
Чтобы облегчить этот процесс, Intlayer предлагает компилятор / экстрактор для трансформации ваших компонентов и извлечения контента.
Для настройки добавьте раздел
compilerв ваш файлintlayer.config.ts:intlayer.config.tsКопировать кодКопировать код в буфер обмена
import { type IntlayerConfig } from "intlayer"; const config: IntlayerConfig = { // ... Остальная часть конфига compiler: { /** * Указывает, должен ли компилятор быть включен. */ enabled: true, /** * Определяет путь к выходным файлам */ output: ({ fileName, extension }) => `./${fileName}${extension}`, /** * Указывает, должны ли компоненты сохраняться после трансформации. * * - Если `true`, компилятор перезапишет файл компонента на диске. Таким образом, трансформация станет постоянной, и компилятор пропустит ее при следующем запуске. Таким образом, компилятор может трансформировать приложение, а затем его можно удалить. * * - Если `false`, компилятор будет внедрять вызов функции `useIntlayer()` в код только в выходных файлах сборки, оставляя основную базу кода нетронутой. Трансформация будет выполняться только в памяти. */ saveComponents: false, /** * Префикс ключей словаря */ dictionaryKeyPrefix: "", }, }; export default config;Запустите экстрактор для трансформации ваших компонентов и извлечения контента:
bashКопировать кодКопировать код в буфер обмена
Генерация карты сайта (Sitemap)
НеобязательноIntlayer поставляется со встроенным генератором карты сайта, который поможет вам легко создать карту сайта для вашего приложения. Он учитывает локализованные маршруты и добавляет необходимые метаданные для поисковых систем.
Создаваемая Intlayer карта сайта поддерживает пространство имен
xhtml:link(Hreflang XML Extensions). В отличие от стандартных генераторов карт сайта, которые просто перечисляют прямые URL-адреса, Intlayer автоматически создает необходимые двусторонние связи между всеми языковыми версиями страницы (например,/about,/about?lang=frи/about?lang=es). Это гарантирует, что поисковые системы будут правильно индексировать и показывать нужную языковую версию соответствующей аудитории.Чтобы использовать его, вам сначала нужно настроить ваш файл
vite.config.ts, чтобы включить предварительный рендеринг (pre-rendering) для ваших локализованных маршрутов и отключить генерацию карты сайта по умолчанию в TanStack Start.vite.config.tsКопировать кодКопировать код в буфер обмена
Затем создайте маршрут
src/routes/sitemap[.]xml.ts, который использует функциюgenerateSitemap:src/routes/sitemap[.]xml.tsКопировать кодКопировать код в буфер обмена
Настройка TypeScript
Intlayer использует расширение модулей (module augmentation), чтобы задействовать преимущества TypeScript и сделать вашу кодовую базу более надежной.
Убедитесь, что ваша конфигурация TypeScript включает автогенерируемые типы:
tsconfig.jsonКопировать кодКопировать код в буфер обмена
Конфигурация Git
Рекомендуется игнорировать файлы, генерируемые Intlayer. Это позволит избежать их коммита в ваш Git-репозиторий.
Для этого добавьте следующие инструкции в ваш файл .gitignore:
Копировать код в буфер обмена
Расширение VS Code
Для улучшения процесса разработки с Intlayer вы можете установить официальное расширение Intlayer для VS Code.
Установить из VS Code Marketplace
Это расширение предоставляет:
- Автодополнение для ключей перевода.
- Обнаружение ошибок в реальном времени для отсутствующих переводов.
- Встроенная предварительный просмотр переведенного контента.
- Быстрые действия для легкого создания и обновления переводов.
Для получения дополнительной информации о том, как использовать расширение, обратитесь к документации расширения Intlayer VS Code.
Что дальше?
Для дальнейшего развития вы можете внедрить визуальный редактор или вынести ваш контент во внешнюю систему, используя CMS.