Spec — @xpulse/i18n

Status: ACCEPTED · März 2026 Abhängigkeiten: @xpulse/event, @xpulse/config, @xpulse/router Optional: @xpulse/template

Prinzipien

URL ist Source of Truth — /doc/... = Defaultsprache, /en/doc/... = explizit EN
Kein Cookie, kein Server-State — Sprachpräferenz liegt im localStorage (Client)
Kein Build-Step — Locale-JSONs werden zur Laufzeit geladen
Opt-in für andere Packages — wer kein i18n braucht, merkt nichts

Route-Wrapping

@xpulse/i18n wrapped router.register() während seines eigenen Init. Alle nachfolgenden Routen-Registrierungen (doc, controller, ...) werden automatisch um /:lang/-Varianten erweitert — unabhängig von deren Init-Reihenfolge.

1 @xpulse/router:init
2 └── router.register() = originalRegister()
3  
4 @xpulse/i18n:init   (depends: ["xpulse-router"])
5 └── router.register() = wrapper()
6  
7 @xpulse/doc:init
8 └── router.register('GET', '/doc/...', handler)
9     └── wrapper registriert automatisch:
10           GET /doc/...          req.lang = detect(req)
11           GET /de/doc/...       req.lang = 'de'
12           GET /en/doc/...       req.lang = 'en'

FOUC-Redirect-Script

Inline-Script im <head>, via http:response:before in alle HTML-Responses injiziert:

1 (function(){try{
2   var l=localStorage.getItem('xpulse_lang');
3   var s=["en"];  // non-default langs
4   if(l&&s.includes(l)&&!location.pathname.startsWith('/'+l+'/')){
5     location.replace('/'+l+location.pathname+location.search);
6   }
7 }catch(e){}})();

Kein FOUC — der Browser sieht nie die falsche Sprachversion.

SEO

Mit use-seo: true werden automatisch injiziert:

1 <link rel="alternate" hreflang="de" href="https://xpulse.one/tool/chat/" />
2 <link rel="alternate" hreflang="en" href="https://xpulse.one/en/tool/chat/" />
3 <link rel="alternate" hreflang="x-default" href="https://xpulse.one/tool/chat/" />

Paket-Struktur

1 @xpulse/i18n/
2   src/
3     index.js                    ← init, lang, t, router-wrap
4     detect.js                   ← detectLang, stripLang, langFromPath
5     middleware.js               ← langHandler, detectHandler, hookResponses
6     template-methods/
7       lang-switcher.js          ← langSwitcher()
8       html-lang.js              ← htmlLang()
9   xpulse.json
10   package.json

1	@xpulse/router:init
2	└── router.register() = originalRegister()
3
4	@xpulse/i18n:init (depends: ["xpulse-router"])
5	└── router.register() = wrapper()
6
7	@xpulse/doc:init
8	└── router.register('GET', '/doc/...', handler)
9	└── wrapper registriert automatisch:
10	GET /doc/... req.lang = detect(req)
11	GET /de/doc/... req.lang = 'de'
12	GET /en/doc/... req.lang = 'en'

1	(function(){try{
2	var l=localStorage.getItem('xpulse_lang');
3	var s=["en"]; // non-default langs
4	if(l&&s.includes(l)&&!location.pathname.startsWith('/'+l+'/')){
5	location.replace('/'+l+location.pathname+location.search);
6	}
7	}catch(e){}})();

1	<link rel="alternate" hreflang="de" href="https://xpulse.one/tool/chat/" />
2	<link rel="alternate" hreflang="en" href="https://xpulse.one/en/tool/chat/" />
3	<link rel="alternate" hreflang="x-default" href="https://xpulse.one/tool/chat/" />

1	@xpulse/i18n/
2	src/
3	index.js ← init, lang, t, router-wrap
4	detect.js ← detectLang, stripLang, langFromPath
5	middleware.js ← langHandler, detectHandler, hookResponses
6	template-methods/
7	lang-switcher.js ← langSwitcher()
8	html-lang.js ← htmlLang()
9	xpulse.json
10	package.json