Guide — App mehrsprachig machen

1. Paket installieren

1 npm install @xpulse/i18n --registry=https://npm.xpulse.one

2. `xpulse.json` in der App anpassen

Minimale Konfiguration (DE als Default, DE + EN unterstützt):

1 {
2   "i18n": {
3     "supported": ["de", "en"],
4     "default":   "de"
5   }
6 }

Vollständige Optionen:

1 {
2   "i18n": {
3     "supported":  ["de", "en"],
4     "default":    "de",
5     "use-seo":    true,
6     "exclude":    ["/_theme/*", "/_logger/*", "/_debug/*", "/api/*", "/health"],
7     "paths": {
8       "translations": "src/translations/"
9     }
10   }
11 }

3. `@xpulse/app` / Service-Loader konfigurieren

@xpulse/i18n wird automatisch über den Service-Loader geladen, wenn das Package installiert ist. xpulse.json des Packages enthält bereits den passenden Eintrag:

1 {
2   "service": {
3     "xpulse-i18n": { "load": true, "depends": ["xpulse-router"] }
4   }
5 }

Kein manueller init()-Aufruf nötig.

4. Übersetzungsdateien anlegen

Struktur unter src/translations/:

1 src/translations/
2   de/
3     platform.index.json
4     platform.footer.json
5   en/
6     platform.index.json
7     platform.footer.json

Format: Flat Key-Value, Variablen als {key}:

1 {
2   "tagline":    "Private Tools. Kein Server. Keine Kompromisse.",
3   "cta":        "Jetzt starten",
4   "status.days": "noch {n} Tag{s} verfügbar"
5 }

5. Lang-Switcher ins Template einbauen

Im Template <html>-Tag:

1 <html lang="{% htmlLang(_route) %}">

Lang-Switcher an beliebiger Stelle im Layout:

1 {% langSwitcher(_route.path) %}

Das ergibt:

1 <div class="xpulse-lang-switcher">
2   <a href="/tool/chat/"
3      onclick="localStorage.setItem('xpulse_lang','de')"
4      class="xpulse-lang-switcher__option xpulse-lang-switcher__option--active"
5      aria-current="true">DE</a>
6   <a href="/en/tool/chat/"
7      onclick="localStorage.setItem('xpulse_lang','en')"
8      class="xpulse-lang-switcher__option">EN</a>
9 </div>

6. CSS für den Switcher

Die Klassen xpulse-lang-switcher, xpulse-lang-switcher__option und xpulse-lang-switcher__option--active können frei gestylt werden, z.B.:

1 .xpulse-lang-switcher {
2     display: flex;
3     gap: 0.5rem;
4 }
5 .xpulse-lang-switcher__option {
6     opacity: 0.5;
7     text-decoration: none;
8 }
9 .xpulse-lang-switcher__option--active {
10     opacity: 1;
11     font-weight: bold;
12 }

7. Strings im Handler abrufen

1 import i18n from '@xpulse/i18n';
2  
3 // In einem Route-Handler:
4 const lang    = i18n.lang(req);
5 const tagline = i18n.t('tagline', lang);
6 const status  = i18n.t('status.days', lang, { n: 3, s: 'e' });

Was passiert automatisch

Alle registrierten Routen bekommen eine /:lang/-Variante (z.B. /en/tool/chat/)
req.lang ist auf jedem Request gesetzt
Ein Inline-Script im <head> liest localStorage und leitet Besucher auf die richtige Sprachversion um (kein FOUC)
Mit use-seo: true werden <link rel="canonical"> und <link rel="alternate" hreflang> Tags automatisch in den <head> injiziert — app.url in xpulse.json muss für absolute URLs gesetzt sein (von Google für hreflang gefordert)

1	{
2	"i18n": {
3	"supported": ["de", "en"],
4	"default": "de",
5	"use-seo": true,
6	"exclude": ["/_theme/", "/_logger/", "/_debug/", "/api/", "/health"],
7	"paths": {
8	"translations": "src/translations/"
9	}
10	}
11	}

1	{
2	"service": {
3	"xpulse-i18n": { "load": true, "depends": ["xpulse-router"] }
4	}
5	}

1	src/translations/
2	de/
3	platform.index.json
4	platform.footer.json
5	en/
6	platform.index.json
7	platform.footer.json

1	{
2	"tagline": "Private Tools. Kein Server. Keine Kompromisse.",
3	"cta": "Jetzt starten",
4	"status.days": "noch {n} Tag{s} verfügbar"
5	}

1	<div class="xpulse-lang-switcher">
2	<a href="/tool/chat/"
3	onclick="localStorage.setItem('xpulse_lang','de')"
4	class="xpulse-lang-switcher__option xpulse-lang-switcher__option--active"
5	aria-current="true">DE</a>
6	<a href="/en/tool/chat/"
7	onclick="localStorage.setItem('xpulse_lang','en')"
8	class="xpulse-lang-switcher__option">EN</a>
9	</div>

1	.xpulse-lang-switcher {
2	display: flex;
3	gap: 0.5rem;
4	}
5	.xpulse-lang-switcher__option {
6	opacity: 0.5;
7	text-decoration: none;
8	}
9	.xpulse-lang-switcher__option--active {
10	opacity: 1;
11	font-weight: bold;
12	}

1	import i18n from '@xpulse/i18n';
2
3	// In einem Route-Handler:
4	const lang = i18n.lang(req);
5	const tagline = i18n.t('tagline', lang);
6	const status = i18n.t('status.days', lang, { n: 3, s: 'e' });