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

Содержание

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

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

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

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

1. 1

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

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

   bash

   Копировать содержимое

   Копировать код

   Копировать код в буфер обмена

   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. 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. 3

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

   Добавьте плагин intlayer в вашу конфигурацию. Для Vanilla JS не требуются дополнительные интеграции UI-фреймворков.

   astro.config.ts

   Копировать содержимое

   Копировать код

   Копировать код в буфер обмена

   // @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. 4

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

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

   src/app.content.ts

   Копировать содержимое

   Копировать код

   Копировать код в буфер обмена

   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,md,mdx,yaml,yml}).

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

5. 5

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

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

   src/pages/[...locale]/index.astro

   Копировать содержимое

   Копировать код

   Копировать код в буфер обмена

   ---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. 6

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

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

   src/pages/[...locale]/index.astro

   Копировать содержимое

   Копировать код

   Копировать код в буфер обмена

   <!-- серверная разметка показана в Шаге 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. 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 для генерации карты сайта, включающей все ваши локализованные маршруты.

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

8. 15

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

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

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

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

   Команда извлеченияКомпилятор Babel

   Запустите экстрактор для преобразования компонентов и извлечения содержимого

   bash

   Копировать содержимое

   Копировать код

   Копировать код в буфер обмена

   npx intlayer extract

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

   vite.config.ts

   Копировать содержимое

   Копировать код

   Копировать код в буфер обмена

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

   bash

   Копировать содержимое

   Копировать код

   Копировать код в буфер обмена

   npm run build # Или npm run dev

   ---

Настройка 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.

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

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