Автор:
    Aymeric PINEAU
    Создание:2024-03-07Последнее обновление:2026-06-23

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

    ide.intlayer.org
    intlayer-astro-template.vercel.app

    Содержание

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

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

    Intlayer оптимизирован для идеальной работы с Astro, предлагая многоязычную маршрутизацию, карту сайта и все функции, необходимые для масштабирования интернационализации (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 в Astro

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

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

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

      bash
      npx intlayer init --interactive
      флаг --interactive необязателен. Используйте intlayer-cli init, если вы AI-агент.
      Эта команда обнаружит вашу среду и установит необходимые пакеты. Например:
      bash
      npm install intlayer astro-intlayer
      bash
      npm install intlayer astro-intlayer
# Опционально: добавить поддержку островов React
npm install react react-dom react-intlayer @astrojs/react

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

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

    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 в вашу конфигурацию.

      astro.config.ts
      // @ts-check

import { intlayer } from "astro-intlayer";
import { defineConfig } from "astro/config";

// https://astro.build/config
export default defineConfig({
  integrations: [intlayer()],
});
      Плагин интеграции intlayer() используется для интеграции Intlayer с Astro. Он обеспечивает сборку файлов объявления контента и отслеживает их изменения в режиме разработки. Он определяет переменные окружения Intlayer внутри приложения Astro. Кроме того, он предоставляет псевдонимы (aliases) для оптимизации производительности.

    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,md,mdx,yaml,yml}).
      Более подробную информацию см. в документации по объявлению контента.

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

      Вы можете использовать словари напрямую в файлах .astro, используя основные хелперы, экспортируемые из intlayer.

      src/pages/index.astro
      ---
import {
  getIntlayer,
  getLocaleFromPath,
  getLocalizedUrl,
  defaultLocale,
  localeMap,
  getHTMLTextDir,
  type LocalesValues,
} from "intlayer";
import LocaleSwitcher from "../components/LocaleSwitcher.astro";

// Get the current locale from the URL (e.g. /es/about -> 'es')
const locale = getLocaleFromPath(Astro.url.pathname) as LocalesValues;

// Get the content for the 'app' dictionary
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>

    <!-- Canonical link: Tells search engines which is the primary version of this page -->
    <link
      rel="canonical"
      href={new URL(getLocalizedUrl(Astro.url.pathname, locale), Astro.site)}
    />

    <!-- Hreflang: Tell Google about all localized versions -->
    {
      localeMap(({ locale: mapLocale }) => (
        <link
          rel="alternate"
          hreflang={mapLocale}
          href={new URL(
            getLocalizedUrl(Astro.url.pathname, mapLocale),
            Astro.site
          )}
        />
      ))
    }

    <!-- x-default: Fallback for users in unmatched languages -->
    <link
      rel="alternate"
      hreflang="x-default"
      href={new URL(
        getLocalizedUrl(Astro.url.pathname, defaultLocale),
        Astro.site
      )}
    />
  </head>
  <body>
    <header>
      <LocaleSwitcher />
    </header>
    <main>
      <h1>{title}</h1>
    </main>
  </body>
</html>

    6. Локализованная маршрутизация

      Создайте динамический сегмент маршрута для обслуживания локализованных страниц, например src/pages/[locale]/index.astro:

      src/pages/[locale]/index.astro
      <!-- astro -->
---
import { getIntlayer } from "intlayer";

const { title } = getIntlayer('app');
---

<h1>{title}</h1>

      Интеграция Astro добавляет middleware Vite во время разработки, которое помогает с маршрутизацией, учитывающей язык, и определениями окружения. Вы по-прежнему можете создавать ссылки между языками, используя собственную логику или вспомогательные функции, такие как getLocalizedUrl из intlayer.

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

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

      src/components/LocaleSwitcher.astro
      ---
import {
  locales,
  getLocaleName,
  getLocalizedUrl,
  getLocaleFromPath,
  getPathWithoutLocale,
  type LocalesValues,
} from "intlayer";

const locale = getLocaleFromPath(Astro.url.pathname) as LocalesValues;
const pathWithoutLocale = getPathWithoutLocale(Astro.url.pathname);
---

<nav>
  {
    locales.map((localeItem) => (
      <a
        href={getLocalizedUrl(pathWithoutLocale, localeItem)}
        data-locale={localeItem}
        aria-current={localeItem === locale ? "page" : undefined}
      >
        {getLocaleName(localeItem)}
      </a>
    ))
  }
</nav>

<script>
  import { setLocaleInStorageClient, getLocalizedUrl, type LocalesValues } from "intlayer";

  const localeLinks = document.querySelectorAll("[data-locale]");

  localeLinks.forEach((link) => {
    link.addEventListener("click", (e) => {
      const locale = link.getAttribute("data-locale") as LocalesValues;

      // Update the locale cookie
      setLocaleInStorageClient(locale);
    });
  });
</script>

<style>
  nav {
    display: flex;
    gap: 1rem;
  }
  a[aria-current="page"] {
    font-weight: bold;
    text-decoration: underline;
  }
</style>

      Примечание о сохранении настроек: Использование setLocaleInStorageClient в клиентском скрипте гарантирует, что языковые предпочтения пользователя сохраняются в куки. Это позволяет промежуточному ПО Intlayer запомнить выбор и автоматически перенаправлять пользователя на предпочитаемый язык при будущих посещениях.

    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. Продолжайте использовать ваш любимый фреймворк

      Продолжайте использовать ваш любимый фреймворк для создания вашего приложения.

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

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

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

      Чтобы упростить этот процесс, 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
      Since v9, the intlayerCompiler is included in the intlayer plugin. So you don't need to add it manually.

      Обновите ваш vite.config.ts, чтобы включить плагин intlayerCompiler:

      vite.config.ts
      import { defineConfig } from "vite";
import { intlayer, intlayerCompiler } from "vite-intlayer";

export default defineConfig({
  plugins: [
    intlayer(),
    intlayerCompiler(), // Adds the compiler plugin
  ],
});
      bash
      npm run build # Или npm run dev

    Настройка TypeScript

    Intlayer использует расширение модулей (module augmentation), чтобы воспользоваться преимуществами 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.

    Tanstack Start SolidAstro и React