Przetłumacz swoją witrynę Astro + Vanilla JS za pomocą Intlayer | Międzynarodowość (i18n)

Spis treści

Czym jest Intlayer?

Intlayer to innowacyjna biblioteka międzynarodowości (i18n) o otwartym kodzie źródłowym, zaprojektowana w celu uproszczenia obsługi wielojęzyczności w nowoczesnych aplikacjach internetowych.

Dzięki Intlayer możesz:

• Łatwo zarządzać tłumaczeniami: Korzystając z deklaratywnych słowników na poziomie komponentów.
• Dynamicznie lokalizować metadane, trasy i treści.
• Zapewnić obsługę TypeScript: Dzięki automatycznie generowanym typom dla lepszego autouzupełniania i wykrywania błędów.
• Korzystać z zaawansowanych funkcji: Takich jak dynamiczne wykrywanie języka i przełączanie języków.

Przewodnik krok po kroku po konfiguracji Intlayer w Astro + Vanilla JS

Sprawdź szablon aplikacji na GitHubie.

Krok 1: Zainstaluj zależności

Zainstaluj niezbędne pakiety za pomocą preferowanego menedżera pakietów:

npm install intlayer astro-intlayer vanilla-intlayernpx intlayer init

• intlayer Główny pakiet zapewniający narzędzia i18n do zarządzania konfiguracją, tłumaczeniami, deklaracją treści, transpilacją i poleceniami CLI.

• astro-intlayer Wtyczka integracyjna Astro służąca do połączenia Intlayer z bundlerem Vite; zawiera również oprogramowanie pośredniczące (middleware) do wykrywania preferowanego języka użytkownika, zarządzania plikami cookie i obsługi przekierowań URL.

• vanilla-intlayer Pakiet do integracji Intlayer z aplikacjami Vanilla JavaScript / TypeScript. Zapewnia singleton Pub/Sub (IntlayerClient) oraz pomocniki oparte na wywołaniach zwrotnych (useIntlayer, useLocale itp.), dzięki którym dowolna część Twoich skryptów Astro <script> może reagować na zmiany języka bez potrzeby posiadania UI frameworka.

Krok 2: Skonfiguruj swój projekt

Utwórz plik konfiguracyjny, aby zdefiniować języki swojej aplikacji:

