Перекладіть свій сайт 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

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

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

• vanilla-intlayer Пакет для інтеграції Intlayer у додатки Vanilla JavaScript / TypeScript. Він надає синглтон Pub/Sub (IntlayerClient) та допоміжні функції на основі callback-функцій (useIntlayer, useLocale тощо), щоб будь-яка частина вашого <script> в Astro могла реагувати на зміни мови без потреби у фреймворку UI.

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

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

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: Інтегруйте Intlayer у вашу конфігурацію Astro

Додайте плагін intlayer до вашої конфігурації Astro. Для 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",      uk: "Привіт Світе",    }),    description: t({      en: "Welcome to my multilingual Astro site.",      fr: "Bienvenue sur mon site Astro multilingue.",      es: "Bienvenido a mi sitio Astro multilingüe.",      uk: "Ласкаво просимо на мій багатомовний сайт Astro.",    }),    switchLocale: t({      en: "Switch language:",      fr: "Changer de langue :",      es: "Cambiar idioma:",      uk: "Змінити мову:",    }),  },} satisfies Dictionary;export default appContent;

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

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

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

З Vanilla JS весь серверний рендеринг (SSR) відбувається безпосередньо у файлах .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>

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

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

<!-- Включіть розрітку серверної частини з кроку 5 сюди --><script>  import { installIntlayer, useLocale } from "vanilla-intlayer";  import { getLocaleFromPath, getLocalizedUrl, type LocalesValues } from "intlayer";  // Ініціалізувати Intlayer на клієнті з мовою, взятою з поточного шляху  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 забезпечують встановлення cookie мови перед перенаправленням через middleware, що дозволяє мові користувача зберігатися для майбутніх візитів.

Примітка щодо Progressive Enhancement: Посилання всередині перемикача мов працюватимуть як стандартні теги <a> навіть без JavaScript. Коли JavaScript доступний, виклик setLocale оновлює cookie перед перенаправленням, забезпечуючи правильну обробку вибору мови посередником (middleware).

Крок 7: 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 для генерації карти сайту, що охоплює всі ваші локалізовані маршрути.

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

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

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

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

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

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

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

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

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

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

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

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

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

(Необов'язково) Крок 1 : Витягніть вміст ваших компонентів

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

Щоб спростити цей процес, 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, щоб винести ваш вміст назовні.