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

    Przetłumacz swoją stronę Vite i Lit 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 „lit-localize” czy „i18next”, Intlayer jest rozwiązaniem wyposażonym w zintegrowane optymalizacje, takie jak:

    Pełne pokrycie światłem

    Intlayer jest zoptymalizowany do doskonałej współpracy z Lit, oferując zakres treści na poziomie komponentów sieciowych, obsługę TypeScript i wszystkie funkcje potrzebne do skalowania umiędzynarodowienia (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 Lit

    1. Instalacja zależności

      Zainstaluj niezbędne pakiety za pomocą npm:

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

      • intlayer

        Podstawowy pakiet, który zapewnia narzędzia do internacjonalizacji do zarządzania konfiguracją, tłumaczenia, deklarowania treści, transpilacji i poleceń CLI.

      • lit-intlayer Pakiet integrujący Intlayer z aplikacjami Lit. Zapewnia hooki oparte na ReactiveController (useIntlayer, useLocale itp.), dzięki czemu elementy LitElement automatycznie renderują się ponownie po zmianie języka.

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

    2. Konfiguracja Twojego projektu

      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 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. Zintegruj Intlayer z konfiguracją 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 Vite intlayer() służy do integracji Intlayer z Vite. Zapewnia budowanie plików deklaracji treści i monitoruje je w trybie deweloperskim. Definiuje zmienne środowiskowe Intlayer wewnątrz aplikacji Vite. Dodatkowo zapewnia aliasy w celu optymalizacji wydajności.

    4. Uruchomienie Intlayer w punkcie wejścia

      Wywołaj installIntlayer() przed zarejestrowaniem jakichkolwiek niestandardowych elementów, aby globalny singleton języka był gotowy, gdy pierwszy element się połączy.

      src/main.ts
      import { installIntlayer } from "lit-intlayer";// Musi być wywołane przed podłączeniem dowolnego elementu LitElement do DOM.installIntlayer();// Zaimportuj i zarejestruj swoje niestandardowe elementy.import "./my-element.js";

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

      src/main.ts
      import { installIntlayer, installIntlayerMarkdown } from "lit-intlayer";installIntlayer();installIntlayerMarkdown();import "./my-element.js";

    5. Zadeklaruj swoją treść

      Twórz i zarządzaj deklaracjami treści w celu przechowywania tłumaczeń:

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

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

    viteLogo: t({
      en: "Vite logo",
      fr: "Logo Vite",
      es: "Logo Vite",
    }),
    litLogo: t({
      en: "Lit logo",
      fr: "Logo Lit",
      es: "Logo Lit",
    }),

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

    readTheDocs: t({
      en: "Click on the Vite and Lit logos to learn more",
      fr: "Cliquez sur les logos Vite et Lit pour en savoir plus",
      es: "Haga clic en los logotipos de Vite y Lit para obtener más información",
    }),
  },
} satisfies Dictionary;

