Integrations
Svelte
The official Svelte 5 package for Verbaly. Idiomatic stores over the same reactive core, store factories for app-level use, and a <Trans> component for rich text.
What you can accomplish:
- Translate with stores:
$tre-renders on every language switch, no wiring - Bind a language switcher in one line:
bind:valueon the language 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
Add the runtime, this package and the Vite plugin, then the compiler, which is where the verbaly command lives. init writes your config and your source catalog.
pnpm add verbaly @verbaly/svelte @verbaly/vite pnpm add -D @verbaly/compilerThen add verbaly() to the plugins in vite.config. It writes verbaly/app, the module your components read.
Setup & stores
<script>
// root component / layout:
import { provideVerbaly } from '@verbaly/svelte';
import { verbaly } from 'verbaly/app';
provideVerbaly(verbaly);
</script>
<script>
// any child component:
import { useT, useLocale } from '@verbaly/svelte';
const t = useT();
const locale = useLocale(); // writable store
const count = 3;
</script>
<p>{$t`You have ${count} messages`}</p>
<select bind:value={$locale}>…</select>- Idiomatic stores:
$tre-renders on every language switch;bind:value={$locale}on a select just works. - No component tree?
tStore(instance)/localeStore(instance)build the same stores without context, shared by the whole app. - No
provideVerbalyabove a component, in the browser?useT()reads the instanceverbaly/appcreates, and the bundler plugin loads that module in every component that imports@verbaly/svelte, so a single-page app or a component test needs no wrapper. On a server a parent has to provide it, since each request has its own instance.
The language a visitor picks
Setting $locale switches every component, and the page follows: <html lang>, <html dir> and the choice, saved in the browser. A single-page app starts in its source language, so read that choice back before mounting:
// the saved choice, else the browser's, loaded before anything renders
import { mount } from 'svelte';
import { resolveLocale } from 'verbaly';
import { locales, setLocale } from 'verbaly/app';
import App from './App.svelte';
setLocale(resolveLocale({ supported: locales, path: false })).then(() =>
mount(App, { target: document.getElementById('app')! }),
);Where a server renders the page, as in SvelteKit, switch with switchLocale from verbaly/app instead: it also sets the cookie the server reads.
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('oHfbnDd4', { name, count })}</h1>Prefer readable keys? $t.id('inbox.title') before the template extracts under your id instead of a content hash.
Prefer to keep the text in your catalog? Write only its key: it is checked and typed the same way. See Keys and catalogs.
Rich text with <Trans>
Svelte has its own component: 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 from the same list of allowed tags asdata-verbaly-rich. Unknown tags unwrap to inert text,richTagsoverrides. - Uses the instance from
provideVerbaly; passinstance={verbaly}explicitly when there's no context. Re-renders on every language switch. - Named links: the
linksprop renders named tags as real<a>elements, with hrefs from your code, never from messages;javascript:blocked. - Your own components: the
componentsprop maps a tag to a Svelte component that receives the tag content as children, and wins over links and the allowed tags.
SvelteKit
Server-rendered pages arrive already translated in the visitor's language, and the browser takes over with the same language and catalog: no flash of untranslated text, no mismatch between server and browser.
- Every page renders in the visitor's language, taken from the address when it carries one, and otherwise from their saved choice or
Accept-Languageheader - 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:
switchLocaleloads the catalog, then persists the choice for the next server render
SvelteKit needs the server package (@verbaly/sveltekit) alongside the Svelte package, the Vite plugin and the compiler:
pnpm add verbaly @verbaly/sveltekit @verbaly/svelte @verbaly/vite pnpm add -D @verbaly/compilerinit writes verbaly.config.ts and your source catalog. List your languages there (locales: ['en', 'es']): the build, verbaly extract and verbaly check all read them.
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 language 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 'verbaly/app';
export const handle = verbalyHandle({ locales, routing });
// src/app.d.ts
declare namespace App {
interface Locals { verbalyLocale: string }
}Hand the language 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 'verbaly/app';
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 'verbaly/app';
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 from verbaly/app already knows your languages and your URL mode. Hand it the instance this page renders with: with the language in the URL it goes to the same page in the other language, and without it it loads the catalog and switches the page in place. Either way it writes the cookie the server hook reads, so the next request already matches:
<script>
import { switchLocale } from 'verbaly/app';
import { useVerbaly } from '@verbaly/svelte';
// the instance this page renders with: one per request
const verbaly = useVerbaly();
</script>
<button onclick={() => switchLocale('es', { instance: verbaly })}>Español</button>- The cookie defaults to
verbaly-locale(same identity as the core's storage key);cookie: falseon either side disables it, for pureAccept-Language. fallbackdefaults to your first language; negotiation follows the order of preference of the browser, andes-PEmatcheses.- No dependency on SvelteKit itself: the hook is typed structurally and stays compatible with SvelteKit 2 and 3.