Skip to main content
urbicon ui

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);
ReturnsSignature
useTranslate() => TypedTranslationFunction<T>
t(key, params?) => string
exists(key) => boolean
getLocales() => Locale[]
registerLocale(locale, bundle) => void
source{ name, base, translations, loaders }
typesCreatePackageTypes<T>

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:

  1. the package namespace in the active locale,
  2. the package namespace in the provider's fallback locale,
  3. the package's own base bundle (en or options.base — complete by construction, so a key the package declares never renders raw),
  4. 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.