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

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:

Przewodnik krok po kroku, jak skonfigurować Intlayer w aplikacji Vite i Svelte

Zobacz Szablon aplikacji na GitHub.

1. 1

   Zainstaluj zależności

   Zainstaluj niezbędne pakiety za pomocą npm:

   bash

   Kopiuj zawartość

   Kopiuj kod

   Skopiuj kod do schowka

   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

   Kopiuj zawartość

   Kopiuj kod

   Skopiuj kod do schowka

   npm install intlayer svelte-intlayer
   npm install vite-intlayer --save-dev
   

   • intlayer

     Główne pakiet, który dostarcza narzędzia do internacjonalizacji do zarządzania konfiguracją, tłumaczeń, deklaracji treści, transpilecji oraz poleceń CLI.

   • svelte-intlayer Pakiet, który integruje Intlayer z aplikacją Svelte. Dostarcza providery kontekstu oraz hooki do internacjonalizacji w Svelte.

   • vite-intlayer Zawiera plugin Vite do integracji Intlayer z bundlerem Vite, a także middleware do wykrywania preferowanego języka użytkownika, zarządzania ciasteczkami oraz obsługi przekierowań URL.

2. 2

   Konfiguracja projektu

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

   intlayer.config.ts

   Kopiuj zawartość

   Kopiuj kod

   Skopiuj kod do schowka

   import { Locales, type IntlayerConfig } from "intlayer";
   
   const config: IntlayerConfig = {
     internationalization: {
       locales: [
         Locales.ENGLISH,
         Locales.FRENCH,
         Locales.SPANISH,
         // Twoje pozostałe lokalizacje
       ],
   
       defaultLocale: Locales.ENGLISH,
     },
   };
   
   export default config;
   

   Poprzez ten plik konfiguracyjny możesz ustawić lokalizowane adresy URL, przekierowania w 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. 3

   Integracja Intlayer w konfiguracji Vite

   Dodaj plugin intlayer do swojej konfiguracji.

   vite.config.ts

   Kopiuj zawartość

   Kopiuj kod

   Skopiuj kod do schowka

   import { defineConfig } from "vite";
   import { svelte } from "@sveltejs/vite-plugin-svelte";
   import { intlayer } from "vite-intlayer";
   
   // https://vitejs.dev/config/
   export default defineConfig({
     plugins: [svelte(), intlayer()],
   });
   

   Wtyczka intlayer() dla Vite służy do integracji Intlayer z Vite. Zapewnia budowanie plików deklaracji treści oraz monitoruje je w trybie deweloperskim. Definiuje zmienne środowiskowe Intlayer w aplikacji Vite. Dodatkowo dostarcza aliasy optymalizujące wydajność.

4. 4

   Zadeklaruj swoją treść

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

   src/app.content.tsx

   Kopiuj zawartość

   Kopiuj kod

   Skopiuj kod do schowka

   import { t, type Dictionary } from "intlayer";
   
   const appContent = {
     key: "app",
     content: {
       title: t({
         en: "Hello World",
         fr: "Bonjour le monde",
         es: "Hola mundo",
       }),
     },
   } satisfies Dictionary;
   
   export default appContent;
   

   Twoje deklaracje zawartości mogą być zdefiniowane w dowolnym miejscu w Twojej aplikacji, pod warunkiem, że zostaną umieszczone w katalogu contentDir (domyślnie ./src). I będą miały rozszerzenie pliku deklaracji zawartości (domyślnie .content.{json,ts,tsx,js,jsx,mjs,cjs,md,mdx,yaml,yml}).

   Aby uzyskać więcej szczegółów, zapoznaj się z dokumentacją deklaracji zawartości.

5. 5

   Wykorzystaj Intlayer w swoim kodzie

   src/App.svelte

   Kopiuj zawartość

   Kopiuj kod

   Skopiuj kod do schowka

   <script>
     import { useIntlayer } from "svelte-intlayer";
   
     const content = useIntlayer("app");
   </script>
   
   <div>
   
   
   <!-- Renderuj zawartość jako prostą zawartość  -->
   <h1>{$content.title}</h1>
   <!-- Aby renderować zawartość edytowalną za pomocą edytora -->
   <h1>{@const Title = $content.title}<Title /></h1>
   <!-- Aby renderować 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>
   

   Jeśli Twoja aplikacja już istnieje, możesz użyć Intlayer Compiler w połączeniu z poleceniem extract, aby przekonwertować tysiące komponentów w jedną sekundę.

