Integrations
Vue
The official Vue 3 package for Verbaly. Composables with automatic cleanup, a <Trans> component for rich text, and keys + params fully typed.
What you can accomplish:
- Translate with composables (useT, useLocale) that react to every language switch
- Bind the language directly to a select:
useLocale()returns a writable computed - Keep keys and params fully typed, with autocompletion from your own messages
- Zero leaks: subscriptions are per-component and cleaned up via
onScopeDispose
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/vue @verbaly/vite pnpm add -D @verbaly/compilerThen add verbaly() to the plugins in vite.config. It writes verbaly/app, the module your components read.
On webpack, Rollup, esbuild or Rspack, install @verbaly/unplugin in place of @verbaly/vite: other bundlers shows how.
Setup & composables
import { verbalyPlugin } from '@verbaly/vue';
import { verbaly } from 'verbaly/app';
app.use(verbalyPlugin(verbaly));<script setup>
import { useT, useLocale } from '@verbaly/vue';
const t = useT();
const locale = useLocale(); // writable: locale.value = 'en'
const count = 3;
</script>
<template>
<p>{{ t`You have ${count} messages` }}</p>
</template>- Subscriptions are per-component and cleaned up on unmount via
onScopeDispose. useLocale()returns a writable computed, so you can bind it directly to a select.- No plugin installed, in the browser?
useT()anduseLocale()read the instanceverbaly/appcreates, and the bundler plugin loads that module in every file that imports@verbaly/vue, so a single-page app or a component test needs no setup. On a server the plugin is required, since each request has its own instance.
The language a visitor picks
Writing locale.value 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 { resolveLocale } from 'verbaly';
import { locales, setLocale } from 'verbaly/app';
setLocale(resolveLocale({ supported: locales, path: false })).then(() => app.mount('#app'));Where a server renders the page, as in Nuxt, switch with switchLocale from verbaly/app instead: it also sets the cookie the server reads.
Write the text in place
The compiler reads your .vue files too: write the source text in an interpolation, in a directive binding or in script setup, 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.
<template>
<p>{{ t`Hola ${user.name}` }}</p>
<a :title="t`Abrir ajustes`">…</a>
</template>
<!-- extracted on save; the build rewrites both to t('key', …) -->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>
Same idea; in Vue each named tag is a render function that wraps its children:
<script setup>
import { Trans } from '@verbaly/vue';
import { h } from 'vue';
const components = { terms: (c) => h('a', { href: '/terms' }, c) };
</script>
<template>
<Trans id='agree' :components='components' />
</template>For plain links skip the render function: the links prop maps tag names to hrefs (a string or an href/target/rel object). components wins on the same name; javascript: hrefs are blocked.
Allowed tags (<em>, <code>…) render as real elements, with no render function needed: the same safe list as plain HTML. richTags overrides it, and the instance prop renders without the plugin.
Nuxt
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
- Zero wiring: one module entry replaces the Vite plugin setup, the negotiation and the
langanddirattribute sync
Nuxt needs the module (@verbaly/nuxt) alongside the Vue package and the compiler:
pnpm add verbaly @verbaly/nuxt @verbaly/vue pnpm add -D @verbaly/compilerWire it up
One line in nuxt.config. The module wires the Vite plugin (live extraction and verbaly/app), picks the language per request and keeps the lang and dir attributes in sync. If your addresses carry the language, it reads them on its own and there is nothing extra to write:
export default defineNuxtConfig({
modules: ['@verbaly/nuxt'],
});
// locales live in your verbaly.config (npx verbaly init), where verbaly check reads them tooFrom here it's plain @verbaly/vue: useT() / useLocale() and <Trans> work unchanged in every component.
useT() is typed by your catalog: the types go to .nuxt/verbaly.d.ts, where Nuxt links them, and npx verbaly extract writes that same file. A key no catalog has fails nuxi typecheck.
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 reads, so the next request already matches:
<script setup>
import { switchLocale } from 'verbaly/app';
import { useVerbaly } from '@verbaly/vue';
// the instance this page renders with: one per request
const verbaly = useVerbaly();
</script>
<template>
<button @click="switchLocale('es', { instance: verbaly })">Español</button>
</template>- The cookie defaults to
verbaly-locale(same identity as the core's storage key);cookie: falsein the module options disables it, for pureAccept-Language. fallbackdefaults to your source language; negotiation follows the order of preference of the browser, andes-PEmatcheses.ssr: falseis covered too: the module resolves the language in the browser, reading the address first when it carries the language, then the cookie, thennavigator.languages, then your fallback.- No dependency on Nuxt itself: the module is typed structurally, without
@nuxt/kit. Theverbalykey innuxt.config.tsis still fully typed (autocomplete and typo checking), and it stays compatible across Nuxt 4. - Fully static site (
nuxi generate)? Prefer pre-translated output per language with verbaly render.