Svelte

What you can accomplish:

• Translate with stores: $t re-renders on every locale switch, no wiring
• Bind a language switcher in one line: bind:value on the locale store just works
• Use context or store factories, with or without a component tree
• Map a tag in a message to your own component with the <Trans> components prop

Installation

Install the package with your preferred package manager.

$ pnpm add @verbaly/svelte

Setup & stores

<script>
  // root component / layout:
  import { provideVerbaly } from '@verbaly/svelte';
  import { verbaly } from 'virtual:verbaly';
  provideVerbaly(verbaly);
</script>

<script>
  // any child component:
  import { useT, useLocale } from '@verbaly/svelte';
  const t = useT();
  const locale = useLocale();  // writable store
</script>

<p>{$t('inbox', { count: 3 })}</p>
<select bind:value={$locale}>…</select>

• Idiomatic stores: $t re-renders on every locale switch; bind:value={$locale} on a select just works.
• No component tree? tStore(instance) / localeStore(instance) build the same stores without context, as app-level singletons.
• No provideVerbaly above a component, in the browser? useT() reads the instance virtual:verbaly creates, so a component test needs no wrapper. On a server a parent has to provide it, since each request has its own instance.
• Rich text: the core's DOM interpreter works in any Svelte app via data-verbaly-rich + bindDom (see Plain HTML → Rich text).

Write the text in place

The compiler reads your .svelte files too: write the source text with the store tag, in a markup expression or in the script, and it is extracted, keyed and typed on save. Plain display text is never extracted, so a page can show t`…` as an example safely. No key to invent, no catalog to touch.

<h1>{$t`Hola ${name}, tienes ${count} mensajes`}</h1>

<!-- extracted on save; the build rewrites it to: -->
<h1>{$t('x7Ka9q2f', { name, count })}</h1>

Prefer readable keys? $t.id('inbox.title') before the template extracts under your id instead of a content hash.

Rich text with <Trans>

Svelte has a real component too: import it from the Trans.svelte subpath (raw component, compiled by your bundler):

<script>
  import Trans from '@verbaly/svelte/Trans.svelte';
  import DocsLink from './DocsLink.svelte';
</script>

<Trans id='home.title' />
<Trans id='greet' values={{ name: 'Aron' }} />

<!-- message: 'Read the <docs>guide</docs>' → your component wraps the tag content -->
<Trans id='cta' components={{ docs: DocsLink }} />

• Message tags (The <em>build</em> gate) render as real elements against the same phrasing whitelist as data-verbaly-rich. Unknown tags unwrap to inert text, richTags overrides.
• Uses the instance from provideVerbaly; pass instance={verbaly} explicitly when there's no context. Re-renders on every locale switch.
• Named links: the links prop renders named tags as real <a> elements, with hrefs from your code, never from messages; javascript: blocked.
• Your own components: the components prop maps a tag to a Svelte component that receives the tag content as children, and wins over links and the whitelist.

SvelteKit

Server-rendered pages arrive already translated in the visitor's language, and the client hydrates with the same locale and catalog: no flash of untranslated text, no hydration mismatch.

• Every page renders in the visitor's language, taken from the address when it carries one, and otherwise from their saved choice or Accept-Language header
• No flash of untranslated text: the HTML the server sends and the page after hydration are identical, catalog included
• Each request gets its own instance, so simultaneous visitors never see each other's language
• A one-call language switcher: switchLocale loads the catalog, then persists the choice for the next server render

SvelteKit needs the SSR package (@verbaly/sveltekit) alongside the Svelte bindings:

$ pnpm add verbaly @verbaly/sveltekit @verbaly/svelte @verbaly/vite

Wire it up

Three wires on the server, one on the client. First the Vite plugin and the lang placeholder:

// vite.config.ts
import { sveltekit } from '@sveltejs/kit/vite';
import verbaly from '@verbaly/vite';

export default { plugins: [verbaly(), sveltekit()] };

<!-- src/app.html -->
<html lang="%verbaly.lang%" dir="%verbaly.dir%">

The server hook resolves the locale per request and fills the placeholder. Pass routing and the address decides when it carries the language, falling back to the saved choice, then Accept-Language, then your fallback:

// src/hooks.server.ts
import { verbalyHandle } from '@verbaly/sveltekit';
import { locales, routing } from 'virtual:verbaly';

export const handle = verbalyHandle({ locales, routing });

// src/app.d.ts
declare namespace App {
  interface Locals { verbalyLocale: string }
}

Hand the locale to the client, then build one instance per render with the catalog awaited, the no-flash guarantee:

// +layout.server.ts
export const load = ({ locals }) => ({ locale: locals.verbalyLocale });

// +layout.ts
import { createRequestInstance } from 'virtual:verbaly';

export const load = async ({ data }) => ({
  ...data,
  verbaly: await createRequestInstance(data.locale),  // catalog ready BEFORE render
});

<!-- +layout.svelte -->
<script>
  import { provideVerbaly } from '@verbaly/svelte';
  let { data, children } = $props();
  provideVerbaly(data.verbaly);
</script>

{@render children()}

From here it's plain @verbaly/svelte: useT() / useLocale() stores and Trans.svelte work unchanged in every component.

$t is typed by your catalog: the types go to src/verbaly.d.ts, the folder SvelteKit's tsconfig reads, so svelte-check sees them with nothing to configure and fails on a key no catalog has.

One route tree for every language

If your pages live at /es/docs, you do not need a route folder per language. One universal hook makes /es/docs render through your /docs route, so your routes stay exactly as they were:

import { verbalyReroute } from '@verbaly/sveltekit';
import { locales } from 'virtual:verbaly';

export const reroute = verbalyReroute({ locales });

It goes in hooks.ts and not hooks.server.ts, because moving between pages in the browser has to resolve the same way the server did.

Switching languages

switchLocale loads the catalog first, switches live, then writes the cookie the server hook reads, so the next SSR request already matches:

<script>
  import { switchLocale } from '@verbaly/sveltekit';
  import { useVerbaly } from '@verbaly/svelte';

  const verbaly = useVerbaly();
</script>

<button onclick={() => switchLocale(verbaly, 'es')}>Español</button>

• The cookie defaults to verbaly-locale (same identity as the core's storage key); cookie: false on either side disables it, for pure Accept-Language.
• fallback defaults to your first locale; negotiation understands q-values and narrows regions (es-PE matches es).
• No dependency on SvelteKit itself: the hook is typed structurally and stays compatible across Kit 2.x.