1. Documentation
    2. Окружающая среда
    3. Intlayer с React CRA

    Начало работы с интернационализацией (i18n) с Intlayer и React Create App

    Что такое Intlayer?

    Intlayer — это инновационная библиотека интернационализации (i18n) с открытым исходным кодом, предназначенная для упрощения многоязычной поддержки в современных веб-приложениях.

    С помощью Intlayer вы можете:

    • Легко управлять переводами с использованием декларативных словарей на уровне компонентов.
    • Динамически локализовать метаданные, маршруты и контент.
    • Обеспечить поддержку TypeScript с автогенерируемыми типами, улучшая автозаполнение и обнаружение ошибок.
    • Воспользоваться расширенными функциями, такими как динамическое определение и переключение локали.

    Пошаговая инструкция по настройке Intlayer в приложении React

    Шаг 1: Установите зависимости

    Установите необходимые пакеты с помощью npm:

    bash
    1npm install intlayer react-intlayer
    bash
    1yarn add intlayer react-intlayer
    bash
    1pnpm add intlayer react-intlayer

    Шаг 2: Конфигурация вашего проекта

    Создайте файл конфигурации для настройки языков вашего приложения:

    typescript
    1// intlayer.config.ts 2 3import { Locales, type IntlayerConfig } from "intlayer"; 4 5const config: IntlayerConfig = { 6 internationalization: { 7 locales: [ 8 Locales.ENGLISH, 9 Locales.FRENCH, 10 Locales.SPANISH, 11 // Ваши другие локали 12 ], 13 defaultLocale: Locales.ENGLISH, 14 }, 15}; 16 17export default config;

    Чтобы увидеть все доступные параметры, ознакомьтесь с документацией по конфигурации здесь.

    Шаг 3: Интеграция Intlayer в вашу конфигурацию CRA

    Измените ваши скрипты, чтобы использовать react-intlayer

    json
    1 "scripts": { 2 "build": "react-intlayer build", 3 "start": "react-intlayer start", 4 "transpile": "intlayer build" 5 },

    Примечание: скрипты react-intlayer основаны на craco. Вы также можете реализовать свою собственную настройку на основе плагина intlayer craco. Смотрите пример здесь.

    Шаг 4: Объявите ваш контент

    Создайте и управляйте вашими словарями контента:

    tsx
    1// src/app.content.tsx 2import { t, type DeclarationContent } from "intlayer"; 3import { type ReactNode } from "react"; 4 5const appContent = { 6 key: "app", 7 content: { 8 getStarted: t<ReactNode>({ 9 en: ( 10 <> 11 Редактируйте <code>src/App.tsx</code> и сохраните, чтобы перезагрузить 12 </> 13 ), 14 fr: ( 15 <> 16 Éditez <code>src/App.tsx</code> et enregistrez pour recharger 17 </> 18 ), 19 es: ( 20 <> 21 Edita <code>src/App.tsx</code> y guarda para recargar 22 </> 23 ), 24 }), 25 reactLink: { 26 href: "https://reactjs.org", 27 content: t({ 28 en: "Learn React", 29 fr: "Apprendre React", 30 es: "Aprender React", 31 }), 32 }, 33 }, 34} satisfies DeclarationContent; 35 36export default appContent;

    Смотрите, как объявить ваши файлы декларации Intlayer.

    Шаг 5: Используйте Intlayer в вашем коде

    Получите доступ к вашим словарям контента на протяжении всего вашего приложения:

    tsx
    1import logo from "./logo.svg"; 2import "./App.css"; 3import { IntlayerProvider, useIntlayer } from "react-intlayer"; 4import { LocaleSwitcher } from "./components/LangSwitcherDropDown"; 5 6function AppContent() { 7 const content = useIntlayer("app"); 8 9 return ( 10 <header className="App-header"> 11 <img src={logo} className="App-logo" alt="logo" /> 12 13 {content.getStarted} 14 <a 15 className="App-link" 16 href={content.reactLink.href.value} 17 target="_blank" 18 rel="noopener noreferrer" 19 > 20 {content.reactLink.content} 21 </a> 22 </header> 23 ); 24} 25 26function App() { 27 return ( 28 <IntlayerProvider> 29 <div className="App"> 30 {/* Чтобы правильно использовать хук useIntlayer, вы должны получать ваши данные в дочернем компоненте */} 31 <AppContent /> 32 </div> 33 <div className="absolute bottom-5 right-5 z-50"> 34 <LocaleSwitcher /> 35 </div> 36 </IntlayerProvider> 37 ); 38} 39 40export default App;

    Примечание: Если вы хотите использовать ваш контент в атрибуте string, таком как alt, title, href, aria-label и т. д., вы должны вызвать значение функции, например:

    tsx
    1<img src={content.image.src.value} alt={content.image.value} />

    (Дополнительно) Шаг 6: Измените язык вашего контента

    Чтобы изменить язык вашего контента, вы можете использовать функцию setLocale, предоставляемую хуком useLocale. Эта функция позволяет вам установить локаль приложения и обновить контент соответственно.

    tsx
    1import { Locales } from "intlayer"; 2import { useLocale } from "react-intlayer"; 3 4const LocaleSwitcher = () => { 5 const { setLocale } = useLocale(); 6 7 return ( 8 <button onClick={() => setLocale(Locales.English)}> 9 Изменить язык на английский 10 </button> 11 ); 12};

    (Дополнительно) Шаг 7: Добавьте локализованный маршрутизация в ваше приложение

    Цель этого шага — создать уникальные маршруты для каждого языка. Это полезно для SEO и SEO-дружественных URL. Пример:

    tsx
    1// /dashboard 2// /es/dashboard 3// /fr/dashboard

    По умолчанию маршруты не префиксируются для локали по умолчанию. Если вы хотите префиксировать локаль по умолчанию, вы можете установить параметр middleware.prefixDefault в true в вашей конфигурации. Смотрите документацию по конфигурации для получения дополнительной информации.

    Чтобы добавить локализованную маршрутизацию в ваше приложение, вы можете создать компонент LocaleRouter, который оборачивает маршруты вашего приложения и обрабатывает маршрутизацию на основе локали. Вот пример с использованием React Router:

    tsx
    1// Импорт необходимых зависимостей и функций 2import { Locales, getConfiguration, getPathWithoutLocale } from "intlayer"; // Утилитные функции и типы из 'intlayer' 3import { FC, PropsWithChildren } from "react"; // Типы React для функциональных компонентов и пропсов 4import { IntlayerProvider } from "react-intlayer"; // Провайдер для контекста интернационализации 5import { 6 BrowserRouter, 7 Routes, 8 Route, 9 useParams, 10 Navigate, 11 useLocation, 12} from "react-router-dom"; // Компоненты маршрутизатора для управления навигацией 13 14// Деструктуризация конфигурации из Intlayer 15const { internationalization, middleware } = getConfiguration(); 16const { locales, defaultLocale } = internationalization; 17 18/** 19 * Компонент, который обрабатывает локализацию и оборачивает дочерние элементы в соответствующий контекст локали. 20 * Он управляет определением локали на основе URL и валидацией. 21 */ 22const AppLocalized: FC<PropsWithChildren> = ({ children }) => { 23 const path = useLocation().pathname; // Получить текущий URL путь 24 const { locale } = useParams<{ locale: Locales }>(); // Извлечь параметр локали из URL 25 26 // Определить текущую локаль, возвращаясь к локали по умолчанию, если она не указана 27 const currentLocale = locale ?? defaultLocale; 28 29 // Удалить префикс локали из пути, чтобы построить базовый путь 30 const pathWithoutLocale = removeLocaleFromUrl( 31 path // Текущий URL путь 32 ); 33 34 /** 35 * Если middleware.prefixDefault равно true, локаль по умолчанию всегда должна быть префиксированной. 36 */ 37 if (middleware.prefixDefault) { 38 // Валидация локали 39 if (!locale || !locales.includes(locale)) { 40 // Перенаправление на локаль по умолчанию с обновленным путем 41 return ( 42 <Navigate 43 to={`/${defaultLocale}/${pathWithoutLocale}`} 44 replace // Заменить текущую запись истории на новую 45 /> 46 ); 47 } 48 49 // Обернуть дочерние элементы в IntlayerProvider и установить текущую локаль 50 return ( 51 <IntlayerProvider locale={currentLocale}>{children}</IntlayerProvider> 52 ); 53 } else { 54 /** 55 * Когда middleware.prefixDefault равно false, локаль по умолчанию не префиксирована. 56 * Убедитесь, что текущая локаль действительна и не является локалью по умолчанию. 57 */ 58 if ( 59 currentLocale.toString() !== defaultLocale.toString() && 60 !locales 61 .filter( 62 (locale) => locale.toString() !== defaultLocale.toString() // Исключить локаль по умолчанию 63 ) 64 .includes(currentLocale) // Проверить, находится ли текущая локаль в списке допустимых локалей 65 ) { 66 // Перенаправление к пути без префикса локали 67 return <Navigate to={pathWithoutLocale} replace />; 68 } 69 70 // Обернуть дочерние элементы в IntlayerProvider и установить текущую локаль 71 return ( 72 <IntlayerProvider locale={currentLocale}>{children}</IntlayerProvider> 73 ); 74 } 75}; 76 77/** 78 * Компонент маршрутизатора, который настраивает маршруты, специфичные для локали. 79 * Он использует React Router для управления навигацией и рендеринга локализованных компонентов. 80 */ 81export const LocaleRouter: FC<PropsWithChildren> = ({ children }) => ( 82 <BrowserRouter> 83 <Routes> 84 <Route 85 // Шаблон маршрута для захвата локали (например, /en/, /fr/) и сопоставления всех последующих путей 86 path="/:locale/*" 87 element={<AppLocalized>{children}</AppLocalized>} // Оборачивает дочерние элементы с управлением локалью 88 /> 89 90 { 91 // Если префиксирование локали по умолчанию отключено, рендерьте дочерние элементы напрямую по корневому пути 92 !middleware.prefixDefault && ( 93 <Route 94 path="*" 95 element={<AppLocalized>{children}</AppLocalized>} // Оборачивает дочерние элементы с управлением локалью 96 /> 97 ) 98 } 99 </Routes> 100 </BrowserRouter> 101);

    (Дополнительно) Шаг 8: Измените URL, когда локаль изменяется

    Чтобы изменить URL, когда локаль изменяется, вы можете использовать свойство onLocaleChange, предоставляемое хуком useLocale. Параллельно вы можете использовать хуки useLocation и useNavigate из react-router-dom, чтобы обновить путь URL.

    tsx
    1import { Locales, getLocalizedUrl } from "intlayer"; 2import { useLocale } from "react-intlayer"; 3import { useLocation, useNavigate } from "react-router-dom"; 4 5const LocaleSwitcher = () => { 6 const location = useLocation(); // Получить текущий URL путь. Пример: /fr/about 7 const navigate = useNavigate(); 8 9 const changeUrl = (locale: Locales) => { 10 // Создать URL с обновленной локалью 11 // Пример: /es/about с установленной локалью на испанский 12 const pathWithLocale = getLocalizedUrl(location.pathname, locale); 13 14 // Обновить путь URL 15 navigate(pathWithLocale); 16 }; 17 18 const { setLocale } = useLocale({ 19 onLocaleChange: changeUrl, 20 }); 21 22 return ( 23 <button onClick={() => setLocale(Locales.English)}> 24 Изменить язык на английский 25 </button> 26 ); 27};

    Настройка TypeScript

    Intlayer использует модульное расширение, чтобы получить преимущества TypeScript и сделать вашу кодовую базу более надежной.

    alt text

    alt text

    Убедитесь, что ваша конфигурация TypeScript включает авто сгенерированные типы.

    json5
    1// tsconfig.json 2 3{ 4 // ваша пользовательская конфигурация 5 include: [ 6 "src", 7 "types", // <- Включите авто сгенерированные типы 8 ], 9}

    Конфигурация Git

    Рекомендуется игнорировать файлы, сгенерированные Intlayer. Это позволяет избежать их коммита в ваш репозиторий Git.

    Для этого вы можете добавить следующие инструкции в ваш файл .gitignore:

    gitignore
    1# Игнорировать файлы, сгенерированные Intlayer 2.intlayer

    Если у вас есть идея по улучшению этой документации, не стесняйтесь внести свой вклад, подав запрос на вытягивание на GitHub.

    Ссылка на документацию GitHub
    Next.js и Page RouterIntlayer с Vite и React

    На этой странице