🌐 Getting Started with Nuxt I18n Micro

Welcome to Nuxt I18n Micro! This guide will help you get up and running with our high-performance internationalization module for Nuxt.js.

📖 Overview

Nuxt I18n Micro is a lightweight internationalization module for Nuxt that delivers superior performance compared to traditional solutions. It's designed to reduce build times, memory usage, and server load, making it ideal for high-traffic and large projects.

🤔 Why Choose Nuxt I18n Micro?

Here are some key benefits of using Nuxt I18n Micro:

🚀 High Performance: Significantly reduces build times and memory consumption
📦 Compact Size: Has minimal impact on your app's bundle size
⚙️ Efficiency: Optimized for large-scale applications with a focus on memory consumption and server load
🛠️ Easy Setup: Simple configuration with sensible defaults
🔧 Flexible: Extensive customization options for complex use cases
📚 Well Documented: Comprehensive documentation and examples

🚀 Quick Start

Installation

Install the module in your Nuxt application:

npmyarnpnpmbun

bash

npm install nuxt-i18n-micro

bash

yarn add nuxt-i18n-micro

bash

pnpm add nuxt-i18n-micro

bash

bun add nuxt-i18n-micro

Basic Configuration

Add the module to your nuxt.config.ts:

typescript

export default defineNuxtConfig({
  modules: [
    'nuxt-i18n-micro',
  ],
  i18n: {
    locales: [
      { code: 'en', iso: 'en-US', dir: 'ltr' },
      { code: 'fr', iso: 'fr-FR', dir: 'ltr' },
      { code: 'ar', iso: 'ar-SA', dir: 'rtl' },
    ],
    defaultLocale: 'en',
    translationDir: 'locales',
  },
})

Folder Structure

Your translation files will be automatically generated when you run the application. Here is the full project structure:

my-nuxt-appNuxt project with i18n-micro
nuxt.config.tsmodule config
package.json
pagesyour Nuxt pages
index.vuehome page
about.vueabout page
articlesdynamic route
[id].vue
components2 files
Header.vue
Footer.vue
localestranslation files
en.jsonglobal translations
fr.jsonglobal translations
ar.jsonglobal translations
pagespage-specific translations
index3 filesmatches pages/index.vue
en.json
fr.json
ar.json
about3 filesmatches pages/about.vue
en.json
fr.json
ar.json
articles-id3 filesmatches pages/articles/[id].vue
en.json
fr.json
ar.json
server1 folder, 1 file
api1 file
example.ts
tsconfig.json

Folder Structure Explanation

Global Files (locales/en.json, etc.) — translations shared across the entire app (menus, footer, common UI)
Page-Specific Files (locales/pages/<route>/<locale>.json) — translations unique to specific pages, loaded only when the page is visited
Dynamic Routes — pages/articles/[id].vue maps to locales/pages/articles-id/ (brackets replaced with dashes)
Auto-Generation — all translation files are automatically created when missing during nuxt dev

Basic Usage

Use translations in your components:

vue

<template>
  <div>
    <h1>{{ $t('welcome') }}</h1>
    <p>{{ $t('description', { name: 'World' }) }}</p>
    
    <div>
      <button
        v-for="locale in $getLocales()"
        :key="locale.code"
        @click="$switchLocale(locale.code)"
      >
        {{ locale.code }}
      </button>
    </div>
  </div>
</template>

<script setup>
import { useI18n } from '#imports'

const { $t, $getLocales, $switchLocale } = useI18n()
</script>

⚙️ Configuration Options

The module provides extensive configuration options to customize your internationalization setup.

🌍 Core Locale Settings

`locales`

Defines the locales available in your application.

Type: Locale[]

Each locale object supports:

Property	Type	Required	Description
`code`	`string`	✅	Unique identifier (e.g., `'en'`)
`iso`	`string`	❌	ISO code (e.g., `'en-US'`)
`dir`	`string`	❌	Text direction (`'ltr'` or `'rtl'`)
`disabled`	`boolean`	❌	Disable in dropdown if `true`
`baseUrl`	`string`	❌	Base URL for locale-specific domains
`baseDefault`	`boolean`	❌	Remove locale prefix from URLs

