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

Зміст

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

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

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

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

1. 1

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

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

   bash

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

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

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

   npx intlayer init --interactive
   

   прапорець --interactive не є обов'язковим. Використовуйте intlayer-cli init, якщо ви є ШІ-агентом.

   Ця команда виявить ваше середовище та встановить необхідні пакети. Наприклад:

   bash

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

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

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

   npm install intlayer astro-intlayer vanilla-intlayer
   

   • 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. 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. Для Vanilla JS не потрібні додаткові інтеграції фреймворків UI.

   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 та надає аліаси для оптимізації продуктивності.

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

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

5. 5

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

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

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

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

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

6. 6

   Додавання перемикача мов

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

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

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

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

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

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

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

   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

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

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

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

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

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

Часто задавані запитання