Autor:
    Aymeric PINEAU
    Data utworzenia:2026-03-31Ostatnia aktualizacja:2026-05-31

    Przetłumacz swoją stronę Vanilla JS używając Intlayer | Międzynarodowienie (i18n)

    ide.intlayer.org
    intlayer-vanilla-template.vercel.app

    Spis treści

    Dlaczego Interlayer zamiast alternatyw?

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

    Intlayer jest zoptymalizowany do doskonałej współpracy z Vanilla JavaScript, oferując zarządzanie treścią niezależnie od platformy, obsługę TypeScript i wszystkie funkcje potrzebne do skalowania internacjonalizacji (i18n).

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

    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.

    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 agent skills, aby praca programisty (DX) była jeszcze płynniejsza dla agentów AI.

    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.

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

    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 konfiguracji Intlayer w aplikacji Vanilla JS

    1. Instalacja zależności

      Zainstaluj niezbędne pakiety za pomocą npm:

      bash
      # Wygeneruj samodzielny pakiet intlayer i vanilla-intlayer
# Ten plik zostanie zaimportowany do Twojego pliku HTML
npx intlayer standalone --packages intlayer vanilla-intlayer --outfile intlayer.js

# Zainicjuj intlayer z plikiem konfiguracyjnym
npx intlayer init --no-gitignore

# Zbuduj słowniki
npx intlayer build

      • intlayer Główny pakiet dostarczający narzędzia do międzynarodowienia w zakresie zarządzania konfiguracją, tłumaczenia, deklarowania treści, transpilacji oraz poleceń CLI.

      • vanilla-intlayer Pakiet integrujący Intlayer z czystymi aplikacjami JavaScript / TypeScript. Dostarcza singleton pub/sub (IntlayerClient) oraz pomocników opartych na callbackach (useIntlayer, useLocale itp.), dzięki czemu każda część Twojej aplikacji może reagować na zmiany języka bez zależności od frameworka UI.

      Eksport bundlingu z CLI intlayer standalone generuje zoptymalizowaną kompilację dzięki usuwaniu nieużywanych kodów (tree-shaking) nieużywanych pakietów, lokalizacji i nieistotnej logiki (takiej jak przekierowania lub prefiksy), specyficznych dla Twojej konfiguracji.

    2. Konfiguracja Twojego projektu

      Architektura

      W tej architekturze rdzeń intlayer zapewnia interfejsy API JavaScript do deklarowania i używania słowników w standardowych środowiskach JavaScript lub TypeScript bez frameworka frontendowego.

      bash
      .
├── src
│   ├── app.content.mjs
│   └── main.js
├── index.html
├── intlayer.config.mjs
└── package.json

      Konfiguracja

      Utwórz plik konfiguracyjny, aby skonfigurować języki Twojej aplikacji:

      intlayer.config.ts
      import { Locales, type IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  internationalization: {
    locales: [
      Locales.ENGLISH,
      Locales.FRENCH,
      Locales.SPANISH,
      // Twoje inne języki
    ],
    defaultLocale: Locales.ENGLISH,
  },
};

export default config;
      Za pomocą tego pliku konfiguracyjnego możesz ustawić zlokalizowane adresy URL, przekierowania middleware, nazwy ciasteczek, lokalizację i rozszerzenie deklaracji treści, wyłączyć logi Intlayer w konsoli i wiele więcej. Pełną listę dostępnych parametrów znajdziesz w dokumentacji konfiguracji.

    3. Zaimportuj pakiet do HTML

      Po wygenerowaniu pakietu intlayer.js, możesz go zaimportować do swojego pliku HTML:

      index.html
      <!DOCTYPE html>
<html lang="pl">
  <head>
    <meta charset="UTF-8" />

    <!-- Zaimportuj pakiet -->
    <script src="./intlayer.js" defer></script>
    <!-- Zaimportuj swój główny skrypt -->
    <script src="./src/main.js" defer></script>
  </head>
  <body>
    <h1 id="title"></h1>
    <p class="read-the-docs"></p>
  </body>
</html>

      Pakiet udostępnia Intlayer i VanillaIntlayer jako obiekty globalne na window.

    4. Uruchom Intlayer w punkcie wejścia

      W swoim src/main.js wywołaj installIntlayer() zanim jakakolwiek treść zostanie wyrenderowana, aby globalny singleton języka był gotowy.

      src/main.js
      const { installIntlayer } = window.VanillaIntlayer;

// Musi zostać wywołane przed renderowaniem jakiejkolwiek treści i18n.
installIntlayer();

      Jeśli chcesz również używać renderera markdown, wywołaj installIntlayerMarkdown():

      src/main.js
      const { installIntlayer, installIntlayerMarkdown } = window.VanillaIntlayer;

installIntlayer();
installIntlayerMarkdown();

    5. Zadeklaruj swoje treści

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

      src/app.content.ts
      import { insert, t, type Dictionary } from "intlayer";