Example:

typescript

locales: [
  { code: 'en', iso: 'en-US', dir: 'ltr' },
  { code: 'fr', iso: 'fr-FR', dir: 'ltr' },
  { code: 'ar', iso: 'ar-SA', dir: 'rtl', disabled: true },
  { 
    code: 'de', 
    iso: 'de-DE', 
    dir: 'ltr', 
    baseUrl: 'https://de.example.com', 
    baseDefault: true 
  },
]

BaseUrl Considerations

Using baseUrl can lead to duplication of internal routes as external links, complicating routing and maintenance. Consider creating external links directly for specific locales instead.

`defaultLocale`

Sets the default locale when no specific locale is selected.

Type: string
Default: 'en'

typescript

defaultLocale: 'en'

`strategy`

Defines how locale prefixes are handled in routes.

Type: string
Default: 'prefix_except_default'

no_prefixprefix_except_defaultprefixprefix_and_default

typescript

strategy: 'no_prefix'
// Routes: /about, /contact
// Locale detection via browser/cookies

typescript

strategy: 'prefix_except_default'
// Default locale: /about, /contact
// Other locales: /fr/about, /de/contact

typescript

strategy: 'prefix'
// All locales: /en/about, /fr/about, /de/about

typescript

strategy: 'prefix_and_default'
// Both prefixed and non-prefixed versions for default locale

📂 Translation Management

`translationDir`

Specifies the directory for translation files.

Type: string
Default: 'locales'

typescript

translationDir: 'i18n' // Custom directory

`disablePageLocales`

Disables page-specific translations, using only global files.

Type: boolean
Default: false

When enabled, only global translation files are used:

locales3 files
en.json
fr.json
ar.json

`fallbackLocale`

Specifies a fallback locale for missing translations.

Type: string | undefined
Default: undefined

typescript

{
  locales: [
    { code: 'en', iso: 'en-US', dir: 'ltr' },
    { code: 'fr', iso: 'fr-FR', dir: 'ltr', fallbackLocale: 'es' },
    { code: 'es', iso: 'es-ES', dir: 'ltr' }
  ],
  defaultLocale: 'en',
  fallbackLocale: 'en' // Global fallback
}

🔍 SEO & Meta Tags

`meta`

Enables automatic SEO meta tag generation.

Type: boolean
Default: true

typescript

meta: true // Generate alternate links, canonical URLs, etc.

`metaBaseUrl`

Sets the base URL for SEO meta tags.

Type: string
Default: '/'

typescript

metaBaseUrl: 'https://example.com'

`canonicalQueryWhitelist`

Specifies which query parameters to preserve in canonical URLs.

Type: string[]
Default: ['page', 'sort', 'filter', 'search', 'q', 'query', 'tag']

typescript

canonicalQueryWhitelist: ['page', 'sort', 'category']

🔄 Advanced Features

`globalLocaleRoutes`

Defines custom localized routes for specific pages.

Type: Record<string, Record<string, string> | false>

typescript

globalLocaleRoutes: {
  'about': {
    en: '/about-us',
    fr: '/a-propos',
    de: '/uber-uns'
  },
  'unlocalized': false // Disable localization entirely
}

`routesLocaleLinks`

Creates links between pages' locale files to share translations.

Type: Record<string, string>

typescript

routesLocaleLinks: {
  'products-id': 'products',
  'about-us': 'about'
}

`customRegexMatcher`

Improves performance for applications with many locales. Instead of checking each locale code one by one, the module uses a single regex to detect whether the first path segment is a locale. The pattern matches the entire first path segment (anchors ^ and $ are applied automatically).

Type: string | RegExp
Default: undefined (auto-generated from locale codes)

Must match ALL locale codes

At build time, the module validates that every locale code in your locales list matches the customRegexMatcher pattern. If any locale code does not match, the build will fail with the error:

Nuxt-i18n-micro: Some locale codes does not match customRegexMatcher