import { Locales, type IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  internationalization: {    locales: [      Locales.ENGLISH,      Locales.FRENCH,      Locales.SPANISH,      Locales.POLISH,      // Twoje inne języki    ],    defaultLocale: Locales.ENGLISH,  },};export default config;

Za pośrednictwem tego pliku konfiguracyjnego możesz ustawić zlokalizowane adresy URL, przekierowania oprogramowania pośredniczącego, nazwy plików cookie, lokalizację i rozszerzenia deklaracji treści, wyłączyć dzienniki Intlayer w konsoli i wiele więcej. Pełną listę dostępnych parametrów znajdziesz w dokumentacji konfiguracji.

Krok 3: Zintegruj Intlayer ze swoją konfiguracją Astro

Dodaj wtyczkę intlayer do konfiguracji Astro. W przypadku Vanilla JS nie jest wymagana dodatkowa integracja z frameworkiem UI.

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

Wtyczka integracyjna intlayer() służy do integracji Intlayer z Astro. Zapewnia ona generowanie plików deklaracji treści i monitoruje je w trybie deweloperskim. Definiuje zmienne środowiskowe Intlayer w aplikacji Astro i udostępnia aliasy w celu optymalizacji wydajności.

Krok 4: Zadeklaruj swoją treść

Twórz i zarządzaj swoimi deklaracjami treści, aby przechowywać tłumaczenia:

import { t, type Dictionary } from "intlayer";const appContent = {  key: "app",  content: {    greeting: t({      en: "Hello World",      fr: "Bonjour le monde",      es: "Hola mundo",      pl: "Witaj świecie",    }),    description: t({      en: "Welcome to my multilingual Astro site.",      fr: "Bienvenue sur mon site Astro multilingue.",      es: "Bienvenido a mi sitio Astro multilingüe.",      pl: "Witaj na mojej wielojęzycznej stronie Astro.",    }),    switchLocale: t({      en: "Switch language:",      fr: "Changer de langue :",      es: "Cambiar idioma:",      pl: "Zmień język:",    }),  },} satisfies Dictionary;export default appContent;

Deklaracje treści mogą być definiowane w dowolnym miejscu aplikacji, pod warunkiem, że są zawarte w contentDir (domyślnie ./src) i pasują do rozszerzenia pliku deklaracji treści (domyślnie .content.{json,ts,tsx,js,jsx,mjs,cjs}).

Więcej informacji znajdziesz w dokumentacji deklaracji treści.

Krok 5: Korzystanie z treści w Astro

Z Vanilla JS całe renderowanie po stronie serwera (SSR) odbywa się bezpośrednio w plikach .astro przy użyciu getIntlayer. Następnie, po stronie klienta, blok <script> inicjuje bibliotekę vanilla-intlayer, aby umożliwić przełączanie języków.

---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 kanoniczny -->    <link      rel="canonical"      href={new URL(getLocalizedUrl(Astro.url.pathname, locale), Astro.site)}    />    <!-- Linki 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>

Jeśli chcesz użyć swojej treści w atrybucie string, takim jak alt, title, href, aria-label itp., możesz użyć wartości funkcji, np.:

html

Kopiuj zawartość

Kopiuj kod

Skopiuj kod do schowka

<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)}" />

Uwaga na temat konfiguracji routingu: Używana przez Ciebie struktura katalogów zależy od ustawienia middleware.routing w intlayer.config.ts:

• prefix-no-default (domyślnie): Zachowuje domyślny język w katalogu głównym (bez prefiksu) i dodaje prefiksy do pozostałych. Użyj [...locale], aby obsłużyć wszystkie przypadki.
• prefix-all: Wszystkie adresy URL otrzymują prefiks języka. Możesz użyć standardowego [locale], jeśli nie musisz traktować katalogu głównego oddzielnie.
• search-param lub no-prefix: Katalogi językowe nie są wymagane. Język jest zarządzany za pomocą parametrów zapytania lub plików cookie.

Krok 6: Dodanie przełącznika języków

W Astro z Vanilla JS przełącznik języków jest generowany na serwerze jako zwykłe linki i ożywiany po stronie klienta za pomocą bloku <script>. Gdy użytkownik kliknie link do języka, vanilla-intlayer ustawia plik cookie języka za pomocą setLocale przed przejściem do zlokalizowanego adresu URL.

<!-- Dołącz znaczniki strony po stronie serwera z kroku 5 --><script>  import { installIntlayer, useLocale } from "vanilla-intlayer";  import { getLocaleFromPath, getLocalizedUrl, type LocalesValues } from "intlayer";  // Zainicjuj Intlayer po stronie klienta z językiem pobranym z bieżącej ścieżki  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);    },  });  // Podepnij zdarzenia kliknięcia pod linki przełącznika języków  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>

Uwaga na temat trwałości: installIntlayer inicjuje singleton Intlayer z językiem zdefiniowanym na serwerze. useLocale wraz z onLocaleChange zapewnia, że plik cookie języka zostanie ustawiony przed przekierowaniem przez middleware, co pozwoli zapamiętać preferencje językowe użytkownika przy przyszłych wizytach.

Uwaga na temat stopniowego ulepszania (Progressive Enhancement): Linki w przełączniku języków będą działać jako standardowe znaczniki <a> nawet bez JavaScriptu. Gdy JavaScript jest obecny, wywołanie setLocale aktualizuje plik cookie przed przekierowaniem, zapewniając, że middleware poprawnie obsłuży wybór języka.

Krok 7: Sitemap i Robots.txt

Intlayer oferuje narzędzia do dynamicznego generowania zlokalizowanej mapy witryny oraz pliku 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.

Utwórz plik src/pages/sitemap.xml.ts, aby wygenerować mapę witryny obejmującą wszystkie Twoje zlokalizowane trasy.

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

Utwórz plik src/pages/robots.txt.ts, aby kontrolować indeksowanie przez wyszukiwarki.

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" },  });};

Konfiguracja TypeScript

Intlayer wykorzystuje rozszerzenie modułów (module augmentation), aby skorzystać z TypeScript, czyniąc bazę kodu bardziej solidną.

Upewnij się, że Twoja konfiguracja TypeScript zawiera automatycznie generowane typy.

{  // ... Twoja istniejąca konfiguracja TypeScript  "include": [    // ... Twoja istniejąca konfiguracja TypeScript    ".intlayer/**/*.ts", // Uwzględnij automatycznie generowane typy  ],}

Konfiguracja Git

Zaleca się ignorowanie plików generowanych przez Intlayer. Zapobiega to ich przesyłaniu do repozytorium Git.

Aby to zrobić, dodaj następujące instrukcje do pliku .gitignore:

# Ignoruj pliki generowane przez Intlayer.intlayer

Rozszerzenie VS Code

Aby poprawić wrażenia z programowania z Intlayer, możesz zainstalować oficjalne rozszerzenie Intlayer dla VS Code.

Instalacja z VS Code Marketplace

To rozszerzenie zapewnia:

• Autouzupełnianie kluczy tłumaczeń.
• Wykrywanie błędów w czasie rzeczywistym dla brakujących tłumaczeń.
• Podgląd inline przetłumaczonej treści.
• Szybkie akcje do łatwego tworzenia i aktualizowania tłumaczeń.

Więcej informacji na temat korzystania z rozszerzenia znajdziesz w dokumentacji rozszerzenia VS Code.

(Opcjonalnie) Krok 17 : Wyodrębnij zawartość swoich komponentów

Jeśli masz istniejącą bazę kodu, transformacja tysięcy plików może być czasochłonna.

Aby ułatwić ten proces, Intlayer proponuje kompilator / ekstraktor, aby przetransformować komponenty i wyodrębnić zawartość.

Aby go skonfigurować, możesz dodać sekcję compiler w pliku intlayer.config.ts:

import { type IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  // ... Reszta Twojej konfiguracji
  compiler: {
    /**
     * Wskazuje, czy kompilator powinien być włączony.
     */
    enabled: true,

    /**
     * Definiuje ścieżkę plików wyjściowych
     */
    output: ({ fileName, extension }) => `./${fileName}${extension}`,

    /**
     * Wskazuje, czy komponenty powinny zostać zapisane po transformacji. W ten sposób kompilator można uruchomić tylko raz, aby przetransformować aplikację, a następnie go usunąć.
     */
    saveComponents: false,

    /**
     * Prefiks klucza słownika
     */
    dictionaryKeyPrefix: "",
  },
};

export default config;

npx intlayer extract

import { defineConfig } from "vite";import { intlayer, intlayerCompiler } from "vite-intlayer";export default defineConfig({ plugins: [   intlayer(),   intlayerCompiler(), // Dodaje wtyczkę kompilatora ],});

npm run build # Lub npm run dev

Pogłębiaj swoją wiedzę

Jeśli chcesz dowiedzieć się więcej, możesz również wdrożyć Edytor Wizualny lub użyć CMS, aby wyeksternalizować swoją treść.