Package Integration
Each package registers its own namespaced keys into one shared registry, then exposes a typed hook. Your app can do the same.
Why namespaces
Blocks, table, and auth each ship their own translation keys. Registering them under a
namespace (blocks.*, table.*, auth.*) into one shared registry gives consumers a single merged translation surface with no key collisions — and
lets your own app keys live alongside the library's.
createPackageI18n
The factory registers the bundles at module init and returns a small typed object. Its
signature is createPackageI18n(name, { en, …otherLocales }, options?) — the
base bundle is required (en, unless options.base names another
locale, e.g. createPackageI18n('mach', { de }, { base: 'de' }) for a
German-only product), other eager locales are checked against its structure, and options.loaders opts into code-splitting.
// Inside @urbicon-ui/blocks — src/lib/i18n/index.ts
import { createPackageI18n } from '@urbicon-ui/i18n';
import en from '../translations/en';
// Generic over the `en` bundle: keys + params flow through to the hook's `t`.
// en is the eager base; de is a lazy dynamic-import loader, so English-only
// apps never bundle the de catalog (before it loads, de resolves to en).
export const blocksI18n = createPackageI18n('blocks', { en }, {
loaders: { de: () => import('../translations/de').then((m) => m.default) }
});
// Re-export the context-scoped hook under a package-specific name.
export const useBlocksI18n = blocksI18n.useTranslate;
// Eager-register de once at server start so a German SSR app renders German on
// the first paint instead of the en fallback (see the SSR note).
export const registerBlocksLocale = (locale, bundle) =>
blocksI18n.registerLocale(locale, bundle);| Returns | Signature | Description |
|---|---|---|
| useTranslate | () => TypedTranslationFunction<T> | Context-scoped hook. Call during component init; reads the provider locale reactively. Re-exported as use<Package>I18n. |
| t | (key, params?) => string | Non-hook resolver against the base locale. For module scope / outside a component tree. |
| exists | (key) => boolean | Whether the key exists in the package's base-locale bundle. |
| getLocales | () => Locale[] | Locales this package has registered (data or loader). |
| registerLocale | (locale, bundle) => void | Eagerly + additively register a lazy locale bundle (SSR escape hatch). Call once at server start; throws on an unsupported locale or non-object bundle. |
| source | { name, base, translations, loaders } | What the factory was called with, read-only — what auditPackage audits. |
| types | CreatePackageTypes<T> | Phantom carrier for the inferred key/param types (compile-time only). |
The hook pattern
useTranslate is re-exported as use<Package>I18n and aliased to
a two-letter local in components (bt / tt / dt). It
reads the context locale at call time, so wrapping it in markup or $derived re-renders on a locale switch.
<!-- In a blocks component -->
<script>
import { useBlocksI18n } from '#lib/i18n/index.js';
const bt = useBlocksI18n(); // call during component init; alias to keep call sites short
</script>
<button aria-label={bt('dialog.close')}>×</button>The hook must be called during component initialisation (like every Svelte context read), then
reused — don't call useBlocksI18n() inside an event handler or loop body.
Resolution order
For a package hook, a key resolves in this order:
- the package namespace in the active locale,
- the package namespace in the provider's fallback locale,
- the package's own base bundle (
enoroptions.base— complete by construction, so a key the package declares never renders raw), - the global namespace (shared keys registered without a package).
A key that resolves nowhere returns the key string itself (fail-honest) — so a missing translation is visible, never silently blank.
The <T> component
For declarative one-off translations in markup, <T> wraps useI18n().t. Props: key, optional params, fallback (shown when the key is missing), package (namespace), and options.
<script>
import { T } from '@urbicon-ui/i18n';
</script>
<!-- Declarative translation; re-renders on locale change. -->
<T key="greeting" params={{ name: 'Ada' }} />
<T key="data.loading" package="table" fallback="Loading…" /><T> is convenient but untyped (its key is a plain string). In library
and app components, prefer the typed hook so keys autocomplete and typos fail to compile.
Registering your own package
Your app is just another package. Call createPackageI18n with a unique name and your
own bundles, export the hook, and read it exactly like the library packages — all under the same
provider.
// my-app/src/lib/i18n.ts
import { createPackageI18n } from '@urbicon-ui/i18n';
const en = {
cart: { empty: 'Your cart is empty', items: '{{count}} items' }
} as const;
const de = {
cart: { empty: 'Dein Warenkorb ist leer', items: '{{count}} Artikel' }
} as const;
export const shopI18n = createPackageI18n('shop', { en, de });
export const useShopI18n = shopI18n.useTranslate;Pick a namespace that won't collide with blocks / table / auth. The docs site you're reading does exactly this under the app namespace.
Parity validation (CI)
auditPackage (from @urbicon-ui/i18n/audit) loads a package's lazy
locales and runs the translation audit over every bundle against the
package's base — en, or options.base. Assert it in a vitest test to
fail CI on drift. It complements the compile-time parity the generic factory enforces for
eager bundles, and covers the lazy ones (see Type Safety).
// my-app/src/lib/i18n.test.ts
import { auditPackage } from '@urbicon-ui/i18n/audit';
import { shopI18n } from '#lib/i18n.js';
it('translations pass the audit', async () => {
const report = await auditPackage(shopI18n); // loads lazy locales, diffs against the base
expect(report.findings).toEqual([]); // a missing nested key is an error, an extra one a warning
});It reads the base from the package's source, so it takes no baseLocale.