Skip to content

5. Internationalisierung

Eine internationalisierte Anwendung zeigt ihre Texte in der Sprache des Benutzers an. Die Fallstudie ist auf Französisch und Englisch verfügbar. Das Prinzip ist einfach: Die Views enthalten keinen Text mehr, sondern Schlüssel ([MENU.HOME]), und ein Wörterbuch für jede Sprache ordnet jedem Schlüssel einen Text zu. Die gewählte Sprache wird in einem Cookie gespeichert.

5.1. Beispiel 22: Eine zweisprachige Anwendung

22-i18n/
├── i18n/
│   ├── en.json
│   └── fr.json
├── src/
│   ├── app.module.ts
│   ├── helpers.ts
│   ├── i18n.ts
│   ├── language.controller.ts
│   ├── main.ts
│   └── pages.controller.ts
├── views/
│   ├── partials/
│   │   └── navbar.hbs
│   ├── home.hbs
│   ├── layout.hbs
│   └── products.hbs
├── nest-cli.json
└── tsconfig.json

5.1.1. Die Wörterbücher

Die Datei [i18n/fr.json]:

{
  "MENU": {
    "HOME": "Accueil",
    "PRODUCTS": "Produits"
  },
  "HOME": {
    "TITLE": "Bienvenue",
    "HELLO": "Bonjour {name} !",
    "DATE": "Nous sommes le {date}."
  },
  "PRODUCTS": {
    "TITLE": "Nos produits",
    "NAME": "Produit",
    "PRICE": "Prix",
    "COUNT": "{n} produit(s) au catalogue."
  }
}

Die Datei [i18n/en.json]:

{
  "MENU": {
    "HOME": "Home",
    "PRODUCTS": "Products"
  },
  "HOME": {
    "TITLE": "Welcome",
    "HELLO": "Hello {name}!",
    "DATE": "Today is {date}."
  },
  "PRODUCTS": {
    "TITLE": "Our products",
    "NAME": "Product",
    "PRICE": "Price",
    "COUNT": "{n} product(s) in the catalogue."
  }
}
  • Ein Wörterbuch ist eine JSON-Datei, die nach Seiten oder Themen gegliedert ist: Der Schlüssel [HOME.HELLO] verweist auf den Text [HELLO] im Abschnitt [HOME];
  • Zeile 8: Ein Text kann Parameter enthalten, die in geschweifte Klammern gesetzt sind und bei der Übersetzung ersetzt werden. Die Wortstellung unterscheidet sich von Sprache zu Sprache: Deshalb wird ein Text nicht einfach durch Aneinanderhängen übersetzter Teilstücke erzeugt.

5.1.2. Das Übersetzungsmodul

Die Datei [src/i18n.ts]:

import { readFileSync } from 'fs';
import { join } from 'path';

export type Language = 'fr' | 'en';
export const LANGUAGES: Language[] = ['fr', 'en'];
export const DEFAULT_LANGUAGE: Language = 'en';
// die von Intl für Datums- und Zahlenangaben verwendete "locale"
export const LOCALES: Record<Language, string> = { fr: 'fr-FR', en: 'en-US' };

// ein Wörterbuch ist ein verschachteltes JSON-Objekt: { "MENU": { "HOME": "Home" } }
type Dictionary = { [key: string]: string | Dictionary };

// die Wörterbücher werden nur EINMAL beim Start gelesen
const FOLDER = join(__dirname, '..', 'i18n');
const dictionaries: Record<Language, Dictionary> = {
  fr: JSON.parse(readFileSync(join(FOLDER, 'fr.json'), 'utf-8')),
  en: JSON.parse(readFileSync(join(FOLDER, 'en.json'), 'utf-8')),
};

export function isLanguage(value: unknown): value is Language {
  return typeof value === 'string' && (LANGUAGES as string[]).includes(value);
}

// translate('en', 'HOME.HELLO', { name: 'Marie' }) -> "Hello Marie!"
export function translate(language: Language, key: string, params: Record<string, unknown> = {}): string {
  const text = lookup(dictionaries[language], key) ?? key;
  return text.replace(/\{(\w+)\}/g, (whole, name: string) => (name in params ? String(params[name]) : whole));
}