const appContent = {
  key: "app",
  content: {
    title: "Vite + Vanilla",

    viteLogoLabel: t({
      en: "Vite Logo",
      fr: "Logo Vite",
      es: "Logo Vite",
    }),

    count: insert(
      t({
        en: "count is {{count}}",
        fr: "le compte est {{count}}",
        es: "el recuento es {{count}}",
      })
    ),

    readTheDocs: t({
      en: "Click on the Vite logo to learn more",
      fr: "Cliquez sur le logo Vite pour en savoir plus",
      es: "Kliknij na logo Vite, aby dowiedzieć się więcej",
    }),
  },
} satisfies Dictionary;

export default appContent;

      Deklaracje treści mogą być definiowane w dowolnym miejscu aplikacji, o ile znajdują się w katalogu contentDir (domyślnie ./src) i pasują do rozszerzenia pliku deklaracji treści (domyślnie .content.{json,ts,tsx,js,jsx,mjs,cjs,md,mdx,yaml,yml}).

      Więcej szczegółów znajdziesz w dokumentacji deklaracji treści.

    6. Użyj Intlayer w swoim JavaScript

      Obiekt window.VanillaIntlayer dostarcza pomocników API: useIntlayer(key, locale?) zwraca przetłumaczoną treść dla danego klucza.

      src/main.js
      const { installIntlayer, useIntlayer } = window.VanillaIntlayer;

installIntlayer();

// Pobierz początkową treść dla bieżącego języka.
// Podepnij .onChange(), aby otrzymywać powiadomienia o każdej zmianie języka.
const content = useIntlayer("app").onChange((newContent) => {
  // Ponownie wyrenderuj lub zaktualizuj tylko dotknięte węzły DOM
  document.querySelector("h1").textContent = String(newContent.title);
  document.querySelector(".read-the-docs").textContent = String(
    newContent.readTheDocs
  );
});

// Początkowy render
document.querySelector("h1").textContent = String(content.title);
document.querySelector(".read-the-docs").textContent = String(
  content.readTheDocs
);

      Uzyskuj dostęp do wartości liści jako ciągów znaków, owijając je w String(), co wywołuje metodę toString() węzła i zwraca przetłumaczony tekst.

      Gdy potrzebujesz wartości dla natywnego atrybutu HTML (np. alt, aria-label), użyj bezpośrednio .value:

      javascript
      img.alt = content.viteLogoLabel.value;

    7. Zmień język swojej treści

      Opcjonalne

      Aby zmienić język treści, użyj funkcji setLocale udostępnianej przez useLocale.

      src/locale-switcher.js
      const { getLocaleName } = window.Intlayer;
const { useLocale } = window.VanillaIntlayer;

export function setupLocaleSwitcher(container) {
  const { locale, availableLocales, setLocale, subscribe } = useLocale();

  const select = document.createElement("select");
  select.setAttribute("aria-label", "Język");

  const render = (currentLocale) => {
    select.innerHTML = availableLocales
      .map(
        (loc) =>
          `<option value="${loc}"${loc === currentLocale ? " selected" : ""}>
            ${getLocaleName(loc)}
          </option>`
      )
      .join("");
  };

  render(locale);
  container.appendChild(select);

  select.addEventListener("change", () => setLocale(select.value));

  // Utrzymuj listę rozwijaną w synchronizacji, gdy język zmieni się z innego miejsca
  return subscribe((newLocale) => render(newLocale));
}

    8. Przełącz atrybuty języka i kierunku HTML

      Opcjonalne

      Zaktualizuj atrybuty lang i dir tagu <html>, aby pasowały do bieżącego języka dla dostępności i SEO.

      src/main.js
      const { getHTMLTextDir } = window.Intlayer;
const { installIntlayer, useLocale } = window.VanillaIntlayer;

installIntlayer();

useLocale({
  onLocaleChange: (locale) => {
    document.documentElement.lang = locale;
    document.documentElement.dir = getHTMLTextDir(locale);
  },
});

    9. Leniwe ładowanie słowników na język

      Opcjonalne

      Jeśli chcesz leniwie ładować słowniki dla każdego języka, możesz użyć useDictionaryDynamic. Jest to przydatne, jeśli nie chcesz pakować wszystkich tłumaczeń w początkowym pliku intlayer.js.

      src/app.js
      const { installIntlayer, useDictionaryDynamic } = window.VanillaIntlayer;

installIntlayer();

