Creation:2026-03-23Last update:2026-05-31

    Przetłumacz swoją stronę Vite i Vanilla JS za pomocą Intlayer | Internacjonalizacja (i18n)

    ide.intlayer.org

    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:

    Pełny zasięg Vite

    Intlayer jest zoptymalizowany do doskonałej współpracy z Vite, oferując zarządzanie treścią niezależnie od platformy, obsługę TypeScript 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 dotyczący konfiguracji Intlayer w aplikacji Vite i Vanilla JS

    1. Instalacja zależności

      Zainstaluj niezbędne pakiety za pomocą npm:

      bash
      npm install intlayer vanilla-intlayernpm install vite-intlayer --save-devnpx intlayer init

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

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

      • vite-intlayer Zawiera plugin Vite do integracji Intlayer z Vite bundler, a także middleware do wykrywania preferowanego języka użytkownika, zarządzania plikami cookie i obsługi przekierowań adresów URL.

    2. Konfiguracja projektu

      Utwórz plik konfiguracyjny, aby skonfigurować języki 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;
      Poprzez ten plik konfiguracyjny możesz skonfigurować zlokalizowane adresy URL, przekierowania middleware, nazwy plików cookie, 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. Integracja Intlayer w konfiguracji Vite

      Dodaj wtyczkę intlayer do swojej konfiguracji.

      vite.config.ts
      import { defineConfig } from "vite";
import { intlayer } from "vite-intlayer";

// https://vitejs.dev/config/
export default defineConfig({
  plugins: [intlayer()],
});
      Wtyczka intlayer() Vite jest używana do integracji Intlayer z Vite. Zapewnia budowanie plików deklaracji treści i monitoruje je w trybie deweloperskim. Definiuje zmienne środowiskowe Intlayer w aplikacji Vite. Ponadto udostępnia aliasy w celu optymalizacji wydajności.

    4. Uruchomienie Intlayer w punkcie wejścia

      Wywołaj installIntlayer() przed wyrenderowaniem jakiejkolwiek treści, aby globalny singleton języka był gotowy.

      src/main.ts
      import { installIntlayer } from "vanilla-intlayer";// Musi być wywołane przed renderowaniem jakiejkolwiek treści i18n.installIntlayer();// Zaimportuj i uruchom moduły aplikacji.import "./app.js";

      Jeśli używasz również deklaracji treści md() (Markdown), zainstaluj również renderer markdown:

      src/main.ts
      import { installIntlayer, installIntlayerMarkdown } from "vanilla-intlayer";installIntlayer();installIntlayerMarkdown();import "./app.js";

    5. Deklaracja 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 logo Vite, aby dowiedzieć się więcej",
    }),
  },
} satisfies Dictionary;

