Autor:
    Aymeric PINEAU
    Data utworzenia:2025-11-20Ostatnia aktualizacja:2026-05-31

    Przetłumacz swoją stronę SvelteKit za pomocą Intlayer | Internacjonalizacja (i18n)

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

    Spis treści

    Dlaczego Interlayer zamiast alternatyw?

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

    Pełne pokrycie SvelteKit

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

    </Accordion>

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

    </Accordion>

    Ł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 agent skills, 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.

    </Accordion>

    Przewodnik krok po kroku: konfiguracja Intlayer w aplikacji SvelteKit

    Zobacz Application Template na GitHub.

    Aby rozpocząć, utwórz nowy projekt SvelteKit. Oto końcowa struktura, którą stworzymy:

    bash
    .
├── intlayer.config.ts
├── package.json
├── src
│   ├── app.d.ts
│   ├── app.html
│   ├── hooks.server.ts
│   ├── lib
│   │   ├── getLocale.ts
│   │   ├── LocaleSwitcher.svelte
│   │   └── LocalizedLink.svelte
│   ├── params
│   │   └── locale.ts
│   └── routes
│       ├── [[locale=locale]]
│       │   ├── +layout.svelte
│       │   ├── +layout.ts
│       │   ├── +page.svelte
│       │   ├── +page.ts
│       │   ├── about
│       │   │   ├── +page.svelte
│       │   │   ├── +page.ts
│       │   │   └── page.content.ts
│       │   ├── Counter.content.ts
│       │   ├── Counter.svelte
│       │   ├── Header.content.ts
│       │   ├── Header.svelte
│       │   ├── home.content.ts
│       │   └── layout.content.ts
│       ├── +layout.svelte
│       └── layout.css
├── static
│   ├── favicon.svg
│   └── robots.txt
├── svelte.config.js
├── tsconfig.json
└── vite.config.ts

    1. Instalacja zależności

      Zainstaluj niezbędne pakiety za pomocą npm:

      bash
      npx intlayer init --interactive
      flaga --interactive jest opcjonalna. Użyj intlayer-cli init, jeśli jesteś agentem AI.
      To polecenie wykryje Twoje środowisko i zainstaluje wymagane pakiety. Na przykład:
      bash
      npm install intlayer svelte-intlayer
npm install vite-intlayer --save-dev
      • intlayer: Podstawowy pakiet i18n.
      • svelte-intlayer: Zapewnia dostawców kontekstu i sklepy dla Svelte/SvelteKit.
      • vite-intlayer: Wtyczka Vite do integracji deklaracji treści z procesem budowania.

    2. Konfiguracja projektu

      Utwórz plik konfiguracyjny w katalogu głównym projektu:

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

const config: IntlayerConfig = {
  internationalization: {
    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
    defaultLocale: Locales.ENGLISH,
  },
};

export default config;

    3. Integracja Intlayer w konfiguracji Vite

      Zaktualizuj swój plik vite.config.ts, aby uwzględnić wtyczkę Intlayer. Ta wtyczka obsługuje transpileację Twoich plików z treścią.

      vite.config.ts
      import { sveltekit } from "@sveltejs/kit/vite";
import { defineConfig } from "vite";
import { intlayer } from "vite-intlayer";

export default defineConfig({
  plugins: [intlayer(), sveltekit()], // kolejność ma znaczenie, Intlayer powinien być umieszczony przed SvelteKit
});

    4. Zadeklaruj swoją treść

      Utwórz pliki deklaracji treści w dowolnym miejscu w folderze src (np. src/lib/content lub obok swoich komponentów). Pliki te definiują tłumaczoną treść dla Twojej aplikacji, używając funkcji t() dla każdego języka.

    5. Wykorzystaj Intlayer w swoich komponentach

      Teraz możesz używać funkcji useIntlayer w dowolnym komponencie Svelte. Zwraca ona reaktywny store, który automatycznie aktualizuje się, gdy zmieni się locale. Funkcja będzie automatycznie respektować bieżący locale (zarówno podczas SSR, jak i nawigacji po stronie klienta).

      , aby uzyskać dostęp do jego reaktywnej wartości (np. $content.title).

      src/lib/components/Component.svelte
      <script lang="ts">
  import { useIntlayer } from "svelte-intlayer";

  // "hero-section" odpowiada kluczowi zdefiniowanemu w Kroku 4
  const content = useIntlayer("hero-section");
</script>

