# Runtime API

Source: https://verbaly.dev/docs/reference/api

The `verbaly` core is ~3 KB gzipped with zero dependencies, and everything builds on native `Intl`.

## createVerbaly(options)

```
import { createVerbaly } from 'verbaly';

const v = createVerbaly({
  locale: 'es',
  fallback: ['en'],
  messages: { es: { home: { title: 'Inicio' } } },
});
```

| Option | Type | Description |
| --- | --- | --- |
| locale | string | Initial language; defaults to `navigator.language` in the browser |
| fallback | string \| string[] | Fallback chain, after the closest match (`es-MX` → `es`) |
| messages | object | Language → tree; nested keys flatten to dots (`home.title`). An empty string counts as untranslated and keeps falling back, the same rule as `check` |
| loaders | object | Lazy catalogs: language → `() => import('./es.json')`, loaded on demand. The one for your starting `locale` is fetched right away, and the UI updates when it lands |
| formatters | object | Custom `{v:name}` formatters |
| icu | function | The ICU parser, for messages that arrive after the build: pass `parseIcu` from `verbaly`. With the plugin, `icu: true` in your config does this |
| partial | string[] | Languages whose messages came with the page: nothing is fetched for them, and a message the page never showed loads the rest once instead of falling back in silence |
| onMissing | function | `(key, locale)`: return a string to substitute; silences the default warn-once |
| onResolve | function | `(info)` on every `t()`: `key`, `locale`, `value` and `status` (hit / fallback / miss). Powers devtools |

## Instance

| Member | Description |
| --- | --- |
| t(key, params?) | Translate. Keys and params are type-checked from your messages. Bad data never crashes a render, and never slips through unnoticed: a missing param, a plural block with no catch-all case, a placeholder with no argument, a value that is not text, a language code the browser cannot read. Each one warns once in the console, naming the message, the path or the code it came from |
| t`...` | Tagged template: interpolates source text; the compiler upgrades it |
| t.id(key)`...` | Readable-key opt-in: formats the inline source; the compiler rewrites it to a keyed call |
| setLocale(locale) | Switch language, notify subscribers, auto-loads a pending lazy catalog. It returns at once: `setLocale` from `verbaly/app` is the one that waits for the catalog |
| loadLocale(locale) | Load a lazy catalog, once, with the closest match: `await` it before `setLocale` for a flash-free switch |
| addMessages(locale, tree, options?) | Merge messages at runtime: what lazy loading is built on. Pass `{ partial: true }` when the messages are one page's worth, so the language stays incomplete and the next missing message still fetches the rest |
| subscribe(fn) | Change listener; returns unsubscribe |
| has(key) | Key exists in the current chain |
| inspect(key) | Origin language (`from`) + source text for a key (devtools/tooling) |
| locale | Current language (readonly) |
| locales | Loaded + loadable languages (readonly): feed a language switcher from one source of truth |
| version | Change counter that powers framework adapters |

## Language helpers

```
import { alternateLinks, inlineMessages, localeDirection, localeFromPath, localeName, localePath, negotiateLocale, persistLocale, resolveLocale, resolveRequestLocale, stripLocalePath, switchLocale } from 'verbaly';

// which language is this page? a fact of the url, undefined when it carries no prefix
localeFromPath({ supported: ['en', 'es', 'pt'] }) ?? 'en';

// which language does this visitor want? url prefix → storage → navigator → fallback
resolveLocale({ supported: ['en', 'es', 'pt'] });
persistLocale('es');                             // localStorage + <html lang> + <html dir>

// server-side: match an Accept-Language header
negotiateLocale('es-PE,en;q=0.8', ['en', 'es']);   // → 'es'

// per-request: url (when it carries the language) → cookie → header → fallback
resolveRequestLocale({ supported: ['en', 'es'], path, routing, cookie, header });

// client switch for SSR setups: catalog → locale → cookie + <html lang> + <html dir>
await switchLocale(instance, 'es');

// language switchers: names and direction from Intl, no tables
localeName('es');        // → 'español'
localeName('de', 'en');  // → 'German'
localeDirection('ar');   // → 'rtl'

// pre-rendered sites: the same page in another language, for a switcher that navigates
localePath('pt', { supported: ['en', 'es', 'pt'], sourceLocale: 'en' });  // /es/docs?q=1#faq → /pt/docs?q=1#faq

// the route behind a localized url, for a router that keeps one tree
stripLocalePath({ supported: ['en', 'es'], path: '/es/docs' });   // → '/docs'

// this page's address in every language, for the head of a server-rendered page
alternateLinks({ supported, sourceLocale: 'en', path: '/docs', baseUrl });

// the messages `verbaly render` wrote into this page, when you asked it to
inlineMessages();   // → { 'home.title': 'El gate del build' } or undefined
```

