@comvi/nuxt API Reference

@comvi/nuxt is a Nuxt 3 module that provides auto-imported composables, locale-aware routing, lazy-loaded translations, and full SSR support. All composables and the <T> component are available globally without imports. It builds on @comvi/core and re-exports all core APIs.

Module Options

Configure the module under the comvi key in nuxt.config.ts:

nuxt.config.ts

export default defineNuxtConfig({
  modules: ['@comvi/nuxt'],

  comvi: {
    defaultLocale: 'en',
    locales: [
      { code: 'en', name: 'English' },
      { code: 'de', name: 'Deutsch' },
      { code: 'fr', name: 'Francais' },
    ],
    localePrefix: 'as-needed',
    cdnUrl: 'https://cdn.comvi.io/your-distribution-id',
  },
});

Options Reference

Option	Type	Default	Description
defaultLocale	string	—	Locale used when no other locale is detected (required)
locales	(string | LocaleObject)[]	—	Available locales (required). Strings or objects with code, name, and optional dir
localePrefix	'always' | 'as-needed' | 'never'	'as-needed'	Controls whether URLs include a locale prefix
cdnUrl	string	—	Full CDN URL for loading translations in production
apiKey	string	—	API key for authenticated requests (dev mode)
apiBaseUrl	string	—	API base URL for loading translations
defaultNs	string	'default'	Default namespace for translations
fallbackLanguage	string | string[]	Same as defaultLocale	Language(s) used when a translation key is missing
detectBrowserLanguage	object | false	See below	Browser language detection settings. Set to false to disable
basicHtmlTags	string[]	—	HTML tags allowed in tag interpolation
setup	string	Auto-detected	Path to a setup file that runs before i18n.init(). Auto-detects ./comvi.setup.* in project root

Locale Object Format

Property	Type	Required	Description
code	string	Yes	BCP 47 language code (e.g., en, de, ar)
name	string	No	Human-readable name (e.g., English, Deutsch)
dir	'ltr' | 'rtl'	No	Text direction. Defaults to 'ltr'
iso	string	No	ISO code for SEO (e.g., en-US). Used in hreflang tags

Browser Language Detection

Property	Type	Default	Description
useCookie	boolean	true	Persist detected locale in a cookie
cookieName	string	'i18n_locale'	Cookie name for the persisted locale
cookieMaxAge	number	31536000	Cookie max age in seconds (default: 1 year)
cookieSecure	boolean	true	Set the Secure flag outside dev mode
redirectOnFirstVisit	boolean	true	Redirect to detected locale on first visit
fallbackLocale	string	defaultLocale	Locale when detection fails or returns unsupported locale

nuxt.config.ts

comvi: {
  detectBrowserLanguage: {
    useCookie: true,
    cookieName: 'i18n_locale',
    redirectOnFirstVisit: true,
    fallbackLocale: 'en',
  },
}

Set detectBrowserLanguage: false to disable automatic detection entirely.

Locale Prefix Modes

Mode	Default Locale URL	Other Locale URL	Description
as-needed	/about	/de/about	Default locale has no URL prefix
always	/en/about	/de/about	All locales get a prefix
never	/about	/about	No URL prefixes; locale set via cookie or header

Auto-Imported Composables

All composables are auto-imported by the module. You never need import statements for them.

useI18n(options?)

The primary composable for translating strings and reading locale state.

<script setup lang="ts">
const { t, locale, locales, isLoading } = useI18n();
</script>

<template>
  <h1>{{ t('page.title') }}</h1>
  <p>Current locale: {{ locale }}</p>
</template>

Signature

useI18n(ns?: string)

Pass an optional namespace string to load and scope all t() calls to that namespace.

Returned Values

Reactive state:

