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

Содержание

Что такое Intlayer?

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

С Intlayer вы можете:

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

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

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

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

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

npm install intlayer astro-intlayer vanilla-intlayernpx 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, а также промежуточное ПО (middleware) для определения предпочтительной локали пользователя, управления куки и обработки перенаправлений URL.

• vanilla-intlayer Пакет, который интегрирует Intlayer с приложениями на чистом JavaScript / TypeScript. Он предоставляет синглтон pub/sub (IntlayerClient) и хелперы на основе обратных вызовов (useIntlayer, useLocale и т. д.), чтобы любая часть ваших блоков <script> в Astro могла реагировать на изменения языка без использования UI-фреймворка.

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

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

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 в вашу конфигурацию. Для Vanilla JS не требуются дополнительные интеграции UI-фреймворков.

// @ts-checkimport { intlayer } from "astro-intlayer";import { defineConfig } from "astro/config";// https://astro.build/configexport default defineConfig({  integrations: [intlayer()],});

Плагин интеграции intlayer() используется для интеграции Intlayer с Astro. Он обеспечивает сборку файлов объявления контента и отслеживает их изменения в режиме разработки. Он определяет переменные окружения Intlayer внутри приложения Astro. Кроме того, он предоставляет псевдонимы для оптимизации производительности.

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

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

import { t, type Dictionary } from "intlayer";const appContent = {  key: "app",  content: {    greeting: t({      en: "Hello World",      fr: "Bonjour le monde",      es: "Hola mundo",      ru: "Привет, мир",    }),    description: t({      en: "Welcome to my multilingual Astro site.",      fr: "Bienvenue sur mon site Astro multilingue.",      es: "Bienvenido a mi sitio Astro multilingüe.",      ru: "Добро пожаловать на мой многоязычный сайт Astro.",    }),    switchLocale: t({      en: "Switch language:",      fr: "Changer de langue :",      es: "Cambiar idioma:",      ru: "Сменить язык:",    }),  },} satisfies Dictionary;export default appContent;

Ваши объявления контента могут быть определены в любом месте вашего приложения, если они включены в каталог contentDir (по умолчанию ./src) и соответствуют расширению файла объявления контента (по умолчанию .content.{json,ts,tsx,js,jsx,mjs,cjs}).

Более подробную информацию см. в документации по объявлению контента.

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

В случае Vanilla JS вся отрисовка выполняется непосредственно в файле .astro с использованием getIntlayer для начального рендеринга на стороне сервера. Блок <script> затем инициализирует vanilla-intlayer на стороне клиента для переключения языков.

---import {  getIntlayer,  getLocaleFromPath,  getLocalizedUrl,  getPrefix,  getLocaleName,  localeMap,  locales,  defaultLocale,  getPathWithoutLocale,  type LocalesValues,} from "intlayer";export const getStaticPaths = () => {  return localeMap(({ locale }) => ({    params: { locale: getPrefix(locale).localePrefix },  }));};const locale = getLocaleFromPath(Astro.url.pathname) as LocalesValues;const pathWithoutLocale = getPathWithoutLocale(Astro.url.pathname);const { greeting, description, switchLocale } = 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>{greeting}</title>    <!-- Каноническая ссылка -->    <link      rel="canonical"      href={new URL(getLocalizedUrl(Astro.url.pathname, locale), Astro.site)}    />    <!-- Ссылки Hreflang -->    {      localeMap(({ locale: mapLocale }) => (        <link          rel="alternate"          hreflang={mapLocale}          href={new URL(            getLocalizedUrl(Astro.url.pathname, mapLocale),            Astro.site          )}        />      ))    }    <link      rel="alternate"      hreflang="x-default"      href={new URL(        getLocalizedUrl(Astro.url.pathname, defaultLocale),        Astro.site      )}    />  </head>  <body>    <main>      <h1 id="greeting">{greeting}</h1>      <p id="description">{description}</p>      <div class="locale-switcher">        <span class="switcher-label">{switchLocale}</span>        <div class="locale-buttons">          {            locales.map((localeItem) => (              <a                href={localeItem === locale ? undefined : getLocalizedUrl(pathWithoutLocale, localeItem)}                class={`locale-btn ${localeItem === locale ? "active" : ""}`}                data-locale={localeItem}                aria-disabled={localeItem === locale}              >                {getLocaleName(localeItem)}              </a>            ))          }        </div>      </div>    </main>  </body></html>

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

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

Шаг 6: Добавление переключателя языков

В случае Vanilla JS в Astro переключатель языков рендерится на стороне сервера в виде обычных ссылок и гидрируется на клиенте через блок <script>. Когда пользователь нажимает на ссылку языка, vanilla-intlayer устанавливает куки языка через setLocale перед переходом по локализованному URL.

<!-- серверная разметка показана в Шаге 5 выше --><script>  import { installIntlayer, useLocale } from "vanilla-intlayer";  import { getLocaleFromPath, getLocalizedUrl, type LocalesValues } from "intlayer";  // Инициализация Intlayer на клиенте с использованием локали из текущего URL  const locale = getLocaleFromPath(window.location.pathname);  installIntlayer({ locale: locale as LocalesValues });  const { setLocale } = useLocale({    onLocaleChange: (newLocale: LocalesValues) => {      window.location.href = getLocalizedUrl(window.location.pathname, newLocale);    },  });  // Прикрепление обработчиков клика к ссылкам переключения языка  const localeLinks = document.querySelectorAll("[data-locale]");  localeLinks.forEach((link) => {    link.addEventListener("click", (e) => {      const localeValue = link.getAttribute("data-locale") as LocalesValues;      if (localeValue && localeValue !== locale) {        e.preventDefault();        setLocale(localeValue);      }    });  });</script>

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

Примечание по прогрессивному улучшению: Ссылки переключения языка работают как стандартные теги <a> даже без JavaScript. Когда JS доступен, вызов setLocale обновляет куки перед переходом, чтобы промежуточное ПО могло выполнить правильное перенаправление.

Шаг 7: Sitemap и Robots.txt

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

Sitemap

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

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

Создайте 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 для управления сканированием поисковыми системами.

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" },  });};

Настройка TypeScript

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

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

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

Настройка Git

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

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

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

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

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

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

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

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

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

(Опционально) Шаг 15: Извлечение содержимого ваших компонентов

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

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

Чтобы настроить его, вы можете добавить раздел compiler в ваш файл 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;

npx intlayer extract

import { defineConfig } from "vite";import { intlayer, intlayerCompiler } from "vite-intlayer";export default defineConfig({ plugins: [   intlayer(),   intlayerCompiler(), // Добавляет плагин компилятора ],});

npm run build # Или npm run dev

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

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