export default appContent;

      Deklaracje treści mogą być definiowane w dowolnym miejscu w 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życie Intlayer w JavaScript

      vanilla-intlayer odzwierciedla API powierzchniowe react-intlayer: useIntlayer(key, locale?) zwraca przetłumaczoną treść bezpośrednio. Wywołaj .onChange() na wyniku, aby zasubskrybować zmiany języka - co jest jawnym odpowiednikiem re-renderu w React.

      src/main.ts
      import { installIntlayer, useIntlayer } from "vanilla-intlayer";installIntlayer();// Pobierz początkową treść dla aktualnego języka.// Wywołaj .onChange(), aby otrzymywać powiadomienia o każdej zmianie języka.const content = useIntlayer("app").onChange((newContent) => {  // Przerenderuj lub zaktualizuj tylko dotknięte węzły DOM  document.querySelector<HTMLHeadingElement>("h1")!.textContent = String(    newContent.title  );  document.querySelector<HTMLParagraphElement>(".read-the-docs")!.textContent =    String(newContent.readTheDocs);});// Renderewanie początkowedocument.querySelector<HTMLHeadingElement>("h1")!.textContent = String(  content.title);document.querySelector<HTMLParagraphElement>(".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.

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

      typescript
      img.alt = content.viteLogoLabel.value;

    7. Zmiana języka treści

      Opcjonalne

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

      src/locale-switcher.ts
      import { getLocaleName } from "intlayer";import { useLocale } from "vanilla-intlayer";export function setupLocaleSwitcher(container: HTMLElement): () => void {  const { locale, availableLocales, setLocale, subscribe } = useLocale();  const select = document.createElement("select");  select.setAttribute("aria-label", "Language");  const render = (currentLocale: string) => {    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 as any));  // Synchronizuj listę rozwijaną, gdy język zmieni się gdzie indziej  return subscribe((newLocale) => render(newLocale));}

    8. Renderowanie treści Markdown i HTML

      Opcjonalne

      Intlayer obsługuje deklaracje treści md() i html(). W czystym JS skompilowana treść jest wstawiana jako surowy HTML za pomocą innerHTML.

      Kompilacja i wstrzykiwanie HTML:

      src/main.ts
      import {  compileMarkdown,  installIntlayerMarkdown,  useIntlayer,} from "vanilla-intlayer";installIntlayerMarkdown();const content = useIntlayer("app").onChange((newContent) => {  const el = document.querySelector<HTMLDivElement>(".edit-note")!;  el.innerHTML = compileMarkdown(String(newContent.editNote));});document.querySelector<HTMLDivElement>(".edit-note")!.innerHTML =  compileMarkdown(String(content.editNote));
      TIP
      String(content.editNote) wywołuje toString() na IntlayerNode, co zwraca surowy ciąg znaków Markdown. Przekaż go do compileMarkdown, aby uzyskać ciąg HTML, a następnie ustaw za pomocą innerHTML.
      WARNING

      Używaj innerHTML tylko z zaufaną treścią. Jeśli markdown pochodzi od użytkownika, najpierw go zneutralizuj (np. za pomocą DOMPurify). Możesz zainstalować renderer neutralizujący dynamicznie:

      typescript
      import { installIntlayerMarkdownDynamic } from "vanilla-intlayer";await installIntlayerMarkdownDynamic(async () => {  const DOMPurify = await import("dompurify");  return (markdown) => DOMPurify.sanitize(compileMarkdown(markdown));});

    9. Dodawanie zlokalizowanego routingu do aplikacji

      Opcjonalne

      Aby stworzyć unikalne trasy dla każdego języka (przydatne dla SEO), możesz użyć intlayerProxy w konfiguracji Vite do wykrywania języka po stronie serwera.

      Najpierw dodaj intlayerProxy do konfiguracji Vite:

      Pamiętaj, że aby używać intlayerProxy na produkcji, musisz przenieść vite-intlayer z devDependencies do dependencies.
      vite.config.ts
      import { defineConfig } from "vite";
import { intlayer, intlayerProxy } from "vite-intlayer";