Property	Type	Description
t	(key: string, params?) => string	Translate a key with optional interpolation parameters
tRaw	(key: string, params?) => TranslationResult	Return structured output for advanced renderers
locale	Ref<string>	Current language (reactive, writable)
isLoading	Readonly<Ref<boolean>>	true while translations are being fetched
isInitializing	Readonly<Ref<boolean>>	true during init()
translationCache	ComputedRef<Map<string, FlattenedTranslations>>	Translation cache (reactive)

Nuxt-specific:

Property	Type	Description
locales	readonly string[]	Configured locale list from module options
defaultLocale	string	Configured default locale

Methods:

Method	Type	Description
setLocale	(lang: string) => Promise<void>	Switch language and wait for translations to load
addTranslations	(translations: Record<string, Record<string, TranslationValue>>) => void	Add translations at runtime
addActiveNamespace	(ns: string) => Promise<void>	Load a new namespace dynamically
setFallbackLocale	`(locales: string	string[]) => void`
onMissingKey	(cb: (key, locale, namespace) => TranslationResult | void) => () => void	Register callback for missing keys (returns unsubscribe)
onLoadError	(cb: (locale, namespace, error) => void) => () => void	Register callback for load errors (returns unsubscribe)
clearTranslations	(locale?, namespace?) => void	Clear translations from cache
reloadTranslations	(locale?, namespace?) => Promise<void>	Force reload from loader
hasLocale	(locale, namespace?) => boolean	Check if a locale is loaded
hasTranslation	(key, locale?, namespace?, checkFallbacks?) => boolean	Check if a translation exists
getLoadedLocales	() => string[]	Get list of all loaded locales
getActiveNamespaces	() => string[]	Get list of active namespaces
getDefaultNamespace	() => string	Get default namespace
on	(event, callback) => () => void	Subscribe to i18n events (returns unsubscribe)
reportError	(error, context?) => void	Report an error to the configured handler

useLocalePath()

Returns a function that generates locale-prefixed paths based on the current locale.

<script setup lang="ts">
const localePath = useLocalePath();
</script>

<template>
  <NuxtLink :to="localePath('/about')">About</NuxtLink>
  <!-- Renders /de/about when locale is "de" -->
</template>

Function Signature

const localePath: (path: string, locale?: string) => string;

Argument	Type	Default	Description
path	string	—	The path to prefix (required)
locale	string	Current locale	Override the locale for the generated path

useSwitchLocalePath()

Returns a function that generates the current page’s URL in a different locale.

<script setup lang="ts">
const switchLocalePath = useSwitchLocalePath();
</script>

<template>
  <NuxtLink :to="switchLocalePath('en')">English</NuxtLink>
  <NuxtLink :to="switchLocalePath('de')">Deutsch</NuxtLink>
</template>

Function Signature

const switchLocalePath: (locale: string) => string;

useLocaleRoute()

Returns a function that resolves a route object for a given path and locale. Useful when you need the full route object instead of just a path string.

<script setup lang="ts">
const localeRoute = useLocaleRoute();

function goToAbout() {
  const route = localeRoute('/about', 'de');
  if (route) {
    navigateTo(route.fullPath);
  }
}
</script>

Function Signature

const localeRoute: (path: string, locale?: string) => RouteLocationResolved | undefined;

useLocaleHead(options?)

Adds localized <html lang>, dir, canonical, alternate, and Open Graph locale metadata.

<script setup lang="ts">
useLocaleHead({
  baseUrl: 'https://example.com',
});
</script>

useRouteConfig()

Returns the resolved routing config plus helpers for generating localized paths.

const { locales, defaultLocale, localePrefix, getPathname, getAllLocalizedPaths } = useRouteConfig();

Server Utilities

The module auto-imports server utilities from @comvi/nuxt runtime server utils:

