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

Spis treści

Czym jest Intlayer?

Intlayer to innowacyjna, open-source'owa biblioteka do internacjonalizacji (i18n), zaprojektowana, aby uprościć wsparcie wielojęzyczne w nowoczesnych aplikacjach webowych.

Dzięki Intlayer możesz:

• Łatwo zarządzać tłumaczeniami za pomocą deklaratywnych słowników na poziomie komponentu.
• Dynamicznie lokalizować metadane, trasy i zawartość.
• Zapewnić wsparcie dla TypeScript dzięki automatycznie generowanym typom, co poprawia autouzupełnianie i wykrywanie błędów.
• Korzystać z zaawansowanych funkcji, takich jak dynamiczne wykrywanie i przełączanie lokalizacji.

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

Zobacz Szablon aplikacji na GitHub.

Krok 1: Zainstaluj zależności

Zainstaluj niezbędne pakiety za pomocą npm:

npm install intlayer svelte-intlayernpm 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.

Krok 2: Konfiguracja projektu

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

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.

Krok 3: Integracja Intlayer w konfiguracji Vite

Dodaj plugin intlayer do swojej konfiguracji.

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ść.

Krok 4: Zadeklaruj swoją treść

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

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,mjx,cjs,cjx}).

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

Krok 5: Wykorzystaj Intlayer w swoim kodzie

<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><svelte:component this={$content.title} /></h1><!-- Aby renderować zawartość jako ciąg znaków --><div aria-label={$content.title.value}></div>

(Opcjonalny) Krok 6: Zmień język swojej zawartości

<script lang="ts">import  { getLocaleName } from 'intlayer';import { useLocale } from 'svelte-intlayer';// Pobierz informacje o lokalizacji i funkcję setLocaleconst { locale, availableLocales, setLocale } = useLocale();// Obsłuż zmianę lokalizacjiconst 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>

(Opcjonalny) Krok 7: Renderowanie Markdown

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.

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

(Opcjonalny) Krok 8: Konfiguracja edytora / CMS intlayer

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

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

Równolegle, w swojej aplikacji Svelte, musisz dodać następującą linię w layoucie lub na poziomie root aplikacji:

import { useIntlayerEditor } from "svelte-intlayer";useIntlayerEditor();

(Opcjonalny) Krok 7: Dodaj lokalizowane routingi do swojej aplikacji

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:

npm install svelte-spa-router

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

<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:

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:

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

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

(Opcjonalny) Krok 8: Zmiana URL po zmianie lokalizacji

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.

<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 lokalizacjiconst { locale, availableLocales } = useLocale();// Obsługa zmiany lokalizacjiconst 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>

Konfiguracja Git

Zaleca się ignorowanie plików generowanych przez Intlayer. Pozwala to uniknąć ich zatwierdzania 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 poprawić swoje doświadczenie w pracy z Intlayer, możesz zainstalować oficjalne rozszerzenie Intlayer dla VS Code.

Zainstaluj z VS Code Marketplace

To rozszerzenie oferuje:

• Autouzupełnianie kluczy tłumaczeń.
• Wykrywanie błędów w czasie rzeczywistym dla brakujących tłumaczeń.
• Podglądy w linii przetłumaczonej zawartości.
• Szybkie akcje umożliwiające łatwe tworzenie i aktualizowanie tłumaczeń.

Aby uzyskać więcej informacji na temat korzystania z rozszerzenia, zapoznaj się z dokumentacją rozszerzenia Intlayer dla VS Code.

Idź dalej

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