Always verify your regex against all your locale codes before deploying.

typescript

// ✅ Correct: matches 'en-us', 'de-de', 'fr-fr'
customRegexMatcher: '[a-z]{2}-[a-z]{2}'

// ✅ Correct: matches 'en', 'de', 'fr', 'zh'
customRegexMatcher: '[a-z]{2}'

// ❌ Wrong: won't match 'zh-Hant' (uppercase letter)
// This will FAIL the build if 'zh-Hant' is in your locales list
customRegexMatcher: '[a-z]{2}-[a-z]{2}'

🛠️ Development Options

`debug`

Enables logging and debugging information.

Type: boolean
Default: false

typescript

debug: true

`disableWatcher`

Disables automatic creation of locale files during development.

Type: boolean
Default: false

typescript

disableWatcher: true

`missingWarn`

Controls whether to show console warnings when translation keys are not found.

Type: boolean
Default: true

typescript

missingWarn: false // Disable warnings for missing translations

Custom Missing Handler

You can set a custom handler for missing translations using setMissingHandler method. This allows you to send missing translation errors to error tracking services like Sentry.

🔧 Plugin Control

`define`

Enables the define plugin for runtime configuration.

Type: boolean
Default: true

typescript

define: false // Disables $defineI18nRoute

`redirects`

Enables automatic redirection logic.

Type: boolean
Default: true

typescript

redirects: false // Disable automatic locale redirection

`plugin`

Enables the main plugin.

Type: boolean
Default: true

typescript

plugin: false

`hooks`

Enables hooks integration.

Type: boolean
Default: true

typescript

hooks: false

🌐 Language Detection

`autoDetectLanguage`

Automatically detects user's preferred language.

Type: boolean
Default: false

typescript

autoDetectLanguage: true

`autoDetectPath`

Specifies routes where locale detection is active.

Type: string
Default: "/"

typescript

autoDetectPath: "/" // Only on home route
autoDetectPath: "*" // On all routes (use with caution)

🔢 Customization

`plural`

Custom function for handling pluralization.

Type: (key: string, count: number, params: Record<string, string | number | boolean>, locale: string, t: Getter) => string

typescript

plural: (key, count, _params, _locale, t) => {
  const translation = t(key)
  if (!translation) return key
  
  const forms = translation.toString().split('|')
  return (count < forms.length ? forms[count].trim() : forms[forms.length - 1].trim())
    .replace('{count}', count.toString())
}

`localeCookie`

Specifies the cookie name for storing user's locale. This enables locale persistence across page reloads and browser sessions.

Type: string | null
Default: null (but see note below about no_prefix)

Effective default depends on strategy

While the configured default is null (disabled), the module automatically overrides this to 'user-locale' when using strategy: 'no_prefix'. This means:

no_prefix: Cookie is always enabled ('user-locale'), even if you don't set it explicitly. This is required because the URL contains no locale information.
All other strategies: Cookie is null (disabled) unless you set it explicitly.

If you set localeCookie explicitly, your value is always used regardless of strategy.

Required for redirects with prefix strategies

When using prefix strategies (prefix, prefix_except_default, prefix_and_default) with redirects: true (the default), you must set localeCookie for redirect behavior to work correctly. Without a cookie, the redirect plugin cannot remember the user's locale preference across page reloads, and redirects will only work based on Accept-Language header (if autoDetectLanguage: true) or defaultLocale.

typescript

// Enable cookie (recommended when using redirects with prefix strategies)
localeCookie: 'user-locale'

// Enable cookie with custom name
localeCookie: 'my-locale-cookie'

// Disable cookie (default) - locale won't persist across reloads
localeCookie: null

What localeCookie enables:

Persists user's locale preference across page reloads
Remembers locale when user returns to your site
Required for no_prefix strategy to work correctly
Required for redirect behavior in prefix strategies (when redirects: true)

`apiBaseUrl`

Defines the path prefix for fetching cached translations. This is a path prefix only, not a full URL.

Type: string
Default: '/_locales'
Environment Variable: NUXT_I18N_APP_BASE_URL

typescript

