Spec — @xpulse/i18n

Status: ACCEPTED · March 2026 Dependencies: @xpulse/event, @xpulse/config, @xpulse/router Optional: @xpulse/template

Principles

URL is source of truth — /doc/... = default language, /en/doc/... = explicit EN
No cookie, no server state — language preference is stored in localStorage (client)
No build step — locale JSON files are loaded at runtime
Opt-in for other packages — packages that don't need i18n are unaffected

Route wrapping

@xpulse/i18n wraps router.register() during its own init. All subsequent route registrations (doc, controller, ...) are automatically extended with /:lang/ variants — regardless of their init order.

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 automatically registers:
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 in <head>, injected into all HTML responses via http:response:before:

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){}})();

No FOUC — the browser never sees the wrong language version.

SEO

With use-seo: true, automatically injected into all HTML responses:

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/" />

Package structure

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 automatically registers:
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