Übersetzen Sie Ihre Vite- und Svelte-Website mit Intlayer | Internationalisierung (i18n)

Inhaltsverzeichnis

Was ist Intlayer?

Intlayer ist eine innovative, Open-Source Internationalisierungsbibliothek (i18n), die entwickelt wurde, um die mehrsprachige Unterstützung in modernen Webanwendungen zu vereinfachen.

Mit Intlayer können Sie:

• Übersetzungen einfach verwalten durch deklarative Wörterbücher auf Komponentenebene.
• Metadaten, Routen und Inhalte dynamisch lokalisieren.
• TypeScript-Unterstützung sicherstellen durch automatisch generierte Typen, die Autovervollständigung und Fehlererkennung verbessern.
• Von erweiterten Funktionen profitieren, wie dynamische Spracherkennung und Umschaltung.

Schritt-für-Schritt-Anleitung zur Einrichtung von Intlayer in einer Vite- und Svelte-Anwendung

Siehe Application Template auf GitHub.

Schritt 1: Abhängigkeiten installieren

Installieren Sie die notwendigen Pakete mit npm:

npm install intlayer svelte-intlayerbash packageManager="npm"npm install intlayer svelte-intlayernpm install vite-intlayer --save-dev

• intlayer

  Das Kernpaket, das Internationalisierungswerkzeuge für Konfigurationsmanagement, Übersetzung, Inhaltsdeklaration, Transpilierung und CLI-Befehle bereitstellt.

• svelte-intlayer
  Das Paket, das Intlayer in Svelte-Anwendungen integriert. Es stellt Context-Provider und Hooks für die Internationalisierung in Svelte bereit.

• vite-intlayer
  Beinhaltet das Vite-Plugin zur Integration von Intlayer mit dem Vite-Bundler sowie Middleware zur Erkennung der bevorzugten Sprache des Nutzers, Verwaltung von Cookies und Handhabung von URL-Weiterleitungen.

Schritt 2: Konfiguration Ihres Projekts

Erstellen Sie eine Konfigurationsdatei, um die Sprachen Ihrer Anwendung zu konfigurieren:

import { Locales, type IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  internationalization: {    locales: [      Locales.ENGLISH,      Locales.FRENCH,      Locales.SPANISH,      // Ihre weiteren Sprachen    ],    defaultLocale: Locales.ENGLISH,  },};export default config;

Über diese Konfigurationsdatei können Sie lokalisierte URLs, Middleware-Weiterleitungen, Cookie-Namen, den Speicherort und die Erweiterung Ihrer Inhaltsdeklarationen einrichten, Intlayer-Logs in der Konsole deaktivieren und mehr. Für eine vollständige Liste der verfügbaren Parameter verweisen wir auf die Konfigurationsdokumentation.

Schritt 3: Integrieren Sie Intlayer in Ihre Vite-Konfiguration

Fügen Sie das Intlayer-Plugin in Ihre Konfiguration ein.

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()],});

Das intlayer() Vite-Plugin wird verwendet, um Intlayer mit Vite zu integrieren. Es sorgt für den Aufbau der Inhaltsdeklarationsdateien und überwacht diese im Entwicklungsmodus. Es definiert Intlayer-Umgebungsvariablen innerhalb der Vite-Anwendung. Zusätzlich stellt es Aliase bereit, um die Leistung zu optimieren.

Schritt 4: Deklarieren Sie Ihren Inhalt

Erstellen und verwalten Sie Ihre Inhaltsdeklarationen, um Übersetzungen zu speichern:

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;

Ihre Inhaltsdeklarationen können überall in Ihrer Anwendung definiert werden, sobald sie in das Verzeichnis contentDir (standardmäßig ./src) aufgenommen werden. Und die Dateiendung der Inhaltsdeklaration muss übereinstimmen (standardmäßig .content.{json,ts,tsx,js,jsx,mjs,mjx,cjs,cjx}).

Für weitere Details siehe die Dokumentation zur Inhaltsdeklaration.

Schritt 5: Intlayer in Ihrem Code verwenden

<script>  import { useIntlayer } from "svelte-intlayer";  const content = useIntlayer("app");</script><div><!-- Inhalt als einfachen Inhalt rendern --><h1>{$content.title}</h1><!-- Um den Inhalt editierbar mit dem Editor zu rendern --><h1><svelte:component this={$content.title} /></h1><!-- Um den Inhalt als String zu rendern --><div aria-label={$content.title.value}></div>

(Optional) Schritt 6: Ändern Sie die Sprache Ihres Inhalts

<script lang="ts">import  { getLocaleName } from 'intlayer';import { useLocale } from 'svelte-intlayer';// Lokale Informationen und setLocale-Funktion abrufenconst { locale, availableLocales, setLocale } = useLocale();// Lokale Änderung behandelnconst 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>

(Optional) Schritt 7: Markdown rendern