apiBaseUrl: 'api/_locales'

The translations will be fetched from /{apiBaseUrl}/{routeName}/{locale}/data.json (e.g., /api/_locales/general/en/data.json).

`apiBaseClientHost`

Defines the base host URL for fetching translations from a CDN or external server on the client side. Use this when translations are hosted on a different domain and need to be fetched from the browser.

Type: string | undefined
Default: undefined
Environment Variable: NUXT_I18N_APP_BASE_CLIENT_HOST

typescript

apiBaseClientHost: 'https://cdn.example.com'

When apiBaseClientHost is set, client-side translations will be fetched from {apiBaseClientHost}/{apiBaseUrl}/{routeName}/{locale}/data.json (e.g., https://cdn.example.com/_locales/general/en/data.json).

`apiBaseServerHost`

Defines the base host URL for fetching translations from a CDN or external server on the server side (SSR). Use this when translations are hosted on a different domain and need to be fetched during server-side rendering.

Type: string | undefined
Default: undefined
Environment Variable: NUXT_I18N_APP_BASE_SERVER_HOST

typescript

apiBaseServerHost: 'https://internal-cdn.example.com'

When apiBaseServerHost is set, server-side translations will be fetched from {apiBaseServerHost}/{apiBaseUrl}/{routeName}/{locale}/data.json (e.g., https://internal-cdn.example.com/_locales/general/en/data.json).

TIP

Use apiBaseUrl for path prefixes, apiBaseClientHost for client-side CDN/external domain hosting, and apiBaseServerHost for server-side CDN/external domain hosting. This allows you to use different CDNs for client and server requests.

🔄 Additional Features

`previousPageFallback`

Enables fallback to previous page translations during page transitions. When navigating between pages, if a translation key is not found on the new page, the module will look for it in the translations from the previous page.

Type: boolean
Default: false

typescript

export default defineNuxtConfig({
  i18n: {
    previousPageFallback: true
  }
})

Use Case

This is especially helpful for pages with asynchronous data loading (useAsyncData, defineAsyncComponent) that may cause translation keys to be displayed as raw paths during loading.

`hmr`

Enables server-side HMR for translations during development. When enabled, the module watches your translation files and invalidates the in-memory server cache for changed locales/pages so that requests immediately get fresh data without restarting the server.

Type: boolean
Default: true (development only)

typescript

export default defineNuxtConfig({
  i18n: {
    // Hot updates for translation files in dev mode
    hmr: true,
  },
})

`cacheMaxSize`

Controls the maximum number of entries in the translation cache. When the limit is reached, the least recently used entry is evicted (LRU policy). Set to 0 (default) for unlimited cache.

Type: number
Default: 0 (unlimited)

`cacheTtl`

Time-to-live for server cache entries in seconds. When a cached entry is accessed, its expiry is refreshed (sliding expiration). Expired entries are evicted on the next cache write. Set to 0 (default) for entries that never expire.

Type: number
Default: 0 (no expiration)

typescript

export default defineNuxtConfig({
  i18n: {
    // Limit cache to 1000 entries, each lives 10 minutes (refreshed on access)
    cacheMaxSize: 1000,
    cacheTtl: 600,
  },
})

When to use

For most projects the default (unlimited, no expiration) is fine — translations are small and finite. However, if your project has thousands of pages with disablePageLocales: false and many locales, the server cache can grow significantly. In long-running Node.js servers this may lead to excessive memory usage.

cacheMaxSize — caps the number of cached entries. Useful for bounding memory.
cacheTtl — ensures stale translations are eventually reloaded from storage. Useful for serverless environments or when translations change at runtime.

Formula for estimating max entries: number_of_locales × (number_of_pages + 1). For example, 10 locales × 500 pages = ~5010 entries.

🔄 Caching Mechanism

Nuxt I18n Micro v3 uses a multi-layer caching architecture built around TranslationStorage — a singleton class that uses Symbol.for on globalThis to ensure a single cache instance across bundles.

Translation Loading Flow

Key Characteristics

🚀 Zero extra requests on first load: SSR-injected data in window.__I18N__ is consumed synchronously on hydration
💾 Process-global server cache: loadTranslationsFromServer() caches merged results via Symbol.for — loaded once per locale/page, served from memory for all subsequent requests
⚡ Single request per page: The API returns already-merged translations (global + page-specific + fallback) — no client-side merging needed
🔄 HMR in development: When hmr: true, translation file changes invalidate the server cache automatically

See the Cache & Storage Architecture for in-depth details.

🌍 Locale State Management

In v3, all locale management goes through the centralized useI18nLocale() composable:

const { setLocale, getLocale, getPreferredLocale } = useI18nLocale()

// Set locale (updates useState + cookie atomically)
setLocale('fr')

// Get current locale
const locale = getLocale()

Do not use useState('i18n-locale') or useCookie('user-locale') directly. The useI18nLocale() composable manages both internally, ensuring consistency between server and client.

See the Custom Language Detection guide for advanced usage.

📚 Next Steps

Now that you have the basics set up, explore these advanced topics:

Routing Strategies - How locale prefixes and redirects work
Per-Component Translations - Learn about $defineI18nRoute
Custom Language Detection - Programmatic locale management with useI18nLocale()
API Reference - Complete method documentation
Cache & Storage - Translation cache architecture
Examples - Real-world usage examples
Migration Guide - Migrating from other i18n solutions or v2

🌐 Getting Started with Nuxt I18n Micro ​

📖 Overview ​

🤔 Why Choose Nuxt I18n Micro? ​

🚀 Quick Start ​

Installation ​

Basic Configuration ​

Folder Structure ​

Basic Usage ​

⚙️ Configuration Options ​

🌍 Core Locale Settings ​

locales ​

defaultLocale ​

strategy ​

📂 Translation Management ​

translationDir ​

disablePageLocales ​

fallbackLocale ​

🔍 SEO & Meta Tags ​

meta ​

metaBaseUrl ​

canonicalQueryWhitelist ​

🔄 Advanced Features ​

globalLocaleRoutes ​

routesLocaleLinks ​

customRegexMatcher ​

🛠️ Development Options ​

debug ​

disableWatcher ​

missingWarn ​

🔧 Plugin Control ​

define ​

redirects ​

plugin ​

hooks ​

🌐 Language Detection ​

autoDetectLanguage ​

autoDetectPath ​

🔢 Customization ​

plural ​

localeCookie ​

apiBaseUrl ​

apiBaseClientHost ​

apiBaseServerHost ​

🔄 Additional Features ​

previousPageFallback ​

hmr ​

cacheMaxSize ​

cacheTtl ​

🔄 Caching Mechanism ​

Translation Loading Flow ​

Key Characteristics ​

🌍 Locale State Management ​

📚 Next Steps ​

🌐 Getting Started with Nuxt I18n Micro

📖 Overview

🤔 Why Choose Nuxt I18n Micro?

🚀 Quick Start

Installation

Basic Configuration

Folder Structure

Basic Usage

⚙️ Configuration Options

🌍 Core Locale Settings

`locales`

`defaultLocale`

`strategy`

📂 Translation Management

`translationDir`

`disablePageLocales`

`fallbackLocale`

🔍 SEO & Meta Tags

`meta`

`metaBaseUrl`

`canonicalQueryWhitelist`

🔄 Advanced Features

`globalLocaleRoutes`

`routesLocaleLinks`

`customRegexMatcher`

🛠️ Development Options

`debug`

`disableWatcher`

`missingWarn`

🔧 Plugin Control

`define`

`redirects`

`plugin`

`hooks`

🌐 Language Detection

`autoDetectLanguage`

`autoDetectPath`

🔢 Customization

`plural`

`localeCookie`

`apiBaseUrl`

`apiBaseClientHost`

`apiBaseServerHost`

🔄 Additional Features

`previousPageFallback`

`hmr`

`cacheMaxSize`

`cacheTtl`

🔄 Caching Mechanism

Translation Loading Flow

Key Characteristics

🌍 Locale State Management

📚 Next Steps