const unsubscribe = useDictionaryDynamic(
  {
    en: () => import("../.intlayer/dictionaries/en/app.mjs"),
    fr: () => import("../.intlayer/dictionaries/fr/app.mjs"),
    es: () => import("../.intlayer/dictionaries/es/app.mjs"),
  },
  "app"
).onChange((content) => {
  document.querySelector("h1").textContent = String(content.title);
});
      Uwaga: useDictionaryDynamic wymaga, aby słowniki były dostępne jako oddzielne pliki ESM. Podejście to jest zazwyczaj stosowane, jeśli masz serwer WWW serwujący słowniki.

    Konfiguracja TypeScript

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

    tsconfig.json
    {
  "compilerOptions": {
    // ...
  },
  "include": ["src", ".intlayer/**/*.ts"],
}

    Rozszerzenie VS Code

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

    Zainstaluj z VS Code Marketplace

    To rozszerzenie zapewnia:

    • Autouzupełnianie dla kluczy tłumaczeń.
    • Wykrywanie błędów w czasie rzeczywistym dla brakujących tłumaczeń.
    • Podgląd wewnątrz kodu przetłumaczonej treści.
    • Szybkie akcje, aby łatwo tworzyć i aktualizować tłumaczenia.

    Więcej szczegółów na temat korzystania z rozszerzenia znajdziesz w dokumentacji rozszerzenia Intlayer dla VS Code.

    Idź dalej

    Aby pójść dalej, możesz zaimplementować edytor wizualny lub wyeksportować swoje treści za pomocą CMS.

    Często Zadawane Pytania

    Tak. Temu poświęcony jest ten przewodnik. Importujesz paczkę vanilla-intlayer bezpośrednio w swoim pliku HTML, jak pokazuje krok 3, inicjalizujesz ją i odczytujesz treść za pomocą useIntlayer lub getIntlayer.

    W znacznie mniejszym stopniu niż tradycyjny katalog runtime, ponieważ strona nigdy nie pobiera języka, którego nie renderuje. Treść jest pobierana w zoptymalizowanych formatach, redukując wagę strony w porównaniu z alternatywami. Zobacz optymalizację bundle'a.

    W znacznej mierze tak. Postępuj zgodnie z przewodnikiem migracji z i18next, aby przenieść treść. Możesz także zachować obecne API za pośrednictwem adapterów kompatybilności.

    Tak. Wtyczka sync JSON utrzymuje Twoje pliki /messages/{locale}/{namespace}.json jako źródło prawdy i generuje z nich słowniki Intlayer w obu kierunkach. Wtyczka sync PO robi to samo dla katalogów gettext, a pliki per locale pozwalają rozdzielić zawartość według języka zamiast grupować lokalizacje w jednym pliku.

    Nie. Uruchom npx intlayer extract, a Intlayer odczyta Twoje pliki źródłowe, wyodrębni ciągi widoczne dla użytkownika i utworzy plik .content obok każdego z nich, dzięki czemu przeglądasz diff zamiast ręcznie kopiować ciągi do katalogu pojedynczo.

    W przypadku w pełni zautomatyzowanego procesu Intlayer Compiler robi to samo w czasie kompilacji kodu źródłowego JSX, TSX, Vue i Svelte, generując słowniki przy każdej zmianie, dzięki czemu nie trzeba ręcznie zarządzać kluczami. Działa w oparciu o analizę statyczną, więc ciągi znaków istniejące tylko w czasie wykonywania pozostają poza zasięgiem, a rozróżnienie tekstu dla użytkownika od logiki aplikacji wymaga kilku adnotacji.

    Pięć narzędzi, wszystkie opcjonalne:

    • Rozszerzenie VS Code: przejście od klucza useIntlayer do pliku treści, który go deklaruje, wyodrębnianie treści z komponentu oraz uruchamianie build, fill, test, push i pull z palety poleceń lub dedykowanej karty Intlayer.
    • Serwer LSP: taka sama świadomość w dowolnym edytorze obsługującym LSP, z funkcjami przejdź do definicji (go to definition), znajdź wszystkie referencje, podglądem przetłumaczonej wartości po najechaniu kursorem, autouzupełnianiem kluczy i pól oraz ostrzeżeniem, gdy klucz nie jest nigdzie zadeklarowany. Rozpoznaje również wywołania i18next, react-i18next, next-intl i use-intl, co ułatwia migrację.
    • Serwer MCP: udostępnia dokumentację i CLI Intlayer dla Cursor, VS Code, Claude Desktop, Claude Code i ChatGPT, dzięki czemu asystent odpowiada na podstawie aktualnej dokumentacji zamiast zgadywać i może samodzielnie wykonywać polecenia, takie jak intlayer fill.
    • Umiejętności agenta (Agent skills): wyspecjalizowane umiejętności, takie jak intlayer-config, intlayer-cli i intlayer-content, oraz po jednej dla każdego frameworka, które uczą agenta konfiguracji routingu i typów węzłów treści.
    • Wtyczka ESLint: reguła no-raw-text oznacza zakodowane na stałe ciągi tekstowe, z dodatkowymi regułami dla statycznych kluczy słownika i nieużywanej zawartości.
    Vite dan Vanilla JSVite dan Lit