// 'HOME.HELLO': wir steigen in HOME hinab, dann in HELLO
function lookup(dictionary: Dictionary, key: string): string | null {
  let node: string | Dictionary | undefined = dictionary;
  for (const part of key.split('.')) {
    if (typeof node !== 'object') {
      return null;
    }
    node = node[part];
  }
  return typeof node === 'string' ? node : null;
}

Kommentieren wir diesen Code:

  • Zeilen 4–6: die unterstützten Sprachen;
  • Zeile 8: das „Locale“ jeder Sprache, das von [Intl] zur Formatierung von Datumsangaben und Zahlen verwendet wird ([fr-FR]: 23/09/2026, 12,50 €; [en-US]: 9/23/2026, €12.50);
  • Zeilen 14–18: Die Wörterbücher werden einmal beim Laden des Moduls gelesen und anschließend im Speicher gehalten;
  • Zeilen 20–22: eine Typprüfung wie in [TypeScript] ([value is Language]): Nach einem positiven Test weiß der Compiler, dass der Wert eine [Language] ist;
  • Zeilen 25–28: die Übersetzung. Der Schlüssel wird im Wörterbuch nachgeschlagen; wird er nicht gefunden, wird der Schlüssel selbst angezeigt: Jedes Versäumnis ist sofort auf dem Bildschirm sichtbar. Der reguläre Ausdruck [/\{(\w+)\}/g] findet jeden Parameter [{name}] und ersetzt ihn durch seinen Wert;
  • Zeilen 31–40: Der Schlüssel [HOME.HELLO] wird in [HOME] und dann in [HELLO] zerlegt, und der Vorgang setzt sich im JSON-Objekt nach unten fort.

5.1.3. Die Helfer

Die Datei [src/helpers.ts]:

import { HelperOptions } from 'handlebars';
import { Language, DEFAULT_LANGUAGE, LOCALES, isLanguage, translate } from './i18n';

interface Hbs {
  registerHelper(name: string, fn: (...args: any[]) => unknown): void;
}

// die Sprache der Seite: res.locals.lang, in das Wurzelmodell eingemischt
function languageOf(options: HelperOptions): Language {
  const lang = options.data?.root?.lang;
  return isLanguage(lang) ? lang : DEFAULT_LANGUAGE;
}

export function registerHelpers(hbs: Hbs): void {
  // {{t 'KEY'}} oder {{t 'KEY' name=...}}: Übersetzung, mit benannten Parametern
  hbs.registerHelper('t', (key: string, options: HelperOptions) => translate(languageOf(options), key, options.hash));

  // {{longDate when}}: "mercredi 23 septembre 2026" / "Wednesday, September 23, 2026"
  hbs.registerHelper('longDate', (when: string, options: HelperOptions) =>
    new Intl.DateTimeFormat(LOCALES[languageOf(options)], { dateStyle: 'full' }).format(new Date(when)),
  );

  // {{money price}}: "12,50 €" / "€12.50"
  hbs.registerHelper('money', (amount: number, options: HelperOptions) =>
    new Intl.NumberFormat(LOCALES[languageOf(options)], { style: 'currency', currency: 'EUR' }).format(amount),
  );

  hbs.registerHelper('eq', (a: unknown, b: unknown) => a === b);
}
  • Zeilen 9–12: Die Sprache der Seite befindet sich im Root-Template ([options.data.root.lang]), wo die [main.ts]-Middleware sie über [res.locals] abgelegt hat;
  • Zeile 16: Der Helfer [t] übersetzt einen Schlüssel. Die benannten Parameter des Helfers ([options.hash]) sind die Parameter des Textes: [{{t 'HOME.HELLO' name=name}}];
  • Zeilen 19–21 und 24–26: Datumsangaben und Beträge werden sprachabhängig formatiert.

5.1.4. Sprachauswahl

Die Datei [src/main.ts]:

import { NestFactory } from '@nestjs/core';
import { NestExpressApplication } from '@nestjs/platform-express';
import * as cookieParser from 'cookie-parser';
import { NextFunction, Request, Response } from 'express';
import * as hbs from 'hbs';
import { dirname, join } from 'path';
import { AppModule } from './app.module';
import { registerHelpers } from './helpers';
import { isLanguage, DEFAULT_LANGUAGE } from './i18n';

