Skip to content

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:

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/compiler
npx verbaly init

Then 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

main.ts
import { verbalyPlugin } from '@verbaly/vue';
import { verbaly } from 'verbaly/app';

app.use(verbalyPlugin(verbaly));
Inbox.vue
<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>

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:

main.ts
// 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.

Inbox.vue
<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:

Agree.vue
<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.

Nuxt needs the module (@verbaly/nuxt) alongside the Vue package and the compiler:

 pnpm add verbaly @verbaly/nuxt @verbaly/vue
 pnpm add -D @verbaly/compiler
npx verbaly init

Wire 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:

nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@verbaly/nuxt'],
});

// locales live in your verbaly.config (npx verbaly init), where verbaly check reads them too

From 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:

LangPicker.vue
<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>
↑↓to moveEnterto open
Copied to clipboard