API Reference

`i18n.init()`

Called automatically by the service loader. No manual call needed.

Wraps router.register() — all subsequent route registrations get /:lang/ variants
Loads translation files from i18n.paths.translations
Registers the http:response:before listener (FOUC script, optional SEO tags)
Emits i18n:init → i18n:ready

`i18n.lang(req)`

Returns the active language for a request. Always set.

1 import i18n from '@xpulse/i18n';
2  
3 const lang = i18n.lang(req);  // → 'de' | 'en'

Priority:

req.lang — set by route middleware (URL prefix /en/...)
Accept-Language header — first supported language
i18n.default from xpulse.json

`i18n.t(key, lang, vars?)`

Returns the translated string.

1 i18n.t('tagline', 'en')
2 // → 'Private Tools. No Server. No Compromises.'
3  
4 i18n.t('status.days', 'en', { n: 3, s: 's' })
5 // → '3 days remaining'
6  
7 i18n.t('unknown.key', 'en')
8 // → 'unknown.key'  (key fallback)

Fallback order:

Entry in the requested language
Entry in the default language (i18n.default)
The key itself as a string

Interpolation: Variables in translation strings are written as {key} and filled via vars:

1 { "status.days": "{n} day{s} remaining" }

1 i18n.t('status.days', 'en', { n: 3, s: 's' })  // → '3 days remaining'
2 i18n.t('status.days', 'en', { n: 1, s: '' })    // → '1 day remaining'

Typical usage in a route handler:

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

Template methods

Available when @xpulse/template is installed.

`{% langSwitcher(path) %}`

Renders a language switcher with links to the /:lang/ variant of the current page. Sets localStorage.xpulse_lang on click.

1 {% langSwitcher(_route.path) %}

Parameter: current path as string — _route.path is available in every template.

`{% htmlLang(route) %}`

Returns the active language code — for <html lang="...">.

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

Parameter: _route object or path string.

`{% t(key, route, vars?) %}`

Returns the translated string — usable directly in templates.

1 {% t('tagline', _route) %}
2 {% t('status.days', _route, {n: 3, s: 's'}) %}
3 {% t('cta', 'en') %}

The second parameter accepts:

_route or path string — language is derived from the path
explicit language code 'de' / 'en'

If the key is not found → key string as fallback (no empty output).

Events

Event	When
`i18n:init`	Init starts, `router.register()` is wrapped
`i18n:ready`	Translation files loaded, ready

xpulse.json options

Key	Default	Description
`i18n.supported`	`["de", "en"]`	Supported languages
`i18n.default`	`"de"`	Default language (no URL prefix route)
`i18n.use-seo`	`false`	Inject `<link rel="canonical">` + `<link rel="alternate" hreflang>` into `<head>`
`i18n.exclude`	`["/_theme/*", ...]`	Paths that don't get a `/:lang/` variant
`i18n.paths.translations`	`"src/translations/"`	Path to locale files
`app.url`	`""`	Base URL for absolute SEO links, e.g. `"https://xpulse.one"` — empty string produces relative paths (invalid for Google hreflang)

1	import i18n from '@xpulse/i18n';
2
3	const lang = i18n.lang(req); // → 'de' \| 'en'

1	i18n.t('tagline', 'en')
2	// → 'Private Tools. No Server. No Compromises.'
3
4	i18n.t('status.days', 'en', { n: 3, s: 's' })
5	// → '3 days remaining'
6
7	i18n.t('unknown.key', 'en')
8	// → 'unknown.key' (key fallback)

1	i18n.t('status.days', 'en', { n: 3, s: 's' }) // → '3 days remaining'
2	i18n.t('status.days', 'en', { n: 1, s: '' }) // → '1 day remaining'

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

1	{% t('tagline', _route) %}
2	{% t('status.days', _route, {n: 3, s: 's'}) %}
3	{% t('cta', 'en') %}