6. 6

   Zmień język swojej zawartości

   Opcjonalne

   src/App.svelte

   Kopiuj zawartość

   Kopiuj kod

   Skopiuj kod do schowka

   <script lang="ts">
   import  { getLocaleName } from 'intlayer';
   import { useLocale } from "svelte-intlayer";
   
   // Pobierz informacje o lokalizacji i funkcję setLocale
   const { locale, availableLocales, setLocale } = useLocale();
   
   // Obsłuż zmianę lokalizacji
   const changeLocale = (event: Event) => {
     const target = event.target as HTMLSelectElement;
     const newLocale = target.value;
     setLocale(newLocale);
   };
   </script>
   
   <div>
     <select value={$locale} on:change={changeLocale}>
       {#each availableLocales ?? [] as loc}
         <option value={loc}>
           {getLocaleName(loc)}
         </option>
       {/each}
     </select>
   </div>
   

7. 7

   Renderowanie Markdown

   Opcjonalne

   Intlayer obsługuje renderowanie zawartości Markdown bezpośrednio w Twojej aplikacji Svelte. Domyślnie Markdown jest traktowany jako zwykły tekst. Aby przekształcić Markdown w bogaty HTML, możesz zintegrować @humanspeak/svelte-markdown lub inny parser markdown.

   Aby zobaczyć, jak deklarować zawartość markdown za pomocą pakietu intlayer, zobacz dokumentację markdown.

   src/App.svelte

   Kopiuj zawartość

   Kopiuj kod

   Skopiuj kod do schowka

   <script>
     import { setIntlayerMarkdown } from "svelte-intlayer";
   
     setIntlayerMarkdown((markdown) =>
      // renderuj zawartość markdown jako ciąg znaków
      return markdown;
     );
   </script>
   
   <h1>{$content.markdownContent}</h1>
   

   Możesz również uzyskać dostęp do danych front-matter swojego markdowna, używając właściwości content.markdownContent.metadata.xxx.

8. 8

   Konfiguracja edytora / CMS intlayer

   Opcjonalne

   Aby skonfigurować edytor intlayer, musisz postępować zgodnie z dokumentacją edytora intlayer.

   Aby skonfigurować CMS intlayer, musisz postępować zgodnie z dokumentacją CMS intlayer.

9. 7

   Dodaj lokalizowane routingi do swojej aplikacji

   Opcjonalne

   Aby obsłużyć lokalizowane routingi w swojej aplikacji Svelte, możesz użyć svelte-spa-router wraz z localeFlatMap z Intlayer do generowania tras dla każdej lokalizacji.

   Najpierw zainstaluj svelte-spa-router:

   bash

   Kopiuj zawartość

   Kopiuj kod

   Skopiuj kod do schowka

   npm install svelte-spa-router
   npx intlayer init
   

   Następnie utwórz plik Router.svelte, aby zdefiniować swoje trasy:

   src/Router.svelte

   Kopiuj zawartość

   Kopiuj kod

   Skopiuj kod do schowka

   <script lang="ts">
   import { localeFlatMap } from "intlayer";
   import Router from "svelte-spa-router";
   import { wrap } from "svelte-spa-router/wrap";
   import App from "./App.svelte";
   
   const routes = Object.fromEntries(
       localeFlatMap(({locale, urlPrefix}) => [
       [
           urlPrefix || '/',
           wrap({
               component: App as any,
               props: {
                   locale,
               },
           }),
       ],
       ])
   );
   </script>
   
   <Router {routes} />
   

   Zaktualizuj swój plik main.ts, aby zamontować komponent Router zamiast App:

   src/main.ts

   Kopiuj zawartość

   Kopiuj kod

   Skopiuj kod do schowka

   import { mount } from "svelte";
   import Router from "./Router.svelte";
   
   const app = mount(Router, {
     target: document.getElementById("app")!,
   });
   
   export default app;
   

   Na koniec zaktualizuj swój plik App.svelte, aby otrzymywał właściwość locale i używał jej z useIntlayer:

   src/App.svelte

   Kopiuj zawartość

   Kopiuj kod

   Skopiuj kod do schowka

   <script lang="ts">
   import type { Locale } from 'intlayer';
   import { useIntlayer } from "svelte-intlayer";
   import Counter from './lib/Counter.svelte';
   import LocaleSwitcher from './lib/LocaleSwitcher.svelte';
   
   export let locale: Locale;
   
   $: content = useIntlayer('app', locale);
   </script>
   
   <main>
     <div class="locale-switcher-container">
       <LocaleSwitcher currentLocale={locale} />
     </div>
   
     <!-- ... reszta twojej aplikacji ... -->
   </main>
   

   Konfiguracja routingu po stronie serwera (opcjonalnie)

   Równolegle możesz również użyć intlayerProxy, aby dodać routing po stronie serwera do swojej aplikacji. Ten plugin automatycznie wykryje aktualny język na podstawie URL i ustawi odpowiedni cookie językowy. Jeśli nie zostanie określony żaden język, plugin wybierze najbardziej odpowiedni język na podstawie preferencji językowych przeglądarki użytkownika. Jeśli nie zostanie wykryty żaden język, nastąpi przekierowanie do domyślnego języka.

   Uwaga: aby używać intlayerProxy w środowisku produkcyjnym, musisz przenieść pakiet vite-intlayer z devDependencies do dependencies.

   Od wersji Intlayer v9, intlayerProxy() jest wbudowany bezpośrednio w plugin intlayer() i domyślnie włączony za pomocą opcji routing.enableProxy (true domyślnie). Rejestrowanie go osobno, jak pokazano poniżej, jest teraz opcjonalne — jest zachowywane dla kompatybilności wstecznej i dla konfiguracji, które muszą kontrolować kolejność pluginów. Ustaw routing.enableProxy: false, aby zrezygnować. Zobacz informacje o wydaniu v9.

   vite.config.ts

   Kopiuj zawartość

   Kopiuj kod

   Skopiuj kod do schowka

   import { defineConfig } from "vite";
   import { svelte } from "@sveltejs/vite-plugin-svelte";
   import { intlayer } from "vite-intlayer";
   
     plugins: [intlayerProxy(), // should be placed first
    svelte(), intlayer()],
   });
   

