Nuxt I18n

@nuxtjs/i18n is the standard internationalization module for Nuxt applications, built on top of Vue I18n. Adding it to a project’s modules array is enough to get locale-prefixed routing, automatic page duplication per locale, and locale-aware navigation composables without hand-writing route tables.

Under the hood the module hooks into Nuxt’s build pipeline at modules:done to resolve the final locale configuration, then rewrites the page manifest, extends the Vite/webpack bundler, and registers Nitro server routes for serving translation message bundles on demand. This lets it support static generation, SSR, and hybrid rendering with the same configuration surface, including strategies like prefixed, prefix-except-default, and domain-based locale routing where each locale can be served from its own custom domain.

Runtime composables (useLocalePath, useSwitchLocalePath, useLocaleHead, useRouteBaseName) and components (NuxtLinkLocale, SwitchLocalePathLink) give application code a locale-aware way to build links and metadata without manually prefixing paths. Messages are lazy-loaded per locale and, in the experimental prerendering mode, emitted as static JSON assets so they can be served from a CDN instead of a dynamic Nitro endpoint.

The module is actively maintained by the Nuxt community team, ships nightly edge builds for early testing, and is exercised by a large end-to-end spec suite covering routing strategies, SSG, SEO metadata, lazy loading, and multi-domain locale setups.

What You Get

• Automatic locale-prefixed route generation for every page, including custom per-locale paths via the defineI18nRoute macro
• Runtime composables (useLocalePath, useLocaleRoute, useSwitchLocalePath, useRouteBaseName) for building locale-aware links and route names
• useLocaleHead composable and automatic SEO tag generation (hreflang, canonical, og:locale) per locale
• Lazy-loading of translation message files per locale, with an experimental mode that prerenders them as static JSON for CDN delivery
• Multiple routing strategies: locale-prefixed paths, prefix-except-default, or fully separate custom domains per locale
• Browser language auto-detection with cookie-based persistence, configurable redirect behavior on first visit

Common Use Cases

• Adding multi-language support to an existing Nuxt site without hand-rolling a routing layer
• Running the same content on locale-specific domains (e.g. example.com vs example.de) from one Nuxt app
• Statically generating a fully localized, SEO-optimized marketing site with per-locale hreflang tags
• Lazy-loading only the active locale’s translation bundle to keep initial JS payload small on large multi-language apps
• Layering i18n configuration across a Nuxt layers/monorepo setup, merging locales and messages from multiple layers

Under The Hood

Architecture The module’s entry point (src/module.ts) creates a shared context object via createContext/resolveContext and defers most of its work to Nuxt’s modules:done hook, where the final locale/message configuration is resolved once other modules have had a chance to register their own i18n hooks. From there it delegates to focused build-time collaborators: pages.ts rewrites the Nuxt page manifest to inject locale-prefixed and custom per-locale routes, bundler.ts extends the Vite pipeline with plugins for message compilation, and nitro.ts registers server routes that serve lazy-loaded translation bundles. Runtime concerns are kept in a clearly separated src/runtime/ tree (composables, components, plugins, routing utilities) that ships to the client/server bundle, while everything under src/ proper only runs at build/prepare time — a clean split that keeps build-only dependencies out of the shipped runtime.

Tech Stack Written entirely in TypeScript on top of @nuxt/kit for module authoring, it wraps Vue I18n (vue-i18n, @intlify/core, @intlify/shared, @intlify/message-compiler) for translation and message-compilation, unstorage and h3/Nitro for serving message assets, and oxc-parser/oxc-transform/oxc-walker for fast AST-based source transforms (e.g. compiling the defineI18nRoute macro away). The repo builds with nuxt-module-build/unbuild, is organized as a pnpm workspace with separate docs and playground sub-projects, and ships both stable and nightly -edge npm releases via bumpp.

Code Quality Testing is extensive and split into two tiers: unit tests (test/, 25+ files covering routing, detection, message delivery, bundling, and type generation) and end-to-end specs (specs/, covering routing strategies, SSG, SEO, lazy-loading, and multi-domain locale setups) run under Vitest. The project enforces ESLint (with the perfectionist plugin for import/property ordering) and knip for unused-export/dependency detection, and CI runs a build → lint → test matrix on every push and PR. Types are used throughout, including generated .d.ts templates for locale/message shape narrowing.

API Design The public composables (useLocalePath, useLocaleRoute, useSwitchLocalePath, useRouteBaseName, useLocaleHead) mirror the shape of Vue Router’s and Nuxt’s own composable conventions, so existing Nuxt/Vue developers can adopt them with little new API to learn. Domain-based locale routing and the experimental prerendered-messages mode are more unusual capabilities among i18n routing modules, trading some setup complexity for CDN-friendly static output and per-locale custom domains without a second deployment.