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

Зміст

Що таке Intlayer?

Intlayer - це інноваційна бібліотека інтернаціоналізації (i18n) з відкритим вихідним кодом, розроблена для спрощення підтримки багатьох мов у сучасних веб-додатках.

З Intlayer ви можете:

• Легко керувати перекладами: Використовуючи декларативні словники на рівні компонентів.
• Динамічно локалізувати метадані, маршрути та вміст.
• Забезпечити підтримку TypeScript: Завдяки автоматично згенерованим типам для кращого автовідчуття та виявлення помилок.
• Використовувати розширені можливості: Такі як динамічне визначення мови та перемикання мов.

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

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

Крок 1: Встановіть залежності

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

npm install intlayer astro-intlayer solid-js solid-intlayer @astrojs/solid-jsnpx intlayer init

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

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

• solid-js Основний пакет Solid.

• solid-intlayer Пакет для інтеграції Intlayer у додатки Solid. Він надає IntlayerProvider, а також примітиви useIntlayer та useLocale для інтернаціоналізації в Solid.

• @astrojs/solid-js Офіційна інтеграція Astro, яка дозволяє використовувати Solid component islands.

Крок 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 та інтеграцію Solid.

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

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

Інтеграція solid() дозволяє використовувати Solid component islands за допомогою client:only="solid-js".

Крок 4: Декларуйте свій вміст

Створюйте та керуйте своїми деклараціями вмісту для зберігання перекладів:

import { t, type Dictionary } from "intlayer";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}).

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

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

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

---import {  getIntlayer,  getLocaleFromPath,  getLocalizedUrl,  getHTMLTextDir,  getPrefix,  localeMap,  defaultLocale,  type LocalesValues,} from "intlayer";import { SolidIsland } from "../../components/solid/SolidIsland";export const getStaticPaths = () => {  return localeMap(({ locale }) => ({    params: { locale: getPrefix(locale).localePrefix },  }));};const locale = getLocaleFromPath(Astro.url.pathname) as LocalesValues;const { title } = 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>{title}</title>    <!-- Канонічне посилання: Повідомляє пошуковим системам основну версію цієї сторінки -->    <link      rel="canonical"      href={new URL(getLocalizedUrl(Astro.url.pathname, locale), Astro.site)}    />    <!-- Hreflang: Повідомляє Google про всі локалізовані версії -->    {      localeMap(({ locale: mapLocale }) => (        <link          rel="alternate"          hreflang={mapLocale}          href={new URL(            getLocalizedUrl(Astro.url.pathname, mapLocale),            Astro.site          )}        />      ))    }    <!-- x-default: Резервний варіант, коли мова не відповідає мові користувача -->    <link      rel="alternate"      hreflang="x-default"      href={new URL(        getLocalizedUrl(Astro.url.pathname, defaultLocale),        Astro.site      )}    />  </head>  <body>    <!-- Solid island рендерить увесь інтерактивний вміст, включаючи перемикач мов -->    <SolidIsland locale={locale} client:only="solid-js" />  </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: Створення компонента Solid Island

Створіть компонент island, який обгортає ваш додаток Solid і приймає мову, визначену сервером:

/** @jsxImportSource solid-js */import { IntlayerProvider, useIntlayer } from "solid-intlayer";import { type LocalesValues } from "intlayer";import { LocaleSwitcher } from "./LocaleSwitcher";function App() {  const content = useIntlayer("app");  return (    <div>      <h1>{content.title}</h1>      <LocaleSwitcher />    </div>  );}export function SolidIsland({ locale }: { locale: LocalesValues }) {  return (    <IntlayerProvider locale={locale}>      <App />    </IntlayerProvider>  );}

Проп locale передається зі сторінки Astro (визначення на стороні сервера) до IntlayerProvider, що слугує початковою мовою для всіх примітивів Solid всередині дерева.

У Solid useIntlayer повертає accessor (наприклад, `content.). Ви повинні викликати його, щоб отримати доступ до реактивного вмісту.

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

Створіть компонент Solid LocaleSwitcher, який зчитує доступні мови та переходить за локалізованою URL-адресою, коли користувач обирає нову мову:

/** @jsxImportSource solid-js */import { useLocale } from "solid-intlayer";import { getLocalizedUrl, getLocaleName, type LocalesValues } from "intlayer";export function LocaleSwitcher() {  const { locale, availableLocales, setLocale } = useLocale({    onLocaleChange: (newLocale: LocalesValues) => {      // Перейти за локалізованою URL-адресою при зміні мови      window.location.href = getLocalizedUrl(        window.location.pathname,        newLocale      );    },  });  return (    <div class="locale-switcher">      <span class="switcher-label">Змінити мову:</span>      <div class="locale-buttons">        {availableLocales.map((localeItem) => (          <button            onClick={() => setLocale(localeItem)}            class={`locale-btn ${localeItem === locale() ? "active" : ""}`}            disabled={localeItem === locale()}          >            <span class="ls-own-name">{getLocaleName(localeItem)}</span>            <span class="ls-current-name">              {getLocaleName(localeItem, locale())}            </span>            <span class="ls-code">{localeItem.toUpperCase()}</span>          </button>        ))}      </div>    </div>  );}

Примітка щодо реактивності Solid: У Solid locale є сигналом реактивного доступу (reactive accessor signal) - завжди викликайте його як locale(), щоб отримати поточне значення.

Примітка щодо стійкості: Використання onLocaleChange для перенаправлення через window.location.href гарантує відвідування нової URL-адреси з мовним префіксом. Це дозволяє middleware Intlayer встановити cookie мови та запам'ятати вибір користувача для майбутніх візитів.

LocaleSwitcher повинен рендеритися всередині IntlayerProvider - використовуйте його у вашому компоненті island (як показано на кроці 6).

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

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