10. 8

    Zmiana URL po zmianie lokalizacji

    Opcjonalne

    Aby umożliwić użytkownikom zmianę języka i odpowiednią aktualizację URL, możesz stworzyć komponent LocaleSwitcher. Komponent ten będzie korzystał z getLocalizedUrl z pakietu intlayer oraz push z svelte-spa-router.

    src/lib/LocaleSwitcher.svelte

    Kopiuj zawartość

    Kopiuj kod

    Skopiuj kod do schowka

    <script lang="ts">
    import { getLocaleName, getLocalizedUrl } from "intlayer";
    import { useLocale } from "svelte-intlayer";
    import { push } from "svelte-spa-router";
    
    export let currentLocale: string | undefined = undefined;
    
    // Pobierz informacje o lokalizacji
    const { locale, availableLocales } = useLocale();
    
    // Obsługa zmiany lokalizacji
    const changeLocale = (event: Event) => {
      const target = event.target as HTMLSelectElement;
      const newLocale = target.value;
      const currentUrl = window.location.pathname;
      const url = getLocalizedUrl( currentUrl, newLocale);
      push(url);
    };
    </script>
    
    <div class="locale-switcher">
      <select value={currentLocale ?? $locale} onchange={changeLocale}>
        {#each availableLocales ?? [] as loc}
          <option value={loc}>
            {getLocaleName(loc)}
          </option>
        {/each}
      </select>
    </div>
    

11. 9

    Wyodrębnij zawartość swoich komponentów

    Opcjonalne

    Ze względów SEO zaleca się poprzedzanie tras ustawieniem języka (np. /about, /fr/about).

    src/lib/components/Link.svelte

    Kopiuj zawartość

    Kopiuj kod

    Skopiuj kod do schowka

    <script lang="ts">
      import { getLocalizedUrl } from "intlayer";
      import { useLocale } from "svelte-intlayer";
    
      export let href = "";
      const { locale } = useLocale();
    
      // Pomocnik do prefiksowania URL
      $: localizedHref = getLocalizedUrl(href, $locale);
    </script>
    
    <a href={localizedHref}>
      <slot />
    </a>
    

12. 10

    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

    Kopiuj zawartość

    Kopiuj kod

    Skopiuj kod do schowka

    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;
    

    Polecenie wyodrębnianiaKompilator Babel

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

    bash

    Kopiuj zawartość

    Kopiuj kod

    Skopiuj kod do schowka

    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

    Kopiuj zawartość

    Kopiuj kod

    Skopiuj kod do schowka

    import { defineConfig } from "vite";
    import { intlayer, intlayerCompiler } from "vite-intlayer";
    
    export default defineConfig({
      plugins: [
        intlayer(),
        intlayerCompiler(), // Adds the compiler plugin
      ],
    });
    

    bash

    Kopiuj zawartość

    Kopiuj kod

    Skopiuj kod do schowka

    npm run build # Lub npm run dev
    

(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

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

{
  "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 Git

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

Aby to zrobić, możesz dodać następujące instrukcje do pliku .gitignore:

# Ignoruj pliki generowane przez Intlayer
.intlayer

Rozszerzenie VS Code

Aby ulepszyć doświadczenie programisty w pracy z Intlayer, możesz zainstalować oficjalne Rozszerzenie Intlayer VS Code.

Zainstaluj 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ądy inline przetłumaczonej zawartości.
• Szybkie akcje do łatwego tworzenia i aktualizacji tłumaczeń.

Aby uzyskać więcej szczegółów na temat korzystania z rozszerzenia, zapoznaj się z dokumentacją Rozszerzenia Intlayer VS Code.

Idź dalej

Aby pójść dalej, możesz zaimplementować edytor wizualny lub wyeksportować swoją zawartość, korzystając z CMS.

Często Zadawane Pytania