Creation:2026-04-24Last update:2026-05-31

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

    ide.intlayer.org

    Spis treści

    Dlaczego Interlayer zamiast alternatyw?

    W porównaniu do głównych rozwiązań, takich jak „astro-i18n” czy „i18next”, Intlayer jest rozwiązaniem wyposażonym w zintegrowane optymalizacje, takie jak:

    Pełny zasięg Astro

    Intlayer jest zoptymalizowany do doskonałej współpracy z Astro, oferując wielojęzyczny routing, mapę witryny i wszystkie funkcje potrzebne do skalowania internacjonalizacji (i18n).

    Rozmiar bundle'a

    Zamiast ładować ogromne pliki JSON na swoje strony, ładuj tylko niezbędną treść. Intlayer pomaga zmniejszyć rozmiary bundle'a i stron nawet o 50%.

    Łatwość konserwacji

    Określanie zakresu zawartości aplikacji ułatwia konserwację aplikacji na dużą skalę. Możesz powielić lub usunąć pojedynczy folder funkcji bez obciążania psychicznego koniecznością przeglądania całej bazy kodu zawartości. Dodatkowo Inlayer jest w pełni napisany, aby zapewnić dokładność treści.

    Agent AI

    Wspólna lokalizacja treści zmniejsza potrzebny kontekst dzięki modelom dużego języka (LLM). Intlayer zawiera także zestaw narzędzi, taki jak CLI do sprawdzania brakujących tłumaczeńLSP, MCP i umiejętności agenta, aby praca programisty (DX) była jeszcze płynniejsza dla agentów AI.

    Automatyzacja

    Korzystaj z automatyzacji, aby tłumaczyć w swoim potoku CI/CD przy użyciu wybranego LLM na koszt dostawcy sztucznej inteligencji. Intlayer oferuje także kompilator do automatyzacji ekstrakcji treści, a także [platformę internetową] (/pl/doc/concept/cms), która pomaga tłumaczyć w tle.

    Wydajność

    Łączenie ogromnych plików JSON z komponentami może prowadzić do problemów z wydajnością i reaktywnością. Inlayer optymalizuje ładowanie treści w czasie kompilacji.

    Skalowanie bez użycia dewelopera

    Więcej niż tylko rozwiązanie i18n, Intlayer zapewnia samodzielny edytor wizualny i pełny CMS, który pomoże Ci zarządzać wielojęzyczną treścią w w czasie rzeczywistym, dzięki czemu współpraca z tłumaczami, copywriterami i innymi członkami zespołu będzie płynna. Treść może być przechowywana lokalnie i/lub zdalnie.

    Przewodnik krok po kroku po konfiguracji Intlayer w Astro + Lit

    Sprawdź szablon aplikacji na GitHubie.

    1. Zainstaluj zależności

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

      bash
      npm install intlayer astro-intlayer lit lit-intlayer @astrojs/litnpx 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.

      • lit Podstawowe pakiety Lit do budowania szybkich, lekkich komponentów Web Components.

      • lit-intlayer Pakiet do integracji Intlayer z aplikacjami Lit. Zapewnia hooki oparte na ReactiveController (useIntlayer, useLocale itp.), które automatycznie instruują LitElement o konieczności ponownego renderowania przy zmianie języka.

      • @astrojs/lit Oficjalna integracja Astro pozwalająca na używanie elementów niestandardowych (custom elements) Lit wewnątrz stron Astro.

    2. Skonfiguruj swój projekt

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

      intlayer.config.ts
      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.

    3. Zintegruj Intlayer ze swoją konfiguracją Astro

      Dodaj wtyczkę intlayer do konfiguracji Astro oraz integrację Lit.

      astro.config.ts
      // @ts-checkimport { intlayer } from "astro-intlayer";import lit from "@astrojs/lit";import { defineConfig } from "astro/config";// https://astro.build/configexport default defineConfig({  integrations: [intlayer(), lit()],});
      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.
      Integracja lit() pozwala na używanie elementów niestandardowych Lit wewnątrz stron Astro.

    4. Zadeklaruj swoją treść

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

      src/components/lit/app.content.ts
      import { t, type Dictionary } from "intlayer";const litDemoContent = {  key: "lit-demo",  content: {    greeting: t({      en: "Hello World",      fr: "Bonjour le monde",      es: "Hola mundo",      pl: "Witaj świecie",    }),    description: t({      en: "Welcome to my multilingual Astro + Lit site.",      fr: "Bienvenue sur mon site Astro + Lit multilingue.",      es: "Bienvenido a mi sitio Astro + Lit multilingüe.",      pl: "Witaj na mojej wielojęzycznej stronie Astro + Lit.",    }),  },} satisfies Dictionary;export default litDemoContent;
      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.

    5. Korzystanie z treści w Astro

      Możesz konsumować słowniki bezpośrednio w swoich plikach .astro, używając podstawowych pomocników wyeksportowanych z intlayer. Powinieneś również dodać metadane SEO (takie jak linki hreflang i kanoniczne) na każdej stronie. Elementy niestandardowe Lit są importowane za pomocą bloku <script> po stronie klienta i umieszczane w body.

      src/pages/[...locale]/index.astro
      ---import {  getIntlayer,  getLocaleFromPath,  getLocalizedUrl,  getHTMLTextDir,  getPrefix,  localeMap,  defaultLocale,  type LocalesValues,} from "intlayer";export const getStaticPaths = () => {  return localeMap(({ locale }) => ({    params: { locale: getPrefix(locale).localePrefix },  }));};const locale = getLocaleFromPath(Astro.url.pathname) as LocalesValues;const { greeting } = getIntlayer("lit-demo", 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>    <!-- Element niestandardowy Lit - otrzymuje język wykryty przez serwer jako atrybut -->    <lit-demo locale={locale}></lit-demo>  </body></html><script>  import "../../components/lit/LitDemo";</script>
      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
      <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.

    6. Utworzenie elementu niestandardowego Lit

      Utwórz element niestandardowy Lit. Wywołaj installIntlayer w connectedCallback, używając atrybutu locale opartego na serwerze, aby zainicjować singleton tłumaczeń po stronie klienta.

      src/components/lit/LitDemo.ts
      import { LitElement, html } from "lit";import { installIntlayer, useIntlayer, useLocale } from "lit-intlayer";import { getLocalizedUrl, getLocaleName, type LocalesValues } from "intlayer";class LitDemo extends LitElement {  static properties = {    locale: { type: String },  };  locale: LocalesValues = "en" as LocalesValues;  private _content = useIntlayer(this, "lit-demo");  private _localeCtrl = useLocale(this, {    onLocaleChange: (newLocale: LocalesValues) => {      window.location.href = getLocalizedUrl(        window.location.pathname,        newLocale      );    },  });  override connectedCallback() {    super.connectedCallback();    // Zainicjuj językiem wykrytym przez serwer    installIntlayer({ locale: this.locale as any });  }  override render() {    const { greeting, description } = this._content;    const {      locale: currentLocale,      availableLocales,      setLocale,    } = this._localeCtrl;    return html`      <div>        <h1>${greeting}</h1>        <p>${description}</p>        <!-- Przełącznik języków renderowany wewnątrz LitElement -->        <div class="locale-switcher">          <span class="switcher-label">Zmień język:</span>          <div class="locale-buttons">            ${availableLocales.map(              (localeItem) => html`                <button                  class="locale-btn ${localeItem === currentLocale                    ? "active"                    : ""}"                  ?disabled=${localeItem === currentLocale}                  @click=${() => setLocale(localeItem)}                >                  <span class="ls-own-name">${getLocaleName(localeItem)}</span>                  <span class="ls-current-name"                    >${getLocaleName(localeItem, currentLocale)}</span                  >                  <span class="ls-code">${localeItem.toUpperCase()}</span>                </button>              `            )}          </div>        </div>      </div>    `;  }}customElements.define("lit-demo", LitDemo);
      Atrybut locale jest przekazywany ze strony Astro (wykrywanie po stronie serwera) i używany do zainicjowania installIntlayer w connectedCallback, ustawiając początkowy język dla wszystkich hooków ReactiveController wewnątrz elementu.
      useIntlayer jest zarejestrowany jako ReactiveController. Automatycznie instruuje on komponent o konieczności ponownego renderowania (re-render) przy zmianie języka, więc nie jest wymagana żadna dodatkowa logika subskrypcji.

    7. Dodanie przełącznika języków

      Funkcjonalność przełączania języków jest zintegrowana bezpośrednio z metodą render() elementu niestandardowego Lit (patrz krok 6 powyżej). Wykorzystuje ona useLocale z lit-intlayer i przechodzi do zlokalizowanego adresu URL, gdy użytkownik wybierze nowy język:

      src/components/lit/LitDemo.ts
      // Wewnątrz klasy LitElement, po konfiguracji useLocale z kroku 6:private _localeCtrl = useLocale(this, {  onLocaleChange: (newLocale: LocalesValues) => {    // Przekieruj do zlokalizowanego adresu URL przy zmianie języka    window.location.href = getLocalizedUrl(window.location.pathname, newLocale);  },});override render() {  const { locale: currentLocale, availableLocales, setLocale } = this._localeCtrl;  return html`    <div class="locale-switcher">      <span class="switcher-label">Zmień język:</span>      <div class="locale-buttons">        ${availableLocales.map(          (localeItem) => html`            <button              class="locale-btn ${localeItem === currentLocale ? "active" : ""}"              ?disabled=${localeItem === currentLocale}              @click=${() => setLocale(localeItem)}            >              <span class="ls-own-name">${getLocaleName(localeItem)}</span>              <span class="ls-current-name">${getLocaleName(localeItem, currentLocale)}</span>              <span class="ls-code">${localeItem.toUpperCase()}</span>            </button>          `        )}      </div>    </div>  `;}

      Uwaga na temat reaktywności Lit: useLocale zwraca ReactiveController. Gdy wywoływane jest setLocale, kontroler automatycznie żąda ponownego renderowania, aktualizując stan przycisków bez potrzeby ręcznej manipulacji DOM.

      Uwaga na temat trwałości: Użycie onLocaleChange do przekierowania przez window.location.href zapewnia, że nowy adres URL z prefiksem językowym zostanie odwiedzony. Pozwala to oprogramowaniu pośredniczącemu Intlayer ustawić plik cookie języka i zapamiętać preferencje użytkownika przy przyszłych wizytach.

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

      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

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

      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. Wyodrębnij zawartość swoich komponentów

      Opcjonalne

      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:

      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;

      Uruchom ekstraktor, aby przetransformować komponenty i wyodrębnić zawartość

      bash
      npx intlayer extract

    Konfiguracja TypeScript

    Intlayer wykorzystuje rozszerzenie modułów (module augmentation), aby skorzystać z TypeScript, czyniąc bazę kodu bardziej solidną. Jeśli używasz składni dekoratorów, upewnij się, że w opcjach kompilatora włączono experimentalDecorators.

    Autocompletion

    Translation Error

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

    tsconfig.json
    {  compilerOptions: {    // ...    experimentalDecorators: true,    useDefineForClassFields: false, // Wymagane dla obsługi dekoratorów w Lit  },  "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:

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

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

    Astro dan Preact
    Astro dan Vanilla JS