# Vue

Source: https://verbaly.dev/docs/frameworks/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.

```sh
npm install verbaly @verbaly/vue @verbaly/vite
# or: pnpm add verbaly @verbaly/vue @verbaly/vite
# or: yarn add verbaly @verbaly/vue @verbaly/vite
# or: bun add verbaly @verbaly/vue @verbaly/vite
```

```sh
npm install -D @verbaly/compiler
# or: pnpm add -D @verbaly/compiler
# or: yarn add -D @verbaly/compiler
# or: bun add -D @verbaly/compiler
```

```sh
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](https://verbaly.dev/docs/frameworks/vite.md#unplugin) shows how.

## Setup & composables

```ts title="main.ts"
import { verbalyPlugin } from '@verbaly/vue';
import { verbaly } from 'verbaly/app';

app.use(verbalyPlugin(verbaly));
```

```vue title="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>
```

- 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()` and `useLocale()` read the instance `verbaly/app` creates, 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:

```ts title="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.

```vue title="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](https://verbaly.dev/docs/guide/keys.md).

### Rich text with \<Trans>

Same idea; in Vue each named tag is a render function that wraps its children:

```vue title="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.

- 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
- Zero wiring: one module entry replaces the Vite plugin setup, the negotiation and the `lang` and `dir` attribute sync

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

```sh
npm install verbaly @verbaly/nuxt @verbaly/vue
# or: pnpm add verbaly @verbaly/nuxt @verbaly/vue
# or: yarn add verbaly @verbaly/nuxt @verbaly/vue
# or: bun add verbaly @verbaly/nuxt @verbaly/vue
```

```sh
npm install -D @verbaly/compiler
# or: pnpm add -D @verbaly/compiler
# or: yarn add -D @verbaly/compiler
# or: bun add -D @verbaly/compiler
```

```sh
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:

```ts title="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`.

> **Why hydration never flashes**
>
> The module resolves the language on the server: the address first when it carries one, then the saved choice, then `Accept-Language`, then your fallback. The result rides the Nuxt payload, and the client builds its instance from that same value, with the catalog awaited before render. Both sides produce identical HTML, so nothing repaints and nothing mismatches.

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

```vue title="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>
```

- The cookie defaults to `verbaly-locale` (same identity as the core's storage key); `cookie: false` in the module options disables it, for pure `Accept-Language`.
- `fallback` defaults to your source language; negotiation follows the order of preference of the browser, and `es-PE` matches `es`.
- `ssr: false` is covered too: the module resolves the language in the browser, reading the address first when it carries the language, then the cookie, then `navigator.languages`, then your fallback.
- No dependency on Nuxt itself: the module is typed structurally, without `@nuxt/kit`. The `verbaly` key in `nuxt.config.ts` is 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](https://verbaly.dev/docs/reference/cli.md).
