@verbaly/nuxt

Server-rendered pages arrive already translated in the visitor's language (the address first when your URLs carry it, then the cookie, then Accept-Language, then your fallback) and the client hydrates with the same locale and the same catalog, so there's no flash of untranslated text and no hydration mismatch. Each request gets its own instance: no locale leaking between concurrent users.

One line in nuxt.config wires everything: the Vite plugin (live extraction + the virtual:verbaly module), the per-request negotiation and <html lang>/<html dir>.

🚀 Install

pnpm add verbaly @verbaly/nuxt @verbaly/vue
pnpm add -D @verbaly/compiler   # the verbaly command: init, extract, check

⚡ Wire it up

1. The module, the whole setup:

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

Locales live in your verbaly.config (created by npx verbaly init), or inline:

modules: [['@verbaly/nuxt', { locales: ['en', 'es', 'pt'] }]],

2. Write text: components use the Vue bindings as usual:

<script setup>
import { useT } from '@verbaly/vue';
const t = useT();
</script>

<template>
  <h1>{{ t('x7Ka9q2f') }}</h1>
</template>

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.

3. Switching languages (client): persists the cookie the server reads:

<script setup>
import { switchLocale } from 'verbaly';
import { useVerbaly } from '@verbaly/vue';
const verbaly = useVerbaly();
</script>

<template>
  <button @click="switchLocale(verbaly, 'es')">Español</button>
</template>

That's it. The module resolves the locale per request (URL → cookie → Accept-Language → fallback), awaits the catalog before render, installs the Vue plugin, and keeps <html lang> and <html dir> in sync.

📖 Options

Via the verbaly key in nuxt.config or inline module options (fully typed in nuxt.config.ts: autocomplete and typo checking). Every @verbaly/vite option passes through, plus:

• When your URLs carry the language, the address decides it and the cookie is not consulted: on /es/docs a visitor gets Spanish whatever they picked before, and on an unprefixed page they get your source language. That follows your routing setting; nothing to configure here.
• No dependency on nuxt or @nuxt/kit: the module is typed structurally; the only moving parts are core primitives (resolveRequestLocale) and the generated createRequestInstance.
• For fully static sites (nuxi generate), consider verbaly render for pre-translated output per locale.

📚 Docs

Full guide: verbaly-web.vercel.app/docs/frameworks/vue#nuxt

License

MIT © Aron Soto