`localeFromPath` and `resolveLocale` answer two different questions, and picking the wrong one is the classic bug. `localeFromPath(options)` asks **which language this page is in**. It reads the `/{locale}/` prefix and returns `undefined` when the url carries none, so on a site with a tree per language you write `localeFromPath(...) ?? sourceLocale` and nothing can contradict the url. `resolveLocale(options)` asks **which language this visitor wants**: the url prefix first, then the stored choice, then `navigator.languages` with its closest match, then your `fallback` (`path: false` switches the url off). Use it to decide where to send someone, never to decide what a page already says. `persistLocale` remembers a switch. All of them are safe on a server. The first two take a `base` for a site served from a subfolder, and the storage ones accept a custom `storageKey` (`false` turns storage off). See [Plain HTML → Picking the language at startup](https://verbaly.dev/docs/frameworks/dom.md#locale-bootstrap) for the full pattern.

`negotiateLocale(header, supported, fallback?)` is the server-side counterpart: give it an `Accept-Language` header and your languages and it returns the best match. It respects quality values and ignores case. Each language finds the closest one you support: `es-PE` matches `es`, `zh-HK` matches `zh-Hant`, and `pt` or `pt-PT` matches `pt-BR`, but never one in another script (`zh-HK` never gets `zh-Hans`). It works with any server; the SvelteKit, Nuxt and Next.js integrations use it under the hood.

`resolveRequestLocale(options)` makes the whole per-request decision in one call. Give it the `path` and your `routing`, and the address decides: a prefixed page is that language for everyone, and a page with no prefix is your source language, so a saved choice can never translate it by accident. Leave `routing` out and the order is the stored cookie first, then the `Accept-Language` header, then your `fallback`. `LOCALE_STORAGE_KEY` exports the shared name (`verbaly-locale`) that the browser storage and the server's cookie both use.

`inlineMessages(root?)` reads the messages `verbaly render` wrote into the page when `render.inlineCatalog` is on, so a pre-translated page needs no catalog over the network. You rarely call it: the generated module already does, and passes the result as `partial` so a message the page never showed still loads on demand instead of falling back in silence.

`stripLocalePath(options)` is the inverse of `localePath`: it gives the route behind a localized address, so a router can match one tree instead of one per language. `alternateLinks(options)` returns this page's address in every language plus an `x-default`, ready for `link rel="alternate"` tags in a server-rendered head. It is the same set `verbaly render` writes into a static site, and it is empty when your addresses carry no language, because one address cannot honestly claim to be every language at once.

`localePath`, `alternateLinks` and `switchLocale` also take `trailingSlash` (`'always'`, `'never'` or `'ignore'`), so every address they build ends the way your site's do. You rarely pass it: `verbaly/app` binds the one Astro or Next is set to, and without one each address keeps the form it had.

`switchLocale(instance, locale, options?)` is the client-side switch the server integrations share: it loads the catalog first, then switches the language, writes the `verbaly-locale` cookie and updates the `lang` and `dir` attributes. Safe to call on the server (it does nothing there); `@verbaly/sveltekit` re-exports it.

`localeName(locale, displayIn?)` and `localeDirection(locale)` feed a language switcher without hardcoded tables: real language names via `Intl.DisplayNames` (the name in its own language by default) and the writing direction of any language. Right-to-left languages need no extra work: `switchLocale`, `persistLocale`, the server integrations and `verbaly render` already keep `dir` right on their own.

## Type-level safety

```title="editor"
v.t('home.title');            ✓
v.t('home.title', { x: 1 });  ✗ no params declared
v.t('nope');                  ✗ unknown key
```

TypeScript parses your messages: `FlatKeys` flattens nested trees, `ParamNames` reads `{param}` occurrences, and `TArgs` makes params required exactly when the message declares them.

With the compiler, the generated types fill in `Register`, so `Translate` is your project's `t` and `Locale` the union of your languages: every `t` an adapter hands out (`useT()`, `getT()`) and every instance of the generated module checks keys and params against your catalog. An instance you build from a dictionary keeps that dictionary's types. All three are types only, so they cost nothing at runtime.

> **Dynamic content**
>
> Runtime keys work too: `addMessages` + `t(dynamicKey)` cover CMS-driven content that compiler-only tools can't handle. A key held in a string compiles as it is; only a key you write by hand is checked against your messages.

## Low-level exports

Building tooling on top of Verbaly? The package exports the same pieces the compiler uses. `parse(message)` gives you the message AST, and `parseTags(text)` with `RICH_TAGS` is the rich-text tokenizer and its list of allowed tags, which is what a custom renderer needs. `flatten(tree)` turns a nested tree into dot-keys. `safeHref(href)` and `safeAttribute(name, value)` are the URL and attribute guards, and `normalizeLink(link)` is the one link normalizer every adapter shares, along with the `RichLink` type.
