Lokalisierung ohne Bibliothek
Übersetze eine Vue-3-App mit einem kleinen Composable statt einer Bibliothek: typisierte Schlüssel, Platzhalter, Pluralformen über Intl.PluralRules, Zahlen im Format der Leser und eine Sprache, die alle Komponenten teilen.
Auf dieser Seite
Quest-Ziele
- Übersetzungen in typisierten Dateien halten, damit ein fehlender Schlüssel ein Compilerfehler ist
- Die aktuelle Sprache zwischen allen Komponenten teilen
- Platzhalter füllen und Zahlen passend zur Sprache formatieren
- Pluralformen mit Intl.PluralRules wählen
- Die Sprache merken und mit der des Browsers beginnen
Bibliotheken wie vue-i18n können viel, und für viele Apps ist das mehr, als sie brauchen. Eine kleine App mit zwei oder drei Sprachen kommt mit einem Composable von etwa hundert Zeilen aus, und die Intl-API des Browsers erledigt die schweren Teile: Pluralregeln und Zahlenformate für jede Sprache.
Das Composable, das hier entsteht, kann, was die meisten Apps brauchen: typisierte Schlüssel, Platzhalter, Pluralformen, Zahlen im richtigen Format und eine Sprache, die gespeichert wird und in jeder Komponente dieselbe ist.
Die Übersetzungen
Jede Sprache ist eine TypeScript-Datei mit einem verschachtelten Objekt. Englisch kommt zuerst, und seine Form wird zum Typ, dem jede andere Sprache entsprechen muss:
export const en = {
app: {
welcome: 'Welcome, {name}!',
language: 'Language',
},
cart: {
// A plural: none for 0, the rest as Intl.PluralRules names them
items: {
none: 'Your cart is empty',
one: 'One item in your cart',
other: '{count} items in your cart',
},
add: 'Add an item',
},
};
// Every language has to have exactly these keys
export type Messages = typeof en;import type { Messages } from './en';
export const de: Messages = {
app: {
welcome: 'Willkommen, {name}!',
language: 'Sprache',
},
cart: {
items: {
none: 'Dein Warenkorb ist leer',
one: 'Ein Artikel im Warenkorb',
other: '{count} Artikel im Warenkorb',
},
add: 'Artikel hinzufügen',
},
};Weil de als Messages deklariert ist, ist ein Schlüssel, der im Deutschen fehlt oder zu viel ist, ein Compilerfehler. Eine Übersetzung kann nicht vergessen werden.
Platzhalter in geschweiften Klammern, etwa
{name}, werden beim Verwenden des Texts gefüllt.Eine Pluralform ist statt eines Strings ein Objekt mit Formen.
noneist ein optionaler eigener Satz für null. Die anderen Formen heißen so, wieIntl.PluralRulessie nennt: Englisch und Deutsch brauchenoneundother, Polnisch auchfewundmany, Arabisch alle sechs.
Das Composable
import { readonly, ref, watchEffect } from 'vue';
import { de } from '../i18n/de';
import { en, type Messages } from '../i18n/en';
const messages = { en, de };
export type Locale = keyof typeof messages;
export const locales: Record<Locale, string> = {
en: 'English',
de: 'Deutsch',
};
const fallback: Locale = 'en';
// A plural: other is required, none and the forms of Intl.PluralRules are optional
type Plural = { other: string; none?: string } & Partial<Record<Intl.LDMLPluralRule, string>>;
// Every key that leads to a message, in dot notation, such as 'app.welcome'
type MessageKey<T = Messages> = {
[K in keyof T & string]: T[K] extends string | Plural ? K : `${K}.${MessageKey<T[K]>}`;
}[keyof T & string];
type Params = Record<string, string | number>;
// The current language. Outside the function, so every component shares it.
const locale = ref<Locale>(initialLocale());
// Keeps <html lang> in step, for screen readers and search engines
watchEffect(() => {
document.documentElement.lang = locale.value;
});
function initialLocale(): Locale {
const saved = localStorage.getItem('locale');
if (isLocale(saved)) {
return saved;
}
// The first of the browser's languages that we have
for (const language of navigator.languages) {
const code = language.split('-')[0];
if (isLocale(code)) {
return code;
}
}
return fallback;
}
function isLocale(value: string | null | undefined): value is Locale {
return value != null && Object.keys(messages).includes(value);
}
function setLocale(next: Locale) {
locale.value = next;
localStorage.setItem('locale', next);
}
function lookup(source: Messages, key: string): string | Plural | undefined {
let node: unknown = source;
for (const part of key.split('.')) {
if (typeof node !== 'object' || node === null) {
return undefined;
}
node = (node as Record<string, unknown>)[part];
}
return node as string | Plural | undefined;
}
// One Intl.PluralRules per language, made when it is first needed
const pluralRules = new Map<Locale, Intl.PluralRules>();
function pluralForm(forms: Plural, count: number): string {
if (count === 0 && forms.none !== undefined) {
return forms.none;
}
let rules = pluralRules.get(locale.value);
if (!rules) {
rules = new Intl.PluralRules(locale.value);
pluralRules.set(locale.value, rules);
}
return forms[rules.select(count)] ?? forms.other;
}
function t(key: MessageKey, params: Params = {}): string {
const message = lookup(messages[locale.value], key) ?? lookup(messages[fallback], key);
if (message === undefined) {
console.warn(`Missing translation: ${key}`);
return key;
}
const text = typeof message === 'string' ? message : pluralForm(message, Number(params.count ?? 0));
// Fills in {name} and the like. Numbers are formatted for the language: 1,000 or 1.000.
return text.replace(/\{(\w+)\}/g, (placeholder, name: string) => {
const value = params[name];
if (value === undefined) {
return placeholder;
}
return typeof value === 'number' ? value.toLocaleString(locale.value) : value;
});
}
export function useLocalization() {
return { locale: readonly(locale), locales, setLocale, t };
}Von oben nach unten:
MessageKeybaut aus dem Typ der englischen Datei jeden gültigen Schlüssel:'app.welcome' | 'app.language' | 'cart.items' | 'cart.add'. Es läuft durch das Objekt und hält bei Strings und Pluralformen an, also ist aucht('cart'), eine Gruppe statt eines Texts, ein Fehler. Dein Editor vervollständigt die Schlüssel beim Tippen.localesteht außerhalb vonuseLocalization. Damit ist es ein Wert für die ganze App: Wechselst du die Sprache in einer Komponente, folgen alle anderen. Innerhalb der Funktion bekäme jede Komponente ihre eigene Sprache. Das Composable gibt es alsreadonlyheraus, damit es sich nur übersetLocaleändert, das es auch speichert.Die erste Sprache ist die zuletzt gespeicherte, sonst die erste der bevorzugten Sprachen des Browsers, die die App hat, sonst Englisch.
de-ATzählt alsde.watchEffecthält das Attributlangder Seite aktuell, mit dem Screenreader eine Stimme wählen und Suchmaschinen die Sprache erkennen.tsucht den Schlüssel in der aktuellen Sprache, fällt auf Englisch zurück und dann, mit einer Warnung, auf den Schlüssel selbst, damit eine Lücke nie als leere Stelle erscheint. Bei einer Pluralform wähltIntl.PluralRulesdie Form fürcount. Zahlen in Platzhaltern werden passend zur Sprache formatiert: 1,000 auf Englisch, 1.000 auf Deutsch.
So verwendest du es
Ein Sprachumschalter. v-model braucht einen Wert, in den es schreiben kann, also gibt ein beschreibbares computed Änderungen an setLocale weiter:
<script setup lang="ts">
import { computed } from 'vue';
import { useLocalization } from '../composables/useLocalization';
const { locale, locales, setLocale, t } = useLocalization();
// v-model needs something it can write to
const current = computed({
get: () => locale.value,
set: setLocale,
});
</script>
<template>
<label>
{{ t('app.language') }}
<select v-model="current">
<option v-for="(name, code) in locales" :key="code" :value="code">{{ name }}</option>
</select>
</label>
</template>Und eine Komponente, die Übersetzungen nutzt:
<script setup lang="ts">
import { ref } from 'vue';
import { useLocalization } from '../composables/useLocalization';
const { t } = useLocalization();
const count = ref(0);
</script>
<template>
<h1>{{ t('app.welcome', { name: 'Ada' }) }}</h1>
<p>{{ t('cart.items', { count }) }}</p>
<button @click="count++">{{ t('cart.add') }}</button>
</template>Klick ein paarmal auf den Button: Der Text geht von „Dein Warenkorb ist leer“ über „Ein Artikel im Warenkorb“ zu „2 Artikel im Warenkorb“. Wechsle in der anderen Komponente auf Englisch, und diese folgt sofort, weil t beim Rendern des Templates das gemeinsame locale liest. Nach dem Neuladen beginnt die Seite in der Sprache, die du gewählt hast.
Wann eine Bibliothek besser ist
Dieses Composable hat alle Sprachen im Bundle und teilt seinen Zustand über das Modul. Für ein paar Sprachen in einer Single-Page-App ist das in Ordnung. Bei vielen Sprachen lädst du jede erst mit import(), wenn sie gewählt wird. Mit Server-Side Rendering würden sich alle Besucher des Servers den Zustand des Moduls teilen, und localStorage und document gibt es dort nicht: Ab da lohnt sich vue-i18n oder das i18n-Modul von Nuxt. Datumswerte funktionieren wie Zahlen, über Intl.DateTimeFormat.
Die Dateien dieses Tutorials:
src/
├── components/
│ ├── CartSummary.vue
│ └── LanguageSwitcher.vue
├── composables/
│ └── useLocalization.ts
└── i18n/
├── de.ts
└── en.tsKommentare
Die Kommentare sind GitHub Discussions: Zum Schreiben mit GitHub anmelden.
Die Kommentare kommen über giscus von GitHub. Beim Laden gehen deine IP-Adresse an giscus.app und GitHub.