Utility	Type	Description
useTranslation(event, options?)	Promise<{ t, locale, hasTranslation }>	Request-scoped server translation helper
loadTranslations(event, locale, options?)	Promise<Record<string, Record<string, TranslationValue>>>	Load namespaces for SSR/SSG payloads
getRequestI18n(event, locale)	Promise<I18n>	Get the request-scoped core i18n instance
getServerRuntimeConfig(event?)	RuntimeConfig	Read public/private Comvi runtime config on the server

<T> Component

Auto-imported. Renders translations with rich content safely using named slots. Same behavior as the @comvi/vue <T> component.

Props

Prop	Type	Default	Description
i18nKey	string	—	Translation key to resolve (required)
params	Record<string, unknown>	{}	Interpolation parameters
ns	string	—	Namespace to look up the key in
locale	string	—	Specific locale to use
fallback	string	—	Fallback text if the key is missing
raw	boolean	—	Forward raw: true to post-processors that support it, such as the in-context editor marker injector
components	Record<string, ComponentHandler>	—	Map of tag names to components (alternative to slots)

Usage

<template>
  <!-- Translation: "Read our <link>terms of service</link>" -->
  <T i18nKey="legal.tos">
    <template #link="{ children }">
      <NuxtLink to="/terms">{{ children }}</NuxtLink>
    </template>
  </T>
</template>

Caution

Never use v-html with translation values. The <T> component provides safe interpolation without XSS risks.

<NuxtLinkLocale>

A locale-aware replacement for <NuxtLink> that automatically prefixes the to prop with the current locale.

<template>
  <NuxtLinkLocale to="/about">About Us</NuxtLinkLocale>
  <!-- Renders <a href="/de/about"> when locale is "de" -->

  <NuxtLinkLocale to="/contact" locale="fr">Contact (FR)</NuxtLinkLocale>
  <!-- Always renders <a href="/fr/contact"> -->
</template>

Props

Inherits all <NuxtLink> props, plus:

Prop	Type	Default	Description
locale	string	Current locale	Override the locale for the link’s to path

$t() Global Helper

Available in all templates without calling useI18n(). Translates a key with optional parameters.

components/Footer.vue

<template>
  <footer>
    <p>{{ $t('footer.copyright', { year: 2025 }) }}</p>
  </footer>
</template>

Note

$t() is a convenience shortcut for templates and returns a string. In <script setup>, use the t function from useI18n() instead.

Setup Hook

The module auto-discovers ./comvi.setup.ts (or .js) at project root, or specify path via setup option.

comvi.setup.ts

import { defineComviSetup } from '@comvi/nuxt/runtime/setup';

export default defineComviSetup(({ i18n }) => {
  i18n.registerLoader({
    en: () => import('./locales/en.json'),
    de: () => import('./locales/de.json'),
  });
});

Runs before i18n.init().

Runtime Config

Access module config via useRuntimeConfig().public.comvi:

server/api/greeting.ts

export default defineEventHandler((event) => {
  const { defaultLocale } = useRuntimeConfig().public.comvi;
  return { greeting: `Default locale is ${defaultLocale}` };
});

Shape:

interface NuxtI18nRuntimeConfig {
  comvi: {
    locales: string[];
    localeObjects: Record<string, LocaleObject>;
    defaultLocale: string;
    localePrefix: 'always' | 'as-needed' | 'never';
    cookieName: string;
    cdnUrl?: string;
    apiBaseUrl?: string;
    defaultNs: string;
    fallbackLanguage: string | string[];
    basicHtmlTags?: string[];
    detectBrowserLanguage: DetectBrowserLanguageOptions | false;
  };
}

Core APIs

@comvi/nuxt builds on @comvi/core and @comvi/vue. Use the Nuxt auto-imported composables/components documented above for application code, and import lower-level core APIs from @comvi/core directly when needed.

Next Steps

Nuxt Integration Guide Full walkthrough of Nuxt setup with routing, lazy loading, and SEO.

Vue API Reference Composables and components shared with the Vue package.

Language Detection How locale detection works across server and client.

Namespaces Organize translations by feature for smaller payloads.