Переводите ваш сайт Astro + Lit с помощью Intlayer

Содержание

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

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

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

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

1. 1

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

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

   bash

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

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

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

   npm install intlayer astro-intlayer lit lit-intlayer @astrojs/lit
   
   npx intlayer init
   

   Если вы хотите использовать свой контент в атрибуте строки, таком как alt, title, href, aria-label и т. д., вы можете использовать значение функции, например:

   tsx

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

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

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

   <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)} />
   

   bash

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

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

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

   npm install intlayer astro-intlayer lit lit-intlayer @astrojs/lit
   

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

   • astro-intlayer Включает плагин интеграции Astro для интеграции Intlayer с бандлером Vite, middleware, разрешающее локаль каждого запроса в Astro.locals.intlayer, и хуки useIntlayer / useDictionary / useLocale. Тот же путь импорта разрешается в серверную реализацию во фронтматтере .astro и в клиентскую (на базе vanilla-intlayer) в блоках <script>.

   • lit Основной пакет Lit для создания быстрых и легких веб-компонентов.

   • lit-intlayer Пакет, который интегрирует Intlayer с приложениями Lit. Он предоставляет хуки на основе ReactiveController (useIntlayer, useLocale и т. д.) для автоматической перерисовки LitElements при смене языка.

   • @astrojs/lit Официальная интеграция Astro, которая позволяет использовать кастомные элементы Lit на страницах Astro.

2. 2

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

   Архитектура

   В этой архитектуре интеграция intlayer(), зарегистрированная в astro.config.ts, собирает ваши словари и добавляет middleware, который определяет локаль каждого запроса и предоставляет её в Astro.locals.intlayer. Страницы располагаются в сегменте rest src/pages/[...locale]/, благодаря чему локаль по умолчанию отдается без префикса, а каждая другая локаль получает собственный выделенный URL. Файлы .astro читают контент с помощью хуков useIntlayer / useLocale из astro-intlayer для серверного рендеринга, а остров Lit (src/components/lit/LitDemo.ts) получает определённую сервером локаль в качестве пропа и передаёт её в lit-intlayer для интерактивной части. Объявления контента размещаются рядом с вашими компонентами в src/.

   bash

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

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

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

   .
   ├── src
   │   ├── components
   │   │   └── lit
   │   │       ├── app.content.ts        # App content declaration
   │   │       └── LitDemo.ts            # Lit custom element (content + locale switcher)
   │   └── pages
   │       ├── [...locale]
   │       │   └── index.astro           # Localized page mounting the custom element
   │       ├── robots.txt.ts             # robots.txt endpoint
   │       └── sitemap.xml.ts            # Localized sitemap endpoint
   ├── astro.config.ts                   # Astro config with the intlayer() and lit() integrations
   ├── intlayer.config.ts
   ├── package.json
   └── tsconfig.json
   

   Конфигурация

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

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

   astro.config.ts

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

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

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

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

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

   Интеграция lit() позволяет использовать кастомные элементы Lit на страницах Astro.

4. 4

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

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

   src/components/lit/app.content.ts

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

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

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

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

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

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

   документации по объявлению контента
5. 5

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

   Используйте ваши словари в файлах .astro с помощью хуков, экспортируемых astro-intlayer. Они имеют те же сигнатуры, что и react-intlayer: useIntlayer("key") возвращает содержимое словаря, а useLocale() текущую локаль, без необходимости передавать аргументы.

   Локаль поступает из middleware astro-intlayer, которое интеграция регистрирует автоматически перед вашим собственным src/middleware.ts. Оно разрешает ее для каждого запроса, на основе префикса URL, затем сохраненной клиентом локали (cookie или заголовок), затем Accept-Language, и сохраняет в Astro.locals.intlayer. Предварительно отрендеренные страницы используют только URL, так как рендерятся один раз для каждого посетителя.

   Кастомный элемент Lit импортируется через клиентский <script> и размещается в теле страницы.

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

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

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

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

   ---
   import { useIntlayer, useLocale } from "astro-intlayer";
   import {
     getLocalizedUrl,
     getPrefix,
     localeMap,
     defaultLocale,
     getHTMLTextDir,
   } from "intlayer";
   
   export const getStaticPaths = () => {
     return localeMap(({ locale }) => ({
       params: { locale: getPrefix(locale).localePrefix },
     }));
   };
   
   // Локаль, разрешенная middleware (напр. /ru/about -> 'ru')
   const { locale } = useLocale();
   
   // Содержимое словаря 'lit-demo' для этой локали
   const { greeting } = useIntlayer("lit-demo");
   ---
   
   <!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>
       <!-- Кастомный элемент Lit - получает локаль, определенную сервером, через свойство -->
       <lit-demo locale={locale}></lit-demo>
     </body>
   </html>
   
   <script>
     import "../../components/lit/LitDemo";
   </script>
   

   Если вы хотите использовать ваше содержимое в атрибуте string, таком как alt, title, href, aria-label и т. д., вы можете использовать значение функции, например:

   tsx

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

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

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

   <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)} />
   

   Astro.locals.intlayer также предоставляет доступ к locale, defaultLocale и availableLocales в ваших собственных middleware и эндпоинтах. Передайте локаль или селектор вторым аргументом (useIntlayer("app", "fr"), useIntlayer("faq", { item: 2 })), чтобы переопределить локаль запроса для одного вызова.

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

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

