@verbaly/nuxt
v0.63.0
Published
Nuxt integration for Verbaly: zero-config module with per-request locale negotiation and flash-free hydration.
Maintainers
aronchinoReadme
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⚡ 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>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:
| Option | What it does |
| ---------- | ------------------------------------------------------------------------------------------------------- |
| cookie | Cookie read/written for the user's choice (default verbaly-locale); false = Accept-Language only. |
| fallback | Locale when nothing matches (defaults to the source locale). |
- When your URLs carry the language, the address decides it and the cookie is not consulted: on
/es/docsa visitor gets Spanish whatever they picked before, and on an unprefixed page they get your source language. That follows yourroutingsetting; nothing to configure here. - No dependency on
nuxtor@nuxt/kit: the module is typed structurally; the only moving parts are core primitives (resolveRequestLocale) and the generatedcreateRequestInstance. - For fully static sites (
nuxi generate), considerverbaly renderfor pre-translated output per locale.
📚 Docs
Full guide: verbaly-web.vercel.app/docs/frameworks/vue#nuxt
License
MIT © Aron Soto