Перекладіть свій сайт Astro + Lit за допомогою Intlayer | Інтернаціоналізація (i18n)

Зміст

Чому варто обрати Intlayer, а не альтернативи?

Порівняно з основними рішеннями, такими як astro-i18n або i18next, Intlayer — це рішення, яке має такі інтегровані оптимізації, як:

Покрокова інструкція з налаштування Intlayer в Astro + Lit

Перегляньте шаблон додатка на GitHub.

1. 1

   Встановіть залежності

   Встановіть необхідні пакети за допомогою бажаного менеджера пакетів:

   bash

   Копіювати вміст

   Копіювати код

   Скопіюйте код у буфер обміну

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

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

   • astro-intlayer Плагін інтеграції Astro для зв'язку Intlayer з бандлером Vite; він також включає middleware для визначення бажаної мови користувача, керування cookie та обробки перенаправлень URL.

   • lit Основний пакет Lit для створення швидких і легких Web Components.

   • lit-intlayer Пакет для інтеграції Intlayer у додатки Lit. Він надає хуки на основі ReactiveController (useIntlayer, useLocale тощо), щоб автоматично повідомляти LitElement про необхідність перерендерингу при зміні мови.

   • @astrojs/lit Офіційна інтеграція Astro, яка дозволяє використовувати Lit custom elements всередині сторінок Astro.

2. 2

   Налаштуйте свій проект

   Створіть конфігураційний файл, щоб визначити мови вашого додатка:

   intlayer.config.ts

   Копіювати вміст

   Копіювати код

   Скопіюйте код у буфер обміну

   import { Locales, type IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  internationalization: {    locales: [      Locales.ENGLISH,      Locales.FRENCH,      Locales.SPANISH,      Locales.UKRAINIAN,      // Ваші інші локалі    ],    defaultLocale: Locales.ENGLISH,  },};export default config;

   Через цей конфігураційний файл ви можете налаштувати локалізовані URL-адреси, перенаправлення middleware, імена cookie, розташування та розширення декларацій вмісту, вимкнути логи Intlayer у консолі та багато іншого. Повний список доступних параметрів дивіться в документації з конфігурації.

3. 3

   Інтегруйте Intlayer у вашу конфігурацію Astro

   Додайте плагін intlayer до вашої конфігурації Astro та інтеграцію Lit.

   astro.config.ts

   Копіювати вміст

   Копіювати код

   Скопіюйте код у буфер обміну

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

   Плагін інтеграції intlayer() використовується для інтеграції Intlayer з Astro. Він забезпевує генерацію файлів декларації вмісту та стежить за ними в режимі розробки. Він визначає змінні середовища Intlayer всередині додатка Astro та надає аліаси для оптимізації продуктивності.

   Інтеграція lit() дозволяє використовувати Lit custom elements всередині сторінок 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",      uk: "Привіт Світе",    }),    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.",      uk: "Ласкаво просимо на мій багатомовний сайт Astro + Lit.",    }),  },} satisfies Dictionary;export default litDemoContent;

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

   Для отримання додаткової інформації дивіться документацію з декларації вмісту.

5. 5

   Використання вмісту в Astro

   Ви можете використовувати словники безпосередньо у ваших .astro файлах, використовуючи основні допоміжні функції, експортовані з intlayer. Вам також слід додати метадані SEO (такі як hreflang та канонічні посилання) на кожній сторінці. Lit custom elements імпортуються за допомогою блоку <script> на стороні клієнта і розміщуються в body.

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

   Копіювати вміст

   Копіювати код

   Скопіюйте код у буфер обміну

   ---import {  getIntlayer,  getLocaleFromPath,  getLocalizedUrl,  getHTMLTextDir,  getPrefix,  localeMap,  defaultLocale,  type LocalesValues,} from "intlayer";export const getStaticPaths = () => {  return localeMap(({ locale }) => ({    params: { locale: getPrefix(locale).localePrefix },  }));};const locale = getLocaleFromPath(Astro.url.pathname) as LocalesValues;const { greeting } = getIntlayer("lit-demo", 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>    <!-- Lit custom element - приймає мову, визначену сервером, як атрибут -->    <lit-demo locale={locale}></lit-demo>  </body></html><script>  import "../../components/lit/LitDemo";</script>

   Якщо ви хочете використовувати свій контент в атрибуті рядка, такому як 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)}" />

   Примітка щодо налаштування маршрутизації: Структура каталогів, яку ви використовуєте, залежить від параметра middleware.routing у intlayer.config.ts:

   • prefix-no-default (за замовчуванням): Зберігає мову за замовчуванням у корені (без префікса) та додає префікси до інших. Використовуйте [...locale], щоб охопити всі випадки.
   • prefix-all: Усі URL-адреси отримують префікс мови. Ви можете використовувати стандартний [locale], якщо вам не потрібно окремо обробляти корінь.
   • search-param або no-prefix: Каталоги мов не потрібні. Мова керується за допомогою параметрів запиту або cookie.

6. 6

   Створення Lit Custom Element

   Створіть Lit custom element. Викличте installIntlayer у connectedCallback, використовуючи атрибут locale, отриманий від сервера, щоб ініціалізувати синглтон керування перекладами на стороні клієнта.

   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 custom element (див. крок 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 para redicuicamiento через window.location.href garantiza відвідування нової URL-адреси з мовним префіксом. Це дозволяє middleware Intlayer встановити cookie мови та запам'ятати вибір користувача для майбутніх візитів.

8. 8

   Sitemap та Robots.txt

   Intlayer пропонує інструменти для динамічного створення локалізованої карти сайту та файлу robots.txt.

   Sitemap

   Intlayer comes with a built-in sitemap generator to help you create a sitemap for your application easily. It handles localized routes and adds the necessary metadata for search engines.

   The Intlayer generated sitemap supports the xhtml:link namespace (Hreflang XML Extensions). Unlike the default sitemap generators that only list raw URLs, Intlayer automatically creates the required bidirectional links between all language versions of a page (e.g., /about, /about?lang=fr, and /about?lang=es). This ensures search engines correctly index and serve the right language version to the right audience.

   Створіть 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. 1

   Витягніть вміст ваших компонентів

   Необов'язково

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

   Щоб спростити цей процес, 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 використовує розширення модулів (module augmentation), щоб отримати переваги від TypeScript, роблячи вашу кодову базу надійнішою. Якщо ви використовуєте синтаксис декораторів, переконайтеся, що ви ввімкнули experimentalDecorators в опціях компилятора.

Переконайтеся, що ваша конфігурація TypeScript включає автоматично згенеровані типи.

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

Конфігурація Git

Ми рекомендуємо ігнорувати файли, згенеровані Intlayer. Це запобігає їх потраплянню до вашого Git-репозиторію.

Для цього додайте наступні інструкції до вашого файлу .gitignore:

# Ігнорувати файли, згенеровані Intlayer.intlayer

Розширення для VS Code

Щоб покращити ваш досвід розробки з Intlayer, ви можете встановити офіційне розширення Intlayer для VS Code.

Встановити з VS Code Marketplace

Це розширення забезпечує:

• Автозаповнення ключів перекладу.
• Виявлення помилок у реальному часі для відсутніх перекладів.
• Попередній перегляд перекладеного вмісту.
• Швидкі дії для легкого створення та оновлення перекладів.

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

Поглиблюйте свої знання

Якщо ви хочете дізнатися більше, ви також можете впровадити Візуальний редактор або використовувати CMS, щоб винести ваш вміст назовні.