Typesafe-i18n: Typsichere Internationalisierung in TypeScript

In der modernen Webentwicklung ist Internationalisierung (i18n) weit mehr als nur Textübersetzung – es ist ein ganzes System zur Verwaltung von Lokalisierung. Typesafe-i18n ist eine Bibliothek für TypeScript, die Internationalisierung auf ein neues Niveau hebt, indem sie vollständige Typsicherheit in allen Phasen gewährleistet: vom Schreiben der Übersetzungen bis zur Verwendung im Code.

Warum ist diese Bibliothek notwendig? Traditionelle i18n-Lösungen (z. B. i18next) arbeiten oft mit dynamischen Strings, was zu Fehlern führt: Tippfehler in Schlüsseln, falsche Argumente oder fehlende Übersetzungen. Typesafe-i18n löst dieses Problem radikal: Wenn Sie LL.WELCOME({name: "Max"}) schreiben, prüft TypeScript, ob der Schlüssel WELCOME existiert, ob er den Parameter name akzeptiert und von welchem Typ dieser Parameter ist. Lokalisierungsfehler werden zu Kompilierungsfehlern, nicht zu Runtime-Bugs.

Die Bibliothek eignet sich ideal für Projekte, bei denen strenge Typisierung wichtig ist: React/Vue/Angular-Anwendungen, Node.js-Server, Komponentenbibliotheken. Sie unterstützt Pluralformen, Interpolation, verschachtelte Schlüssel, asynchrones Laden und die Generierung von Typen basierend auf Ihren Übersetzungsdateien. In diesem Artikel behandeln wir alle Aspekte der Arbeit mit Typesafe-i18n: von der Installation bis zu fortgeschrittenen Techniken.

Installation

Die Installation erfolgt über npm (oder yarn/pnpm):

npm install typesafe-i18n

Für die Generierung von Typen und Übersetzungsdateien wird ein zusätzliches Paket benötigt:

npm install --save-dev typesafe-i18n-cli

Nach der Installation initialisieren Sie das Projekt:

npx typesafe-i18n --init

Dieser Befehl erstellt die grundlegende Ordnerstruktur und Konfigurationsdateien.

Schnellstart: Minimales funktionierendes Beispiel

Erstellen wir eine einfache Anwendung, die den Benutzer in verschiedenen Sprachen begrüßt.

Schritt 1: Erstellen Sie eine Übersetzungsdatei

Erstellen Sie die Datei src/i18n/de/index.ts:

import type { Translation } from '../i18n-types'

const de: Translation = {
   HI: 'Hallo {name}!',
   GOODBYE: 'Tschüss, {name}!'
}

export default de

Schritt 2: Erstellen Sie eine Übersetzungsdatei für Englisch

Erstellen Sie die Datei src/i18n/en/index.ts:

import type { Translation } from '../i18n-types'

const en: Translation = {
   HI: 'Hello {name}!',
   GOODBYE: 'Goodbye, {name}!'
}

export default en

Schritt 3: Starten Sie die Typgenerierung

npx typesafe-i18n

Schritt 4: Verwenden Sie es im Code

import { i18n } from './i18n/i18n-util'
import { loadLocale } from './i18n/i18n-util.sync'
import { L } from './i18n/i18n-util'

// Locales laden
loadLocale('de')
loadLocale('en')

// Instanz für Deutsch erstellen
const LL_de = i18n('de')
console.log(LL_de.HI({ name: 'Max' })) // Ausgabe: Hallo Max!

// Auf Englisch umschalten
const LL_en = i18n('en')
console.log(LL_en.HI({ name: 'Max' })) // Ausgabe: Hello Max!

Beachten Sie: Wenn Sie versuchen, LL_de.HI() ohne das Argument name aufzurufen, gibt TypeScript einen Kompilierungsfehler aus. Wenn Sie sich im Schlüssel vertippen (LL_de.Hello) – ebenfalls ein Fehler.

Wichtige Methoden und Funktionen

Betrachten wir 8 Schlüsselfunktionen und Methoden der Bibliothek Typesafe-i18n.

1. i18n(locale: Locales): TranslationFunctions

Signatur: i18n(locale: Locales): TranslationFunctions

Funktion: Erstellt eine Übersetzerinstanz für das angegebene Gebietsschema. Gibt ein Objekt mit allen Übersetzungsfunktionen zurück.

import { i18n } from './i18n/i18n-util'

const LL = i18n('de')
console.log(LL.HI({ name: 'Anna' })) // Hallo Anna!