Перекладіть свій сайт Astro за допомогою Intlayer

Зміст

Чому варто обрати 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 Основний пакет, що надає інструменти i18n для керування конфігурацією, перекладами, декларацією вмісту, транспіляцією та командами CLI.

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

2. 2

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

   Архітектура

   У цій архітектурі інтеграція intlayer(), зареєстрована в astro.config.ts, збирає ваші словники та додає middleware, який визначає локаль кожного запиту та надає її в Astro.locals.intlayer. Сторінки розміщуються під rest-сегментом src/pages/[...locale]/, завдяки чому локаль за замовчуванням обслуговується без префікса, а кожна інша локаль отримує власну виділену URL-адресу. Файли .astro читають вміст за допомогою хуків useIntlayer / useLocale з astro-intlayer, а оголошення вмісту розміщуються поруч із вашими компонентами в src/.

   bash

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

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

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

   .
   ├── src
   │   ├── app.content.tsx               # App content declaration
   │   ├── components
   │   │   └── LocaleSwitcher.astro      # Locale switcher component
   │   └── pages
   │       ├── [...locale]
   │       │   └── index.astro           # Localized page (rest param also serves the default locale)
   │       ├── robots.txt.ts             # robots.txt endpoint
   │       └── sitemap.xml.ts            # Localized sitemap endpoint
   ├── astro.config.ts                   # Astro config with the intlayer() integration
   ├── 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,
         Locales.UKRAINIAN,
         // Ваші інші локалі
       ],
       defaultLocale: Locales.ENGLISH,
     },
   };
   
   export default config;
   

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

   документації з конфігурації
3. 3

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

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

   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.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",
         uk: "Привіт Світе",
       }),
     },
   } satisfies Dictionary;
   
   export default appContent;
   

   Декларації вмісту можна визначати в будь-якому місці вашого додатка, за умови, що вони включені в 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, оскільки вони рендеряться один раз для кожного відвідувача.

   Вам також слід додати SEO-метадані, такі як hreflang і канонічні посилання, на кожну сторінку та включити перемикач мов, щоб користувачі могли змінювати мову.

   src/pages/index.astro

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

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

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

   ---
   import { useIntlayer, useLocale } from "astro-intlayer";
   import {
     getLocalizedUrl,
     defaultLocale,
     localeMap,
     getHTMLTextDir,
   } from "intlayer";
   import LocaleSwitcher from "../components/LocaleSwitcher.astro";
   
   // Локаль, визначена middleware (напр. /uk/about -> 'uk')
   const { locale } = useLocale();
   
   // Вміст словника 'app' для цієї локалі
   const { title } = useIntlayer("app");
   ---
   
   <!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>
   

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

6. 6

   Локалізована маршрутизація

   Створіть динамічні сегменти маршрутів (наприклад, src/pages/[locale]/index.astro) для обслуговування локалізованих сторінок:

   src/pages/[locale]/index.astro

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

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

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

   ---
   import { getIntlayer } from "intlayer";
   
   const { title } = getIntlayer('app');
   ---
   
   <h1>{title}</h1>
   

   Інтеграція Astro додає middleware Vite, який допомагає з маршрутизацією з урахуванням мови та визначеннями середовища під час розробки. Ви також можете використовувати власну логіку або інструменти intlayer, такі як getLocalizedUrl, для посилань між мовами.

7. 7

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

   Щоб користувачі могли перемикатися між мовами, ви можете створити компонент LocaleSwitcher. Цей компонент має відображати список усіх підтримуваних мов та посилатися на ту саму сторінку кожною мовою.

   src/components/LocaleSwitcher.astro

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

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

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

   ---
   import { useLocale } from "astro-intlayer";
   import { getLocaleName, getLocalizedUrl, getPathWithoutLocale } from "intlayer";
   
   const { locale, availableLocales } = useLocale();
   const pathWithoutLocale = getPathWithoutLocale(Astro.url.pathname);
   ---
   
   <nav aria-label="Languages">
     <ul>
       {
         availableLocales.map((localeItem) => (
           <li key={localeItem} class="p-1">
             <a
               href={getLocalizedUrl(pathWithoutLocale, localeItem)}
               data-locale={localeItem}
               aria-current={localeItem === locale ? "page" : undefined}
             >
               {getLocaleName(localeItem)}
             </a>
           </li>
         ))
       }
     </ul>
   </nav>
   
   <script>
     // У браузері той самий імпорт розпізнається як клієнтська реалізація
     import { useLocale } from "astro-intlayer";
     import { getLocalizedUrl, type LocalesValues } from "intlayer";
   
     // Зберігає вибір у cookie локалі, після чого переходить на локалізований URL
     const { setLocale } = useLocale({
       onLocaleChange: (newLocale) => {
         window.location.href = getLocalizedUrl(window.location.pathname, newLocale);
       },
     });
   
     const localeLinks = document.querySelectorAll("[data-locale]");
   
     localeLinks.forEach((link) => {
       link.addEventListener("click", (event) => {
         const locale = link.getAttribute("data-locale") as LocalesValues;
   
         event.preventDefault();
         setLocale(locale);
       });
     });
   </script>
   
   <style>
     nav {
       display: flex;
       gap: 1rem;
     }
     ul {
       display: flex;
       list-style: none;
       padding: 0;
       margin: 0;
       gap: 0.5rem;
     }
     a[aria-current="page"] {
       font-weight: bold;
       text-decoration: underline;
     }
   </style>
   

   Примітка щодо збереження стану: setLocale із клієнтського useLocale зберігає мовні вподобання користувача в cookie. Це дозволяє Intlayer запам'ятовувати вибір і автоматично перенаправляти користувача на бажану мову під час наступних візитів: сторінки, що рендерилися на вимогу (адаптер з output: 'server' або prerender = false), перенаправляються middleware Intlayer до надсилання будь-якого HTML, тоді як попередньо згенеровані сторінки, що надаються як статичні файли, перенаправляються невеликим скриптом, який інтеграція вставляє в кожну сторінку. Встановіть routing.enableProxy в false, щоб вимкнути обидва механізми. В astro dev cookie ігнорується як джерело перенаправлення, якщо тільки routing.enableProxy не встановлено в true, тому застарілий cookie не зможе перехопити сторінки, над якими ви працюєте.

   Взаємосумісність сервера та клієнта: astro-intlayer розпізнається як серверні хуки у фронтматтері (зчитуючи Astro.locals) та як клієнтські хуки vanilla-intlayer у блоках <script> та островах (islands), з тими самими іменами та структурою даних. setLocale та onChange діють лише на клієнті, викличте installIntlayer() один раз для ініціалізації клієнтського сховища. astro-intlayer/client експортує клієнтську точку входу явно.

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 },
   ];
   
   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. 9

   Продовжуйте використовувати ваш улюблений фреймворк

   Продовжуйте будувати свій додаток, використовуючи фреймворк за вашим вибором.

   Intlayer з React

   Intlayer з Vue

   Intlayer з Svelte

   Intlayer з Solid

   Intlayer з Preact

   Intlayer з Lit
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
    

    Зберіть застосунок, щоб перетворити ваші компоненти та витягти вміст

    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.

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

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

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