const ROOT = join(__dirname, '..');

async function bootstrap() {
  const app = await NestFactory.create<NestExpressApplication>(AppModule);
  app.useStaticAssets(join(dirname(require.resolve('bootstrap/package.json')), 'dist'), { prefix: '/bootstrap/' });
  app.setBaseViewsDir(join(ROOT, 'views'));
  app.setViewEngine('hbs');
  registerHelpers(hbs);
  await new Promise<void>((done) => hbs.registerPartials(join(ROOT, 'views', 'partials'), () => done()));
  app.use(cookieParser());
  // die Sprache jeder Seite: die des Cookies [language], andernfalls Englisch
  app.use((req: Request, res: Response, next: NextFunction) => {
    const cookie = req.cookies?.language;
    res.locals.lang = isLanguage(cookie) ? cookie : DEFAULT_LANGUAGE;
    next();
  });
  await app.listen(3000);
  console.log('Server started on http://localhost:3000');
}

bootstrap();

Zeilen 22–26: Bei jeder Anfrage wird die Sprache aus dem [language]-Cookie gelesen (standardmäßig Englisch) und in [res.locals.lang] abgelegt und damit im Template jeder View bereitgestellt.

Die Datei [src/language.controller.ts]:

import { Controller, Get, NotFoundException, Param, Req, Res } from '@nestjs/common';
import { Request, Response } from 'express';
import { isLanguage } from './i18n';

@Controller('language')
export class LanguageController {
  // GET /language/fr: speichert die Auswahl in einem Cookie und kehrt dann zur vorherigen Seite zurück
  @Get(':language')
  change(@Param('language') language: string, @Req() req: Request, @Res() res: Response): void {
    if (!isLanguage(language)) {
      throw new NotFoundException();
    }
    res.cookie('language', language, { maxAge: 365 * 24 * 3600 * 1000, sameSite: 'lax', httpOnly: true });
    res.redirect(originPage(req));
  }
}

// die Seite, von der wir kommen (Header Referer), von der wir nur den Pfad behalten:
// eine Weiterleitung auf eine vollständige, der Anfrage entnommene Adresse würde es ermöglichen,
// den Benutzer auf eine andere Website zu schicken (Schwachstelle "open redirect")
function originPage(req: Request): string {
  const referer = req.get('referer');
  if (!referer) {
    return '/';
  }
  try {
    const url = new URL(referer);
    return url.pathname + url.search;
  } catch {
    return '/';
  }
}
  • Zeilen 8–15: [GET /language/en] speichert die Auswahl in einem Cookie, das ein Jahr gültig ist, und leitet dann auf die Seite um, von der der Benutzer kam. Eine unbekannte Sprache führt zu einem 404-Fehler;
  • Zeilen 21–32: Die ursprüngliche Seite wird durch den Header [Referer] angegeben, den der Browser beim Klick auf einen Link hinzufügt. Wir behalten nur den Pfad: Eine Umleitung auf eine vollständige URL aus der Anfrage würde es einer bösartigen Website erlauben, einen Link zu erstellen, der den Benutzer nach dem Durchlaufen unserer Website auf die bösartige Website weiterleitet (eine Schwachstelle, bekannt als [open redirect]).

5.1.5. Die Views

Die Datei [views/layout.hbs]:

<!doctype html>
<html lang="{{lang}}">
<head>
  <meta charset="utf-8">
  <title>{{t pageTitle}}</title>
  <link rel="stylesheet" href="/bootstrap/css/bootstrap.min.css">
</head>
<body>
  <div class="container py-3">
    {{> navbar}}
    {{{body}}}
  </div>
</body>
</html>
  • Zeile 2: Das Attribut [lang] der Seite spiegelt die gewählte Sprache wider (nützlich für Screenreader und Rechtschreibprüfungen);
  • Zeile 5: Der Seitentitel ist ein Schlüssel, den die Action liefert ([pageTitle]) und den die View übersetzt: [{{t pageTitle}}]. Ohne Apostrophe ist das Argument des Helfers eine Template-Variable und keine literale Zeichenkette.

