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

Содержание

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

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

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

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

1. 1

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

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

   bash

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

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

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

   npx intlayer init --interactive
   

   флаг --interactive необязателен. Используйте intlayer-cli init, если вы AI-агент.

   Эта команда обнаружит вашу среду и установит необходимые пакеты. Например:

   bash

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

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

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

   npm install intlayer astro-intlayer
   

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

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

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

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

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

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

   • Intlayer + React: Intlayer с React
   • Intlayer + Vue: Intlayer с Vue
   • Intlayer + Svelte: Intlayer со Svelte
   • Intlayer + Solid: Intlayer с Solid
   • Intlayer + Preact: Intlayer с Preact
10. 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
    

    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 включает автогенерируемые типы.

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

Настройка Git

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

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

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

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

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

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

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

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

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

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

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

Часто задаваемые вопросы