<!-- Renderuj treść jako prostą zawartość -->
<h1>{$content.title}</h1>
<!-- Aby renderować treść edytowalną za pomocą edytora -->
<h1>{@const Title = $content.title}<Title /></h1>
<!-- Aby wyrenderować zawartość jako ciąg znaków -->
<div aria-label={$content.title.value}></div>
<div aria-label={$content.title.toString()}></div>
<div aria-label={String($content.title)}></div>

    6. Skonfiguruj routing

      Opcjonalne

      Poniższe kroki pokazują, jak skonfigurować routing oparty na lokalizacji w SvelteKit. Pozwala to na dodanie prefiksu lokalizacji do adresów URL (np. /en/about, /fr/about) dla lepszego SEO i doświadczenia użytkownika.

      bash
      .
└─── src
    ├── app.d.ts                  # Definiuje typ lokalizacji
    ├── hooks.server.ts           # Zarządza routingiem lokalizacji
    ├── lib
    │   └── getLocale.ts          # Sprawdza lokalizację z nagłówka, ciasteczek
    ├── params
    │   └── locale.ts             # Definiuje parametr lokalizacji
    └── routes
        ├── [[locale=locale]]     # Opakowuje w grupę tras, aby ustawić lokalizację
        │   ├── +layout.svelte    # Lokalny layout dla trasy
        │   ├── +layout.ts
        │   ├── +page.svelte
        │   ├── +page.ts
        │   └── about
        │       ├── +page.svelte
        │       └── +page.ts
        └── +layout.svelte         # Główny layout dla fontów i stylów globalnych

    7. Obsługa wykrywania lokalizacji po stronie serwera

      W SvelteKit serwer musi znać lokalizację użytkownika, aby wyrenderować odpowiednią zawartość podczas SSR. Używamy hooks.server.ts do wykrywania lokalizacji z URL lub ciasteczek.

      Utwórz lub zmodyfikuj plik src/hooks.server.ts:

      src/hooks.server.ts
      import type { Handle } from "@sveltejs/kit";
import { getLocalizedUrl } from "intlayer";
import { getLocale } from "$lib/getLocale";

export const handle: Handle = async ({ event, resolve }) => {
  const detectedLocale = getLocale(event);

  // Sprawdź, czy bieżąca ścieżka już zaczyna się od lokalizacji (np. /fr, /en)
  const pathname = event.url.pathname;
  const targetPathname = getLocalizedUrl(pathname, detectedLocale);

  // Jeśli w URL nie ma lokalizacji (np. użytkownik odwiedza "/"), przekieruj go
  if (targetPathname !== pathname) {
    return new Response(undefined, {
      headers: { Location: targetPathname },
      status: 307, // Tymczasowe przekierowanie
    });
  }

  return resolve(event, {
    transformPageChunk: ({ html }) => html.replace("%lang%", detectedLocale),
  });
};

      Następnie utwórz pomocnika do pobierania lokalizacji użytkownika z eventu żądania:

      src/lib/getLocale.ts
      import {
  configuration,
  getLocaleFromStorage,
  localeDetector,
  type Locale,
} from "intlayer";
import type { RequestEvent } from "@sveltejs/kit";

/**
 * Pobierz lokalizację użytkownika z eventu żądania.
 * Ta funkcja jest używana w hooku `handle` w `src/hooks.server.ts`.
 *
 * Najpierw próbuje pobrać lokalizację z magazynu Intlayer (ciasteczka lub niestandardowe nagłówki).
 * Jeśli lokalizacja nie zostanie znaleziona, następuje odwołanie do negocjacji "Accept-Language" przeglądarki.
 *
 * @param event - Event żądania z SvelteKit
 * @returns Lokalizacja użytkownika
 */