export default appContent;

      Deklaracje treści mogą być definiowane w dowolnym miejscu aplikacji, o ile są zawarte 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. Wykorzystaj Intlayer w swoim LitElement

      Użyj useIntlayer wewnątrz LitElement. Zwraca proxy ReactiveController, który automatycznie wyzwala ponowne renderowanie przy każdej zmianie aktywnego języka - nie jest wymagana żadna dodatkowa konfiguracja.

      src/my-element.ts
      import { LitElement, html } from "lit";import { customElement, property } from "lit/decorators.js";import { useIntlayer } from "lit-intlayer";@customElement("my-element")export class MyElement extends LitElement {  @property({ type: Number })  count = 0;  // useIntlayer rejestruje się jako ReactiveController.  // Element renderuje się ponownie automatycznie po zmianie języka.  private content = useIntlayer(this, "app");  override render() {    const { content } = this;    return html`      <h1>${content.title}</h1>      <img src="/vite.svg" alt=${content.viteLogo.value} />      <img src="/lit.svg" alt=${content.litLogo.value} />      <button @click=${() => this.count++}>        ${content.count({ count: this.count })}      </button>      <p>${content.readTheDocs}</p>    `;  }}

      Gdy potrzebujesz przetłumaczonego ciągu znaków w natywnym atrybucie HTML (np. alt, aria-label, title), wywołaj .value na węźle typu liść (leaf node):

      typescript
      html`<img alt=${content.viteLogo.value} />`;html`<img alt=${content.viteLogo.toString()} />`;html`<img alt=${String(content.viteLogo)} />`;

    7. Zmiana języka treści

      Opcjonalne

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

      src/locale-switcher.ts
      import { LitElement, html } from "lit";import { customElement } from "lit/decorators.js";import { getLocaleName } from "intlayer";import { useLocale } from "lit-intlayer";@customElement("locale-switcher")export class LocaleSwitcher extends LitElement {  private locale = useLocale(this);  private _onChange(e: Event) {    const select = e.target as HTMLSelectElement;    this.locale.setLocale(select.value as any);  }  override render() {    return html`      <select @change=${this._onChange}>        ${this.locale.availableLocales.map(          (loc) => html`            <option value=${loc} ?selected=${loc === this.locale.locale}>              ${getLocaleName(loc)}            </option>          `        )}      </select>    `;  }}

    8. Renderowanie treści Markdown i HTML

      Opcjonalne

      Intlayer obsługuje deklaracje treści md() i html(). W Lit skompilowane wyjście jest wstrzykiwane jako surowy kod HTML za pomocą dyrektywy unsafeHTML.

      Wyrenderuj skompilowany kod HTML w swoim elemencie:

      src/my-element.ts
      import { LitElement, html } from "lit";import { customElement } from "lit/decorators.js";import { unsafeHTML } from "lit/directives/unsafe-html.js";import { useIntlayer } from "lit-intlayer";import { compileMarkdown } from "lit-intlayer/markdown";@customElement("my-element")export class MyElement extends LitElement {  private content = useIntlayer(this, "app");  override render() {    return html`      <div class="edit-note">        ${unsafeHTML(compileMarkdown(String(this.content.editNote)))}      </div>    `;  }}
      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 znaków HTML, a następnie wyrenderuj go za pomocą dyrektywy unsafeHTML z biblioteki Lit.

    9. Dodaj zlokalizowany routing do swojej aplikacji

      Opcjonalne

      Aby stworzyć unikalne trasy dla każdego języka (przydatne dla SEO), możesz użyć routera po stronie klienta wraz z pomocnikami Intlayer localeMap / localeFlatMap oraz wtyczką Vite intlayerProxy do wykrywania języka po stronie serwera.

      Najpierw dodaj intlayerProxy do konfiguracji Vite:

      Pamiętaj, że aby korzystać z intlayerProxy w środowisku produkcyjnym, 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: [intlayer(), intlayerProxy()],
});

    10. Zmiana adresu URL po zmianie języka

      Opcjonalne

      Aby zaktualizować adres URL w przeglądarce po zmianie języka, użyj useRewriteURL wraz z przełącznikiem języka:

      src/locale-switcher.ts
      import { LitElement, html } from "lit";import { customElement } from "lit/decorators.js";import { getLocaleName, getLocalizedUrl } from "intlayer";import { useLocale, useRewriteURL } from "lit-intlayer";@customElement("locale-switcher")export class LocaleSwitcher extends LitElement {  private locale = useLocale(this);  // Automatycznie przepisuje bieżący adres URL przy zmianie języka.  private _rewriteURL = useRewriteURL(this);  private _onChange(e: Event) {    const select = e.target as HTMLSelectElement;    this.locale.setLocale(select.value as any);  }  override render() {    return html`      <select @change=${this._onChange}>        ${this.locale.availableLocales.map(          (loc) => html`            <option value=${loc} ?selected=${loc === this.locale.locale}>              ${getLocaleName(loc)}            </option>          `        )}      </select>    `;  }}

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

      Opcjonalne

      Zaktualizuj atrybuty lang i dir tagu <html>, aby odpowiadały bieżącemu językowi w celu zapewnienia dostępności i SEO.

      src/my-element.ts
      import { LitElement, html } from "lit";import { customElement } from "lit/decorators.js";import { getHTMLTextDir } from "intlayer";import { useLocale } from "lit-intlayer";@customElement("my-element")export class MyElement extends LitElement {  private locale = useLocale(this, {    onLocaleChange: (loc) => {      document.documentElement.lang = loc;      document.documentElement.dir = getHTMLTextDir(loc);    },  });  override render() {    return html`<!-- Twoja treść -->`;  }}

    12. Wyodrębnij treść 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 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 Twojej 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 transformacji.     * W ten sposób kompilator można uruchomić tylko raz, aby przekształcić aplikację, a następnie można go usunąć.     */    saveComponents: false,    /**     * Prefiks klucza słownika     */    dictionaryKeyPrefix: "",  },};export default config;

    (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 Twoja konfiguracja TypeScript zawiera automatycznie generowane typy.

    tsconfig.json
    {  "compilerOptions": {    // ...    "experimentalDecorators": true,    "useDefineForClassFields": false,  },  "include": ["src", ".intlayer/**/*.ts"],}
    experimentalDecorators oraz useDefineForClassFields: false są wymagane przez Lit do obsługi dekoratorów.

    Konfiguracja Git

    Zaleca się ignorowanie plików generowanych przez Intlayer. Pozwala to uniknąć zatwierdzania ich 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ądy w tekście przetłumaczonej treści.
    • Szybkie akcje ułatwiające tworzenie i aktualizowanie tłumaczeń.

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

    Dowiedz się więcej

    Aby dowiedzieć się więcej, możesz zaimplementować edytor wizualny lub wyeksportować treść za pomocą CMS.

    Vite dan Vanilla JS
    Angular 21