6. 6

   Создание кастомного элемента Lit

   Создайте кастомный элемент Lit. Вызовите installIntlayer в connectedCallback со свойством locale, определенным сервером, чтобы инициализировать синглтон Intlayer на клиенте.

   src/components/lit/LitDemo.ts

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

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

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

   import { LitElement, html } from "lit";
   import { installIntlayer, useIntlayer, useLocale } from "lit-intlayer";
   import { getLocalizedUrl, getLocaleName, type LocalesValues } from "intlayer";
   
   class LitDemo extends LitElement {
     static properties = {
       locale: { type: String },
     };
   
     locale: LocalesValues = "en" as LocalesValues;
   
     private _content = useIntlayer(this, "lit-demo");
     private _localeCtrl = useLocale(this, {
       onLocaleChange: (newLocale: LocalesValues) => {
         window.location.href = getLocalizedUrl(
           window.location.pathname,
           newLocale
         );
       },
     });
   
     override connectedCallback() {
       super.connectedCallback();
       // Инициализация локалью, определенной сервером
       installIntlayer({ locale: this.locale as any });
     }
   
     override render() {
       const { greeting, description } = this._content;
       const {
         locale: currentLocale,
         availableLocales,
         setLocale,
       } = this._localeCtrl;
   
       return html`
         <div>
           <h1>${greeting}</h1>
           <p>${description}</p>
           <!-- Переключатель языка отрисовывается в LitElement -->
           <div class="locale-switcher">
             <span class="switcher-label">Сменить язык :</span>
             <div class="locale-buttons">
               ${availableLocales.map(
                 (localeItem) => html`
                   <button
                     class="locale-btn ${
                       localeItem === currentLocale ? "active" : ""
                     }"
                     ?disabled=${localeItem === currentLocale}
                     @click=${() => setLocale(localeItem)}
                   >
                     <span class="ls-own-name">${getLocaleName(localeItem)}</span>
                     <span class="ls-current-name"
                       >${getLocaleName(localeItem, currentLocale)}</span
                     >
                     <span class="ls-code">{localeItem.toUpperCase()}</span>
                   </button>
                 `
               )}
             </div>
           </div>
         </div>
       `;
     }
   }
   
   customElements.define("lit-demo", LitDemo);
   

   Проп locale передается со страницы Astro (определенной сервером) и используется в connectedCallback для инициализации installIntlayer, что делает её начальной локалью для всех хуков ReactiveController в элементе.

   useIntlayer регистрируется как ReactiveController. Элемент автоматически перерисовывается при смене языка - дополнительная настройка не требуется.

7. 7

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

   Переключатель языков встроен непосредственно в метод render() кастомного элемента Lit (показано в Шаге 6). Он использует useLocale из lit-intlayer и переходит по локализованному URL, когда пользователь выбирает новый язык:

   src/components/lit/LitDemo.ts

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

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

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

   // Внутри класса LitElement, после настройки useLocale (из Шага 6):
   
   private _localeCtrl = useLocale(this, {
     onLocaleChange: (newLocale: LocalesValues) => {
       // Перейти по локализованному URL при смене языка
       window.location.href = getLocalizedUrl(window.location.pathname, newLocale);
     },
   });
   
   override render() {
     const { locale: currentLocale, availableLocales, setLocale } = this._localeCtrl;
   
     return html`
       <div class="locale-switcher">
         <span class="switcher-label">Сменить язык :</span>
         <div class="locale-buttons">
           ${availableLocales.map(
             (localeItem) => html`
               <button
                 class="locale-btn ${localeItem === currentLocale ? "active" : ""}"
                 ?disabled=${localeItem === currentLocale}
                 @click=${() => setLocale(localeItem)}
               >
                 <span class="ls-own-name">${getLocaleName(localeItem)}</span>
                 <span class="ls-current-name">${getLocaleName(localeItem, currentLocale)}</span>
                 <span class="ls-code">${localeItem.toUpperCase()}</span>
               </button>
             `
           )}
         </div>
       </div>
     `;
   }
   

   Примечание по реактивности Lit: useLocale возвращает ReactiveController. При вызове setLocale контроллер автоматически планирует перерисовку - таким образом, состояние активной кнопки обновляется без ручных манипуляций с DOM.

   Примечание по сохранению состояния: Использование onLocaleChange для перенаправления через window.location.href гарантирует посещение нового языкового URL, позволяя middleware 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 },
   ];
   
   export const GET: APIRoute = async ({ site }) => {
     const xmlOutput = generateSitemap(pathList, {
       siteUrl: "https://example.com",
     });
   
     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. 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
   

   Соберите приложение, чтобы преобразовать ваши компоненты и извлечь контент

   bash

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

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

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

   npm run build # Или npm run dev
   

Настройка TypeScript

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

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

{
  compilerOptions: {
    // ...
    experimentalDecorators: true,
    useDefineForClassFields: false, // Требуется Lit для поддержки декораторов
  },
  include: [
    // ... Ваши существующие конфигурации TypeScript
    ".intlayer/**/*.ts", // Включить автогенерируемые типы
  ],
}

Настройка Git

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

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

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

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

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

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

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

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

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

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

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