Intlayer unterstützt das direkte Rendern von Markdown-Inhalten in Ihrer Svelte-Anwendung. Standardmäßig wird Markdown als reiner Text behandelt. Um Markdown in reichhaltiges HTML umzuwandeln, können Sie @humanspeak/svelte-markdown oder einen anderen Markdown-Parser integrieren.

Um zu sehen, wie man Markdown-Inhalte mit dem intlayer-Paket deklariert, siehe die Markdown-Dokumentation.

<script>  import { setIntlayerMarkdown } from "svelte-intlayer";  setIntlayerMarkdown((markdown) =>   // rendere den Markdown-Inhalt als String   return markdown;  );</script><h1>{$content.markdownContent}</h1>

Sie können auch auf Ihre Markdown-Front-Matter-Daten über die Eigenschaft content.markdownContent.metadata.xxx zugreifen.

(Optional) Schritt 8: Einrichten des intlayer Editors / CMS

Um den intlayer Editor einzurichten, müssen Sie der intlayer Editor Dokumentation folgen.

Um das intlayer CMS einzurichten, müssen Sie der intlayer CMS Dokumentation folgen.

Parallel dazu müssen Sie in Ihrer Svelte-Anwendung die folgende Zeile in einem Layout oder im Root Ihrer Anwendung hinzufügen:

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

(Optional) Schritt 7: Lokalisierte Routing zu Ihrer Anwendung hinzufügen

Um lokalisierte Routen in Ihrer Svelte-Anwendung zu verwalten, können Sie svelte-spa-router zusammen mit Intlayers localeFlatMap verwenden, um Routen für jede Locale zu generieren.

Installieren Sie zuerst svelte-spa-router:

npm install svelte-spa-router

Erstellen Sie dann eine Datei Router.svelte, um Ihre Routen zu definieren:

<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} />

Aktualisieren Sie Ihre main.ts, um die Router-Komponente anstelle von App zu mounten:

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

Aktualisieren Sie abschließend Ihre App.svelte, um die locale-Prop zu empfangen und sie mit useIntlayer zu verwenden:

<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>  <!-- ... der Rest Ihrer App ... --></main>

Serverseitiges Routing konfigurieren (optional)

Parallel dazu können Sie auch den intlayerProxy verwenden, um serverseitiges Routing zu Ihrer Anwendung hinzuzufügen. Dieses Plugin erkennt automatisch die aktuelle Locale basierend auf der URL und setzt das entsprechende Locale-Cookie. Wenn keine Locale angegeben ist, bestimmt das Plugin die am besten geeignete Locale basierend auf den Spracheinstellungen des Browsers des Benutzers. Wenn keine Locale erkannt wird, erfolgt eine Weiterleitung zur Standard-Locale.

Hinweis: Um den intlayerProxy in der Produktion zu verwenden, müssen Sie das Paket vite-intlayer von devDependencies zu dependencies verschieben.

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

(Optional) Schritt 8: Ändern der URL, wenn sich die Locale ändert

Um Benutzern das Wechseln der Sprache zu ermöglichen und die URL entsprechend zu aktualisieren, können Sie eine LocaleSwitcher-Komponente erstellen. Diese Komponente verwendet getLocalizedUrl von intlayer und push von 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;// Locale-Informationen abrufenconst { locale, availableLocales } = useLocale();// Locale-Wechsel behandelnconst changeLocale = (event: Event) => {  plugins: [svelte(), intlayer(), intlayerProxy()],});

(Optional) Schritt 8: URL ändern, wenn sich die Locale ändert

Um Benutzern das Wechseln der Sprache und die entsprechende Aktualisierung der URL zu ermöglichen, können Sie eine LocaleSwitcher-Komponente erstellen. Diese Komponente verwendet getLocalizedUrl von intlayer und push von 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;// Locale-Informationen abrufenconst { locale, availableLocales } = useLocale();// Locale-Änderung behandelnconst 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>

Git-Konfiguration

Es wird empfohlen, die von Intlayer generierten Dateien zu ignorieren. Dadurch vermeiden Sie, diese versehentlich in Ihr Git-Repository zu committen.

Fügen Sie dazu die folgenden Anweisungen in Ihre .gitignore-Datei ein:

# Ignoriere die von Intlayer generierten Dateien.intlayer

VS Code Erweiterung

Um Ihre Entwicklungserfahrung mit Intlayer zu verbessern, können Sie die offizielle Intlayer VS Code Extension installieren.

Im VS Code Marketplace installieren

Diese Erweiterung bietet:

• Autovervollständigung für Übersetzungsschlüssel.
• Echtzeit-Fehlererkennung für fehlende Übersetzungen.
• Inline-Vorschauen des übersetzten Inhalts.
• Schnellaktionen, um Übersetzungen einfach zu erstellen und zu aktualisieren.

Für weitere Details zur Verwendung der Erweiterung lesen Sie die Intlayer VS Code Extension Dokumentation.

Weiterführende Schritte

Um weiterzugehen, können Sie den visuellen Editor implementieren oder Ihre Inhalte mit dem CMS auslagern.