export const getLocale = (event: RequestEvent): Locale => {
  const defaultLocale = configuration?.internationalization?.defaultLocale;

  // Próba pobrania lokalizacji z magazynu Intlayer (ciasteczka lub nagłówki)
  const storedLocale = getLocaleFromStorage({
    // Dostęp do ciasteczek SvelteKit
    getCookie: (name: string) => event.cookies.get(name) ?? null,
    // Dostęp do nagłówków SvelteKit
    getHeader: (name: string) => event.request.headers.get(name) ?? null,
  });

  if (storedLocale) {
    return storedLocale;
  }

  // Powrót do negocjacji "Accept-Language" przeglądarki
  const negotiatorHeaders: Record<string, string> = {};

  // Konwersja obiektu Headers SvelteKit na zwykły Record<string, string>
  event.request.headers.forEach((value, key) => {
    negotiatorHeaders[key] = value;
  });

  // Sprawdzenie lokalizacji z nagłówka `Accept-Language`
  const userFallbackLocale = localeDetector(negotiatorHeaders);

  if (userFallbackLocale) {
    return userFallbackLocale;
  }

  // Zwróć domyślną lokalizację, jeśli nie znaleziono dopasowania
  return defaultLocale;
};
      getLocaleFromStorage sprawdzi lokalizację na podstawie nagłówka lub ciasteczka w zależności od Twojej konfiguracji. Zobacz Konfiguracja po więcej szczegółów.
      Funkcja localeDetector przetworzy nagłówek Accept-Language i zwróci najlepsze dopasowanie.

      Jeśli lokalizacja nie jest skonfigurowana, chcemy zwrócić błąd 404. Aby to ułatwić, możemy stworzyć funkcję match, która sprawdzi, czy lokalizacja jest poprawna:

      /src/params/locale.ts
      export const match = (param: Locale = defaultLocale): boolean =>
  locales.includes(param);

      Uwaga: Upewnij się, że Twój plik src/app.d.ts zawiera definicję lokalizacji:

      typescript
      declare global {
  namespace App {
    interface Locals {
      locale: import("intlayer").Locale;
    }
  }
}

      Dla pliku +layout.svelte możemy usunąć wszystko, aby zachować tylko statyczną zawartość, niezwiązaną z i18n:

      src/+layout.svelte
      <script lang="ts">
     import './layout.css';

    let { children } = $props();
</script>

<div class="app">
    {@render children()}
</div>

<style>
    .app {
    /*  */
    }
</style>

      Następnie utwórz nową stronę i layout w grupie [[locale=locale]]:

      src/routes/[[locale=locale]]/+layout.ts
      import type { Load } from "@sveltejs/kit";
import { defaultLocale, type Locale } from "intlayer";

export const prerender = true;

// Użyj generycznego typu Load
export const load: Load = ({ params }) => {
  const locale: Locale = (params.locale as Locale) ?? defaultLocale;

  return {
    locale,
  };
};
      src/routes/[[locale=locale]]/+layout.svelte
      <script lang="ts">
    import type { Snippet } from 'svelte';
    import { useIntlayer, setupIntlayer } from "svelte-intlayer";
    import Header from './Header.svelte';
    import type { LayoutData } from './$types';

    let { children, data }: { children: Snippet, data: LayoutData } = $props();

    // Inicjalizuj Intlayer z lokalizacją z trasy
  $effect(() => {
      setupIntlayer(data.locale);
  });
    // Użyj słownika zawartości layoutu
    const layoutContent = useIntlayer('layout');
</script>

<Header />

<main>
    {@render children()}
</main>

<footer>
    <p>
        {$layoutContent.footer.prefix.value}{' '}
        <a href="https://svelte.dev/docs/kit">{$layoutContent.footer.linkLabel.value}</a>{' '}
        {$layoutContent.footer.suffix.value}
    </p>
</footer>

<style>
  /*  */
</style>
      src/routes/[[locale=locale]]/+page.ts
      export const prerender = true;
      src/routes/[[locale=locale]]/+page.svelte
      <script lang="ts">
    import { useIntlayer } from "svelte-intlayer";

    // Użyj słownika treści strony głównej
    const homeContent = useIntlayer('home');
</script>

<svelte:head>
    <title>{$homeContent.title.value}</title>
</svelte:head>

<section>
    <h1>
        {$homeContent.title}
    </h1>
</section>

<style>
  /*  */
</style>

    8. Linki z internacjonalizacją

      Opcjonalne

      Dla SEO zaleca się poprzedzanie swoich ścieżek lokalizacją (np. /en/about, /fr/about). Ten komponent automatycznie dodaje prefiks lokalizacji do każdego linku.

      src/lib/components/LocalizedLink.svelte
      <script lang="ts">
  import { getLocalizedUrl } from "intlayer";
  import { useLocale } from "svelte-intlayer";

  let { href = "" } = $props();
  const { locale } = useLocale();

  // Pomocnik do dodawania prefiksu lokalizacji do URL
  $: localizedHref = getLocalizedUrl(href, $locale);
</script>

<a href={localizedHref}>
  <slot />
</a>

      Jeśli używasz goto z SvelteKit, możesz zastosować tę samą logikę z getLocalizedUrl, aby nawigować do zlokalizowanego URL:

      typescript
      import { goto } from "$app/navigation";
