Задайте питання та отримайте підсумок документа, вказавши цю сторінку та обраного вами постачальника штучного інтелекту
Історія версій
- "Оновлення використання API useIntlayer у Solid для прямого доступу до властивостей"v8.9.004.05.2026
- "Додано команду init"v7.5.930.12.2025
- "Представлено validatePrefix та додано крок 14: Обробка сторінок 404 з локалізованими маршрутами."v7.4.011.12.2025
- "Додано крок 13: Отримання локалі у server actions (необов'язково)"v7.3.905.12.2025
- "Додано крок 13: Адаптувати Nitro"v7.2.318.11.2025
- "Виправлено значення префікса за замовчуванням, додавши функцію getPrefix, useLocalizedNavigate, LocaleSwitcher та LocalizedLink."v7.1.017.11.2025
- "Оновлено документацію"v6.5.203.10.2025
- "Додано для Tanstack Start"v5.8.109.09.2025
Вміст цієї сторінки перекладено за допомогою штучного інтелекту.
Переглянути останню версію оригінального вмісту англійськоюЯкщо у вас є ідея щодо покращення цієї документації, будь ласка, долучіться, надіславши pull request на GitHub.
Посилання на документацію на GitHubСкопіювати документацію у форматі Markdown в буфер обміну
Перекладіть ваш вебсайт Tanstack Start за допомогою Intlayer | Інтернаціоналізація (i18n)
Зміст
Цей посібник демонструє, як інтегрувати Intlayer для плавної інтернаціоналізації в проєктах Tanstack Start з маршрутизацією, що враховує локаль, підтримкою TypeScript та сучасними практиками розробки.
Чому варто обрати Intlayer, а не альтернативи?
Порівняно з основними рішеннями, такими як react-i18next або use-intl або paraglide, Intlayer — це рішення, яке має такі інтегровані оптимізації, як:
Intlayer повністю оптимізовано для TanStack Start, забезпечуючи багатомовну маршрутизацію, керування файлами cookie, генерацію карти сайту, динамічне завантаження вмісту та всі функції, необхідні для масштабування ваших зусиль з інтернаціоналізації (i18n).
Замість того, щоб завантажувати великі файли JSON на свої сторінки, завантажуйте лише необхідний вміст. Intlayer допомагає зменшити розмір бандлу і сторінок до 50%.
Організація вмісту за окремими областями (scoping) полегшує технічне обслуговування великомасштабних програм. Ви можете скопіювати або видалити окрему папку функцій без розумового навантаження перегляду всієї кодової бази вмісту. Крім того, Intlayer повністю типізований (fully typed), щоб забезпечити точність вашого вмісту.
Спільне розміщення вмісту зменшує контекст, необхідний для великих мовних моделей (LLM). Intlayer також постачається з набором інструментів, наприклад CLI для перевірки відсутніх перекладів,LSP, MCP і навички агента, щоб зробити роботу розробника (DX) ще зручнішою для агентів ШІ.
Використовуйте автоматизацію для перекладу в конвеєрі CI/CD за допомогою LLM за вашим вибором за рахунок вашого постачальника штучного інтелекту. Intlayer також пропонує компілятор для автоматизації екстракція вмісту, а також веб-платформу, щоб допомогти перекладати у фоновому режимі.
Підключення великих файлів JSON до компонентів може призвести до проблем з продуктивністю та реакцією. Intlayer оптимізує завантаження вмісту під час збірки (build time).
Більше ніж просто рішення i18n, Intlayer пропонує власний візуальний редактор і повний CMS, щоб допомогти вам керувати своїм багатомовним вмістом у реальному часі, спрощуючи співпрацю з перекладачами, копірайтерами та іншими членами команди. Контент можна зберігати локально та/або віддалено.
Покроковий посібник з налаштування Intlayer у застосунку Tanstack Start
Перегляньте Шаблон додатка на GitHub.
Створіть проект
Почніть зі створення нового проєкту TanStack Start, дотримуючись інструкції Створення нового проєкту на сайті TanStack Start.
Встановіть пакети Intlayer
Встановіть необхідні пакети, використовуючи обраний менеджер пакетів:
bashКопіювати кодСкопіюйте код у буфер обміну
intlayer
Основний пакет, який надає інструменти інтернаціоналізації для керування конфігурацією, перекладу, оголошення контенту, транспіляції та команд CLI.
react-intlayer Пакет, який інтегрує Intlayer із React-застосунком. Надає провайдери контексту та хуки для інтернаціоналізації в React.
vite-intlayer Містить плагін Vite для інтеграції Intlayer з бандлером Vite, а також middleware для визначення пріоритетної локалі користувача, керування cookie та обробки перенаправлень URL.
Конфігурація вашого проєкту
Створіть файл конфігурації, щоб налаштувати мови вашого додатка:
intlayer.config.tsКопіювати кодСкопіюйте код у буфер обміну
За допомогою цього файлу конфігурації ви можете налаштувати локалізовані URL-адреси, перенаправлення через middleware, імена cookie, розташування та розширення декларацій контенту, вимкнути логування Intlayer у консолі та інше. Для повного переліку доступних параметрів див. документацію з конфігурації.
Інтегруйте Intlayer у вашу конфігурацію Vite
Додайте плагін intlayer до вашої конфігурації:
vite.config.tsКопіювати кодСкопіюйте код у буфер обміну
Плагін Vite
intlayer()використовується для інтеграції Intlayer з Vite. Він забезпечує побудову файлів декларацій контенту та відстежує їх у режимі розробки. Він визначає змінні середовища Intlayer у Vite-застосунку. Додатково він надає аліаси для оптимізації продуктивності.Створіть кореневий Layout
Налаштуйте кореневий layout для підтримки інтернаціоналізації, використовуючи
useParamsдля визначення поточної локалі та встановлення атрибутівlangіdirна тезіhtml.src/routes/__root.tsxКопіювати кодСкопіюйте код у буфер обміну
Якщо ви хочете використовувати свій вміст в атрибуті типу
string, наприкладalt,title,href,aria-labelтощо, ви повинні викликати значення функції, наприклад:htmlКопіювати кодСкопіюйте код у буфер обміну
Створіть Locale Layout
Створіть layout, який обробляє префікс локалі та виконує валідацію.
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/localized-link.tsxКопіювати кодСкопіюйте код у буфер обміну
Цей компонент має дві цілі:
- Видалити непотрібний префікс
{-$locale}з URL. - Вставити параметр локалі в URL, щоб користувач був безпосередньо перенаправлений на локалізований маршрут.
Потім ми можемо створити хук
useLocalizedNavigateдля програмної навігації:src/hooks/useLocalizedNavigate.tsxКопіювати кодСкопіюйте код у буфер обміну
- Видалити непотрібний префікс
Використовуйте Intlayer на ваших сторінках
Отримуйте доступ до словників контенту по всьому застосунку:
Локалізована головна сторінка
src/routes/{-$locale}/index.tsxКопіювати кодСкопіюйте код у буфер обміну
Щоб дізнатися більше про хук
useIntlayer, зверніться до документації.Створіть компонент перемикача локалі
Створіть компонент, щоб дозволити користувачам змінювати мову:
src/components/locale-switcher.tsxКопіювати кодСкопіюйте код у буфер обміну
Щоб дізнатися більше про хук
useLocale, зверніться до документації.Керування атрибутами HTML
Як показано в Кроці 5, ви можете керувати атрибутами
langіdirтегаhtml, використовуючиuseParamsу вашому кореневому компоненті. Це забезпечує правильне встановлення атрибутів на сервері та клієнті.src/routes/__root.tsxКопіювати кодСкопіюйте код у буфер обміну
Додати middleware
Ви також можете використовувати
intlayerProxyдля додавання маршрутизації на стороні сервера у вашому додатку. Цей плагін автоматично визначатиме поточну локаль на основі URL і встановлюватиме відповідний cookie з локаллю. Якщо локаль не вказана, плагін визначить найбільш підходящу локаль на основі мовних налаштувань браузера користувача. Якщо локаль не буде виявлена, відбудеться перенаправлення на локаль за замовчуванням.Зверніть увагу, що щоб використовувати
intlayerProxyу production, потрібно перемістити пакетvite-intlayerзdevDependenciesдоdependencies.vite.config.tsКопіювати кодСкопіюйте код у буфер обміну
Інтернаціоналізуйте свої метадані
Ви також можете використовувати хук
getIntlayer, щоб отримувати ваші словники контенту по всьому застосунку:src/routes/{-$locale}/index.tsxКопіювати кодСкопіюйте код у буфер обміну
Отримання локалі у серверних діях
Можливо, ви захочете отримувати поточну локаль всередині серверних дій або API-ендпоїнтів. Ви можете зробити це за допомогою хелпера
getLocaleзintlayer.Ось приклад із використанням серверних функцій TanStack Start:
src/routes/{-$locale}/index.tsxКопіювати кодСкопіюйте код у буфер обміну
Керування сторінками «Не знайдено»
Коли користувач переходить на неіснуючу сторінку, ви можете відобразити власну сторінку «не знайдено», і префікс локалі може впливати на те, як ця сторінка викликається.
Розуміння обробки 404 у TanStack Router з префіксами локалі
У TanStack Router обробка сторінок 404 для локалізованих маршрутів вимагає багаторівневого підходу:
- Виділений маршрут 404: спеціальний маршрут для відображення інтерфейсу сторінки 404
- Валідація на рівні маршруту: перевіряє префікси локалі та перенаправляє некоректні на 404
- Catch-all route: Перехоплює будь-які невідповідні шляхи в межах сегмента локалі
src/routes/{-$locale}/404.tsxКопіювати кодСкопіюйте код у буфер обміну
src/routes/{-$locale}/route.tsxКопіювати кодСкопіюйте код у буфер обміну
src/routes/{-$locale}/$.tsxКопіювати кодСкопіюйте код у буфер обміну
Налаштування TypeScript
Intlayer використовує module augmentation, щоб отримати переваги TypeScript і зміцнити ваш codebase.
Переконайтеся, що ваша конфігурація TypeScript включає автогенеровані типи:
tsconfig.jsonКопіювати кодСкопіюйте код у буфер обміну
Витягніть вміст ваших компонентів
Необов'язковоЯкщо у вас є існуюча кодова база, перетворення тисяч файлів може зайняти багато часу.
Щоб спростити цей процес, 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Копіювати кодСкопіюйте код у буфер обміну
Налаштування Git
Рекомендується ігнорувати файли, згенеровані Intlayer. Це дозволить уникнути їх коміту в ваш Git-репозиторій.
Для цього ви можете додати наступні інструкції до файлу .gitignore:
Скопіюйте код у буфер обміну
Розширення VS Code
Щоб покращити досвід розробки з Intlayer, ви можете встановити офіційне Intlayer VS Code Extension.
Встановити з VS Code Marketplace
Це розширення надає:
- Автозаповнення для ключів перекладу.
- Виявлення помилок у реальному часі для відсутніх перекладів.
- Вбудовані попередні перегляди перекладеного вмісту.
- Швидкі дії для простого створення та оновлення перекладів.
Для детальнішої інформації про використання розширення зверніться до документації Intlayer VS Code Extension.
Рухатися далі
Щоб піти далі, ви можете реалізувати візуальний редактор або винести свій вміст у зовнішню систему, використовуючи CMS.