Creation:2024-03-07Last update:2026-05-31

    Переведите ваш сайт Astro + React с помощью Intlayer | Интернационализация (i18n)

    ide.intlayer.org

    Содержание

    Почему Intlayer лучше альтернатив?

    По сравнению с основными решениями, такими как astro-i18n или i18next, Intlayer представляет собой решение со встроенными оптимизациями, такими как:

    Intlayer оптимизирован для идеальной работы с Astro, предлагая многоязычную маршрутизацию, карту сайта и все функции, необходимые для масштабирования интернационализации (i18n).

    Вместо загрузки огромных файлов JSON на свои страницы загружайте только необходимый контент. Intlayer помогает уменьшить размер бандла и страниц до 50 %.

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

    Совместное размещение контента уменьшает контекст, необходимый для моделей большого языка (LLM). Intlayer также поставляется с набором инструментов, таких как CLI для проверки отсутствия переводов,LSP, MCP, и навыки агента, чтобы сделать работу разработчика (DX) еще более удобной для агентов ИИ.

    Используйте автоматизацию для перевода в своем конвейере CI/CD, используя LLM по вашему выбору за счет вашего поставщика ИИ. Intlayer также предлагает компилятор для автоматизации извлечения контента, а также веб-платформу, которая помогает переводить в фоновом режиме.

    Подключение больших файлов JSON к компонентам может привести к проблемам с производительностью и реактивностью. Intlayer оптимизирует загрузку контента во время сборки (build time).

    Intlayer — это больше, чем просто решение i18n. Он предоставляет автономный визуальный редактор и полный CMS, чтобы помочь вам управлять многоязычным контентом в реальном времени, упрощая сотрудничество с переводчиками, копирайтерами и другими членами команды. Контент может храниться локально и/или удаленно.

    Пошаговое руководство по настройке Intlayer в Astro + React

    Посмотреть Шаблон приложения на GitHub.

    1. Установка зависимостей

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

      bash
      npm install intlayer astro-intlayer react react-dom react-intlayer @astrojs/reactnpx intlayer init
      Если вы хотите использовать свой контент в атрибуте строки, таком как alt, title, href, aria-label и т. д., вы можете использовать значение функции, например:
      html
      <img src="{content.image.src.value}" alt="{content.image.value}" /><img src="{content.image.src.toString()}" alt="{content.image.toString()}" /><img src="{String(content.image.src)}" alt="{String(content.image)}" />

      • intlayer Основной пакет, предоставляющий инструменты интернационализации для управления конфигурацией, переводами, объявлением контента, транспиляцией и командами CLI.

      • astro-intlayer Включает плагин интеграции для Astro для интеграции Intlayer с бандлером Vite, а также промежуточное ПО для определения предпочтительной локали пользователя, управления куки и обработки перенаправлений URL.

      • react, react-dom Основные пакеты React, необходимые для отрисовки компонентов React в браузере.

      • react-intlayer Пакет, который интегрирует Intlayer с приложениями React. Он предоставляет IntlayerProvider, а также хуки useIntlayer и useLocale для интернационализации в React.

      • @astrojs/react Официальная интеграция Astro, которая позволяет использовать острова (islands) компонентов React.

    2. Настройка вашего проекта

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

      intlayer.config.ts
      import { Locales, type IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  internationalization: {    locales: [      Locales.ENGLISH,      Locales.FRENCH,      Locales.SPANISH,      // Ваши другие локали    ],    defaultLocale: Locales.ENGLISH,  },};export default config;
      Через этот конфигурационный файл вы можете настроить локализованные URL, перенаправления middleware, названия куки, расположение и расширение ваших объявлений контента, отключить логи Intlayer в консоли и многое другое. Полный список доступных параметров см. в документации по конфигурации.

    3. Интеграция Intlayer в конфигурацию Astro

      Добавьте плагин intlayer и интеграцию React в вашу конфигурацию.

      astro.config.ts
      // @ts-checkimport { intlayer } from "astro-intlayer";import react from "@astrojs/react";import { defineConfig } from "astro/config";// https://astro.build/configexport default defineConfig({  integrations: [intlayer(), react()],});
      Плагин интеграции intlayer() используется для интеграции Intlayer с Astro. Он обеспечивает сборку файлов объявления контента и отслеживает их изменения в режиме разработки. Он определяет переменные окружения Intlayer внутри приложения Astro. Кроме того, он предоставляет псевдонимы для оптимизации производительности.
      Интеграция react() позволяет использовать острова компонентов React через client:only="react".

    4. Объявление контента

      Создавайте и управляйте объявлениями контента для хранения переводов:

      src/app.content.tsx
      import { t, type Dictionary } from "intlayer";import type { ReactNode } from "react";const appContent = {  key: "app",  content: {    title: t({      en: "Hello World",      fr: "Bonjour le monde",      es: "Hola mundo",      ru: "Привет, мир",    }),  },} satisfies Dictionary;export default appContent;
      Ваши объявления контента могут быть определены в любом месте вашего приложения, если они включены в каталог contentDir (по умолчанию ./src) и соответствуют расширению файла объявления контента (по умолчанию .content.{json,ts,tsx,js,jsx,mjs,cjs}).
      Более подробную информацию см. в документации по объявлению контента.

    5. Использование контента в Astro

      Вы можете использовать словари напрямую в файлах .astro, используя основные хелперы, экспортируемые из intlayer. Вам также следует добавить SEO-метаданные, такие как hreflang и канонические ссылки, на каждую страницу и встроить остров React для интерактивного контента на стороне клиента.

      src/pages/[...locale]/index.astro
      ---import {  getIntlayer,  getLocaleFromPath,  getLocalizedUrl,  getHTMLTextDir,  getPrefix,  localeMap,  defaultLocale,  type LocalesValues,} from "intlayer";import { ReactIsland } from "../../components/react/ReactIsland";export const getStaticPaths = () => {  return localeMap(({ locale }) => ({    params: { locale: getPrefix(locale).localePrefix },  }));};const locale = getLocaleFromPath(Astro.url.pathname) as LocalesValues;const { title } = getIntlayer("app", locale);---<!doctype html><html lang={locale} dir={getHTMLTextDir(locale)}>  <head>    <meta charset="utf-8" />    <meta name="viewport" content="width=device-width" />    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />    <title>{title}</title>    <!-- Каноническая ссылка: Сообщает поисковым системам, какая версия страницы является основной -->    <link      rel="canonical"      href={new URL(getLocalizedUrl(Astro.url.pathname, locale), Astro.site)}    />    <!-- Hreflang: Сообщает Google о наличии всех локализованных версий -->    {      localeMap(({ locale: mapLocale }) => (        <link          rel="alternate"          hreflang={mapLocale}          href={new URL(            getLocalizedUrl(Astro.url.pathname, mapLocale),            Astro.site          )}        />      ))    }    <!-- x-default: Резервный вариант для пользователей с несовпадающими языками -->    <link      rel="alternate"      hreflang="x-default"      href={new URL(        getLocalizedUrl(Astro.url.pathname, defaultLocale),        Astro.site      )}    />  </head>  <body>    <!-- Остров React отрисовывает весь интерактивный контент, включая переключатель языков -->    <ReactIsland locale={locale} client:only="react" />  </body></html>

      Примечание по конфигурации маршрутизации: Структура каталогов, которую вы используете, зависит от настройки middleware.routing в вашем intlayer.config.ts:

      • prefix-no-default (по умолчанию): Сохраняет локаль по умолчанию в корне (без префикса) и добавляет префиксы к остальным. Используйте [...locale] для обработки всех случаев.
      • prefix-all: Все URL имеют префикс языка. Вы можете использовать стандартный [locale], если вам не нужно обрабатывать корень отдельно.
      • search-param или no-prefix: Папка локали не нужна. Локаль обрабатывается через параметры поиска или куки.

    6. Создание компонента Острова React

      Создайте компонент острова, который оборачивает ваше приложение React и получает локаль, определенную сервером:

      src/components/react/ReactIsland.tsx
      /** @jsxImportSource react */import { IntlayerProvider, useIntlayer } from "react-intlayer";import { type LocalesValues } from "intlayer";import { LocaleSwitcher } from "./LocaleSwitcher";function App() {  const { title } = useIntlayer("app");  return (    <div>      <h1>{title}</h1>      <LocaleSwitcher />    </div>  );}export function ReactIsland({ locale }: { locale: LocalesValues }) {  return (    <IntlayerProvider locale={locale}>      <App />    </IntlayerProvider>  );}
      Проп locale передается со страницы Astro (определенной сервером) в IntlayerProvider, что делает её начальной локалью для всех хуков React в дереве компонентов.

    7. Добавление переключателя языков

      Создайте React-компонент LocaleSwitcher, который считывает доступные локали и переходит по локализованному URL, когда пользователь выбирает новый язык:

      src/components/react/LocaleSwitcher.tsx
      /** @jsxImportSource react */import { useLocale } from "react-intlayer";import { getLocalizedUrl, getLocaleName, type LocalesValues } from "intlayer";export function LocaleSwitcher() {  const { locale, availableLocales, setLocale } = useLocale({    onLocaleChange: (newLocale: LocalesValues) => {      // Перейти по локализованному URL при смене языка      window.location.href = getLocalizedUrl(        window.location.pathname,        newLocale      );    },  });  return (    <div className="locale-switcher">      <span className="switcher-label">Сменить язык:</span>      <div className="locale-buttons">        {availableLocales.map((localeItem) => (          <button            key={localeItem}            onClick={() => setLocale(localeItem)}            className={`locale-btn ${localeItem === locale ? "active" : ""}`}            disabled={localeItem === locale}          >            <span className="ls-own-name">{getLocaleName(localeItem)}</span>            <span className="ls-current-name">              {getLocaleName(localeItem, locale)}            </span>            <span class="ls-code">{localeItem.toUpperCase()}</span>          </button>        ))}      </div>    </div>  );}

      Примечание по сохранению состояния: Использование onLocaleChange для перенаправления через window.location.href гарантирует посещение нового языкового URL, позволяя middleware Intlayer установить куки языка и запомнить предпочтение пользователя для будущих посещений.

      LocaleSwitcher должен отрисовываться внутри IntlayerProvider - используйте его внутри вашего компонента острова (как показано в Шаге 6).

    8. Sitemap и Robots.txt

      Intlayer предоставляет утилиты для динамического создания локализованных карт сайта и файлов robots.txt.

      Sitemap

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

      Создаваемая Intlayer карта сайта поддерживает пространство имен xhtml:link (Hreflang XML Extensions). В отличие от стандартных генераторов карт сайта, которые просто перечисляют прямые URL-адреса, Intlayer автоматически создает необходимые двусторонние связи между всеми языковыми версиями страницы (например, /about, /about?lang=fr и /about?lang=es). Это гарантирует, что поисковые системы будут правильно индексировать и показывать нужную языковую версию соответствующей аудитории.

      Создайте src/pages/sitemap.xml.ts для генерации карты сайта, включающей все ваши локализованные маршруты.

      src/pages/sitemap.xml.ts
      import type { APIRoute } from "astro";import { generateSitemap, type SitemapUrlEntry } from "intlayer";const pathList: SitemapUrlEntry[] = [  { path: "/", changefreq: "daily", priority: 1.0 },  { path: "/about", changefreq: "monthly", priority: 0.7 },];const SITE_URL = import.meta.env.SITE ?? "http://localhost:4321";export const GET: APIRoute = async ({ site }) => {  const xmlOutput = generateSitemap(pathList, { siteUrl: SITE_URL });  return new Response(xmlOutput, {    headers: { "Content-Type": "application/xml" },  });};

      Robots.txt

      Создайте src/pages/robots.txt.ts для управления сканированием поисковыми системами.

      src/pages/robots.txt.ts
      import type { APIRoute } from "astro";import { getMultilingualUrls } from "intlayer";const getAllMultilingualUrls = (urls: string[]) =>  urls.flatMap((url) => Object.values(getMultilingualUrls(url)) as string[]);const disallowedPaths = getAllMultilingualUrls(["/admin", "/private"]);export const GET: APIRoute = ({ site }) => {  const robotsTxt = [    "User-agent: *",    "Allow: /",    ...disallowedPaths.map((path) => `Disallow: ${path}`),    "",    `Sitemap: ${new URL("/sitemap.xml", site).href}`,  ].join("\n");  return new Response(robotsTxt, {    headers: { "Content-Type": "text/plain" },  });};

    9. Извлечение содержимого ваших компонентов

      Необязательно

      Если у вас есть существующая кодовая база, преобразование тысяч файлов может занять много времени.

      Чтобы упростить этот процесс, 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
      npx intlayer extract

    Настройка TypeScript

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

    Автодополнение

    Ошибка перевода

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

    tsconfig.json
    {  // ... Ваши существующие конфигурации TypeScript  include: [    // ... Ваши существующие конфигурации TypeScript    ".intlayer/**/*.ts", // Включить автогенерируемые типы  ],}

    Настройка Git

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

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

    bash
    # Игнорировать файлы, созданные Intlayer.intlayer

    Расширение для VS Code

    Для улучшения процесса разработки с помощью Intlayer вы можете установить официальное расширение Intlayer для VS Code.

    Установить из VS Code Marketplace

    Это расширение предоставляет:

    • Автодополнение для ключей перевода.
    • Обнаружение ошибок в реальном времени для отсутствующих переводов.
    • Встроенный предпросмотр переведенного контента.
    • Быстрые действия для легкого создания и обновления переводов.

    Для получения более подробной информации об использовании расширения см. документацию расширения Intlayer для VS Code.

    Дальнейшие шаги

    Вы также можете внедрить визуальный редактор или вынести ваш контент во внешнюю CMS.

    Astro
    Astro и Svelte