import { getLocalizedUrl } from "intlayer";
import { useLocale } from "svelte-intlayer";

const { locale } = useLocale();
const localizedPath = getLocalizedUrl("/about", $locale);
goto(localizedPath); // Nawiguje do /en/about lub /fr/about w zależności od lokalizacji

    9. Przełącznik języka

      Opcjonalne

      Aby umożliwić użytkownikom zmianę języka, zaktualizuj URL.

      src/lib/components/LanguageSwitcher.svelte
      <script lang="ts">
  import { getLocalizedUrl, getLocaleName } from 'intlayer';
  import { useLocale } from "svelte-intlayer";
  import { page } from '$app/stores';
  import { goto } from '$app/navigation';

  const { locale, setLocale, availableLocales } = useLocale({
    onLocaleChange: (newLocale) => {
      const localizedPath = getLocalizedUrl($page.url.pathname, newLocale);
      goto(localizedPath);
    },
  });
</script>

<ul class="locale-list">
  {#each availableLocales as localeEl}
    <li>
      <a
        href={getLocalizedUrl($page.url.pathname, localeEl)}
        onclick={(e) => {
          e.preventDefault();
          setLocale(localeEl); // Ustawi locale w store i wywoła onLocaleChange
        }}
        class:active={$locale === localeEl}
      >
        {getLocaleName(localeEl)}
      </a>
    </li>
  {/each}
</ul>

<style>
  /* */
</style>

    10. Dodaj backend proxy

      Opcjonalne

      Aby dodać backend proxy do swojej aplikacji SvelteKit, możesz użyć funkcji intlayerProxy dostarczonej przez wtyczkę vite-intlayer. Ta wtyczka automatycznie wykryje najlepszy locale dla użytkownika na podstawie URL, ciasteczek i preferencji językowych przeglądarki.

      Od wersji Intlayer v9, intlayerProxy() jest wbudowany bezpośrednio w wtyczkę intlayer() i domyślnie włączony za pomocą opcji routing.enableProxy (true domyślnie). Rejestrowanie go oddzielnie, jak pokazano poniżej, jest teraz opcjonalne — jest zachowywane dla zgodności wstecznej i dla konfiguracji, które wymagają kontroli kolejności wtyczek. Ustaw routing.enableProxy: false, aby zrezygnować. Zobacz uwagi do wydania v9.
      vite.config.ts
      import { defineConfig } from "vite";
import { intlayer } from "vite-intlayer";
import { sveltekit } from "@sveltejs/kit/vite";

// https://vitejs.dev/config/
export default defineConfig({
  plugins: [
    intlayer({
      proxy: {
        ignore: (req) => req.url?.startsWith("/api"),
      },
    }),
    sveltekit(),
  ],],
});

    11. Konfiguracja edytora intlayer / CMS

      Opcjonalne

      Aby skonfigurować edytor intlayer, należy postępować zgodnie z dokumentacją edytora intlayer.

      Aby skonfigurować CMS intlayer, należy postępować zgodnie z dokumentacją CMS intlayer.

      Aby móc wizualizować selektor edytora intlayer, musisz użyć składni komponentu w swojej zawartości intlayer.

      Component.svelte
      <script lang="ts">
  import { useIntlayer } from "svelte-intlayer";

  const content = useIntlayer("component");
</script>

<div>

  <!-- Renderuj zawartość jako prostą zawartość -->
  <h1>{$content.title}</h1>

  <!-- Renderuj zawartość jako komponent (wymagane przez edytor) -->
  {@const Component = $content.component}<Component />
</div>

    12. 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
      Since v9, the intlayerCompiler is included in the intlayer plugin. So you don't need to add it manually.

      Zaktualizuj vite.config.ts, aby dołączyć wtyczkę intlayerCompiler:

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

export default defineConfig({
  plugins: [
    intlayer(),
    intlayerCompiler(), // Adds the compiler plugin
  ],
});
      bash
      npm run build # Lub npm run dev

    Konfiguracja Git

    Zaleca się ignorowanie plików generowanych przez Intlayer.

    .gitignore
    # Ignoruj pliki generowane przez Intlayer
.intlayer

    Idź dalej

    • Edytor wizualny: Zintegruj Intlayer Visual Editor, aby edytować tłumaczenia bezpośrednio z interfejsu użytkownika.
    • CMS: Zewnętrz zarządzanie treścią, korzystając z Intlayer CMS.
    Vite dan SvelteVite dan Preact