Die Datei [views/partials/navbar.hbs]:

<nav class="navbar navbar-expand bg-light rounded mb-3 px-3">
  <div class="navbar-nav me-auto">
    <a class="nav-link" href="/">{{t 'MENU.HOME'}}</a>
    <a class="nav-link" href="/products">{{t 'MENU.PRODUCTS'}}</a>
  </div>
  {{!-- die aktuelle Sprache wird hervorgehoben --}}
  <div class="btn-group btn-group-sm">
    <a class="btn {{#if (eq lang 'fr')}}btn-primary{{else}}btn-outline-primary{{/if}}" href="/language/fr">FR</a>
    <a class="btn {{#if (eq lang 'en')}}btn-primary{{else}}btn-outline-primary{{/if}}" href="/language/en">EN</a>
  </div>
</nav>

Zeilen 8–9: zwei Links (der Sprachwechsel ändert keine Anwendungsdaten: Ein GET ist dafür angemessen), wobei die aktuelle Sprache hervorgehoben ist.

Die Datei [views/home.hbs]:

1
2
3
<h1>{{t 'HOME.TITLE'}}</h1>
<p>{{t 'HOME.HELLO' name=name}}</p>
<p>{{t 'HOME.DATE' date=(longDate today)}}</p>

Zeile 3: ein Teilausdruck: Das Datum wird zunächst von [longDate] formatiert und dann als Parameter [date] an den Helfer [t] übergeben.

Die Datei [views/products.hbs]:

<h1>{{t 'PRODUCTS.TITLE'}}</h1>
<table class="table table-sm w-auto">
  <thead><tr><th>{{t 'PRODUCTS.NAME'}}</th><th class="text-end">{{t 'PRODUCTS.PRICE'}}</th></tr></thead>
  <tbody>
    {{#each products}}
      {{!-- innerhalb der Schleife findet der Helper die Sprache im ROOT-Modell --}}
      <tr><td>{{name}}</td><td class="text-end">{{money price}}</td></tr>
    {{/each}}
  </tbody>
</table>
<p>{{t 'PRODUCTS.COUNT' n=count}}</p>

Die Datei [src/pages.controller.ts]:

import { Controller, Get, Render } from '@nestjs/common';

@Controller()
export class PagesController {
  @Get()
  @Render('home')
  home(): object {
    // pageTitle ist ein SCHLÜSSEL: die View übersetzt ihn
    return { pageTitle: 'HOME.TITLE', name: 'Marie', today: '2026-09-23' };
  }

  @Get('products')
  @Render('products')
  products(): object {
    const products = [
      { name: 'Keyboard', price: 25 },
      { name: 'Mouse', price: 12.5 },
      { name: 'Screen', price: 1149 },
    ];
    return { pageTitle: 'PRODUCTS.TITLE', products, count: products.length };
  }
}

5.1.6. Ausführung

Auf Französisch (nach einem Klick auf FR; ohne Cookie erscheint die Seite auf Englisch, der Standardsprache):

Image

Image

Klick auf EN:

curl -i -H "Referer: http://localhost:3000/products" http://localhost:3000/language/en
1
2
3
4
5
6
7
HTTP/1.1 302 Found
Set-Cookie: language=en; Max-Age=31536000; Path=/; Expires=Thu, 23 Sep 2027 14:16:03 GMT; HttpOnly; SameSite=Lax
Location: /products
Content-Type: text/plain; charset=utf-8
Content-Length: 31

Found. Redirecting to /products

Der Server setzt das Cookie und leitet auf die ursprüngliche Seite um, die nun auf Englisch angezeigt wird:

Image

Image

Die Fallstudie funktioniert genau so, mit umfangreicheren Wörterbüchern ([i18n/fr.json] und [i18n/en.json]): derselbe Helfer [t], derselbe Controller [/language/:language], dasselbe Cookie. Es gibt nur einen Unterschied: Die von der Geschäfts- und der Web-Schicht erzeugten Fehlermeldungen sind ebenfalls Schlüssel, die erst im letzten Moment von der View übersetzt werden.