export default defineConfig({
  plugins: [
    intlayerProxy(), // powinien być umieszczony jako pierwszy
    intlayer(),
  ],
});

    10. Zmiana adresu URL przy zmianie języka

      Opcjonalne

      Aby aktualizować adres URL w przeglądarce przy zmianie języka, wywołaj useRewriteURL() po zainstalowaniu Intlayer:

      src/main.ts
      import { installIntlayer, useRewriteURL } from "vanilla-intlayer";installIntlayer();// Przepisuje adres URL natychmiast i przy każdej kolejnej zmianie języka.// Zwraca funkcję anulującą subskrypcję w celu wyczyszczenia.const stopRewriteURL = useRewriteURL();

    11. Przełączanie atrybutów języka i kierunku tekstu HTML

      Opcjonalne

      Zaktualizuj atrybuty lang i dir tagu <html>, aby odpowiadały aktualnemu językowi w celu ułatwienia dostępu i SEO.

      src/main.ts
      import { getHTMLTextDir } from "intlayer";import { installIntlayer, useLocale } from "vanilla-intlayer";installIntlayer();useLocale({  onLocaleChange: (locale) => {    document.documentElement.lang = locale;    document.documentElement.dir = getHTMLTextDir(locale);  },});

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

      Opcjonalne

      W przypadku dużych aplikacji możesz chcieć podzielić słownik każdego języka na osobny fragment. Użyj useDictionaryDynamic wraz z dynamicznym import() z Vite:

      src/app.ts
      import { installIntlayer, useDictionaryDynamic } from "vanilla-intlayer";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);});
      Pakiet każdego języka jest pobierany tylko wtedy, gdy ten język stanie się aktywny, a wynik jest buforowany - kolejne przełączenia na ten sam język są natychmiastowe.

    13. Wyodrębnianie treści komponentów

      Opcjonalne

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

      Aby ułatwić ten proces, Intlayer proponuje kompilator / ekstraktor do przekształcania komponentów i wyodrębniania treści.

      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 konfiguracji  compiler: {    /**     * Wskazuje, czy kompilator powinien być włączony.     */    enabled: true,    /**     * Definiuje ścieżkę do plików wyjściowych     */    output: ({ fileName, extension }) => `./${fileName}${extension}`,    /**     * Wskazuje, czy komponenty powinny zostać zapisane po przekształceniu.     * W ten sposób kompilator można uruchomić tylko raz, aby przekształcić aplikację, a następnie go usunąć.     */    saveComponents: false,    /**     * Prefiks klucza słownika     */    dictionaryKeyPrefix: "",  },};export default config;

      Uruchom ekstraktor, aby przekształcić komponenty i wyodrębnić treść

      bash
      npx intlayer extract

    (Opcjonalnie) Sitemap i robots.txt (generacja przy buildzie)

    Intlayer udostępnia generateSitemap i getMultilingualUrls - narzędzia do formatowania wielojęzycznych plików sitemap.xml i robots.txt dla crawlerów i automatycznego zapisu do public/. Zwykle uruchamia się mały skrypt Node przed Vite (np. hooki npm predev / prebuild).

    Sitemap

    Generator sitemap uwzględnia locale i dodaje metadane dla crawlerów.

    Sitemap obsługuje przestrzeń nazw xhtml:link (hreflang). Zamiast płaskiej listy URL Intlayer tworzy dwukierunkowe powiązania wszystkich wersji językowych strony (np. /about, /fr/about lub /about?lang=fr w zależności od routingu).

    Robots.txt

    Użyj getMultilingualUrls, by reguły Disallow obejmowały wszystkie zlokalizowane warianty ścieżek.

    1. Plik generate-seo.mjs w katalogu głównym

    generate-seo.mjs
    import fs from "fs";import path from "path";import { fileURLToPath } from "url";import { generateSitemap, getMultilingualUrls } from "intlayer";const __dirname = path.dirname(fileURLToPath(import.meta.url));const SITE_URL = (process.env.SITE_URL || "http://localhost:5173").replace(  /\/$/,  "");const pathList = [  { path: "/", changefreq: "daily", priority: 1.0 },  { path: "/about", changefreq: "monthly", priority: 0.7 },];const sitemapXml = generateSitemap(pathList, { siteUrl: SITE_URL });fs.writeFileSync(path.join(__dirname, "public", "sitemap.xml"), sitemapXml);const getAllMultilingualUrls = (urls) =>  urls.flatMap((url) => Object.values(getMultilingualUrls(url)));const disallowedPaths = getAllMultilingualUrls(["/admin", "/private"]);const robotsTxt = [  "User-agent: *",  "Allow: /",  ...disallowedPaths.map((path) => `Disallow: ${path}`),  "",  `Sitemap: ${SITE_URL}/sitemap.xml`,].join("\n");fs.writeFileSync(path.join(__dirname, "public", "robots.txt"), robotsTxt);console.log("SEO files generated successfully.");

    Pakiet intlayer musi być zainstalowany. W produkcji ustaw SITE_URL w środowisku (np. w CI).

    Preferuj generate-seo.mjs dla ESM w Node. Przy generate-seo.js ustaw "type": "module" w package.json lub włącz ESM inaczej.

    2. Uruchom skrypt przed Vite

    package.json
    {  "scripts": {    "dev": "vite",    "prebuild": "node generate-seo.mjs",    "build": "vite build",    "preview": "vite preview"  }}

    Dostosuj polecenia dla pnpm lub yarn. Możesz też wywołać skrypt z CI.

    Konfiguracja TypeScript

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

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

    Konfiguracja Git

    Zaleca się ignorowanie plików generowanych przez Intlayer. Pozwala to uniknąć ich zatwierdzania w repozytorium Git.

    Aby to zrobić, możesz dodać 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 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 wierszowy przetłumaczonej treści.
    • Szybkie akcje do łatwego tworzenia i aktualizowania tłumaczeń.

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

    Idź dalej

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

    Vite dan Preact
    Vite dan Lit