Nuxt I18n Micro

Nuxt I18n Micro is a lightweight internationalization module for Nuxt designed for high performance and large-scale projects.

Key architectural features include:

• Strategy-Based Routing: Handles locale prefixes using @i18n-micro/route-strategy (build-time) and @i18n-micro/path-strategy (runtime). Supported strategies include prefix, no_prefix, prefix_except_default, and prefix_and_default.
• Streamlined Translation Loading: Supports JSON files only. Translations are split into a global file for common elements and page-specific files. In dev mode, page-specific files are auto-generated if they do not exist.
• Minimalist Design: Consists of a single Nuxt module and a small set of runtime plugins to minimize bundle size and memory consumption.

The nuxt-i18n-micro ecosystem provides several specialized Vue components to handle internationalization tasks within your application:

• <i18n-group>: Used to group translations under a common prefix.
• <i18n-link>: A localized link component that automatically handles language-specific routing.
• <i18n-switcher>: A component for providing users with a language selection interface.
• <i18n-t>: The primary component for rendering translated text strings.

The @i18n-micro packages are lightweight, framework-specific versions of Nuxt I18n Micro. They are designed to provide essential internationalization functionality with a minimal footprint for environments outside of Nuxt.

Key Characteristics:

• Core Features: Includes basic translation methods, pluralization, and formatting.
• Essential Components: Provides a small set of UI components (like <I18nT>, <I18nLink>, etc.).
• Router Adapter Pattern: Uses an abstraction to decouple i18n from specific routing libraries. You must implement a router adapter to enable routing-aware features.
• Lightweight: Unlike the full Nuxt module, these packages do not include framework-specific routing logic by default and focus primarily on translation functionality.

The nuxt-i18n-micro package provides several specialized composables to handle different aspects of internationalization in a Nuxt application:

• useI18n: The primary composable used for accessing and managing translations.
• useLocaleHead: Used to manage SEO meta tags related to the current locale.
• useI18nHead: Provides page-level SEO overrides, useful for specific content like articles, CMS data, or custom hreflang configurations.
• useI18nLocale: Manages centralized locale state, including cookie handling and synchronization utilities.

nuxt-i18n-micro is composed of modular packages that can often be used independently of the main Nuxt module. For example, you can use @i18n-micro/vue in a standalone Vue application or @i18n-micro/core in any environment.

Each package provides specific functionality ranging from framework bindings (Astro, Preact, React, Solid, Vue) to core logic, utilities, and devtools.

The Nuxt I18n Micro runtime API provides methods for translation, locale management, and event handling within your Nuxt application. The API is categorized into three main areas:

1. Methods: Core functions for translating strings and managing locales, including $t, $ts, $_t, $_ts, locale switching, and routing helpers.
2. Events: Lifecycle hooks for reacting to i18n changes, such as i18n:register, i18n:beforeLocaleSwitch, and i18n:afterLocaleSwitch.
3. Translations and Cache: Tools for managing translation data via TranslationStorage, payload loading, and cache clearing using $clearCache.

@i18n-micro/hmr provides utilities to enable hot-reloading of translations during Nuxt I18n Micro development mode. This allows you to see translation changes in your application immediately without a full page reload or server restart.

import { handleTranslationWatchChange } from '@i18n-micro/hmr/watcher'
import { generateHmrPlugin } from '@i18n-micro/hmr/generate-plugin'
import { SERVER_CC_KEY } from '@i18n-micro/hmr/cache-keys'

The @i18n-micro/types-generator provides the following capabilities:

• Automatic type generation: Creates TypeScript types directly from your JSON translation files.
• Full type safety: Ensures translation keys are valid at compile time.
• IDE autocomplete: Provides intelligence for translation keys within your editor.
• Hot reload: Automatically updates types when translation files change.
• Zero runtime overhead: The generation process happens at build/dev time and does not affect production performance.

The @i18n-micro/test-utils package provides a suite of exported utilities for testing i18n logic without a full Nuxt environment. It offers two main ways to interact with i18n:

1. Mock Instance: Use createFakeI18n to get a comprehensive object containing both prefixed ($t) and non-prefixed (t) methods, along with state management.
2. Standalone Utilities: Use exported functions like setLocale, t, ts, localePath, and mergeTranslations to manipulate a global test state.

Commonly used utilities include:

• Translations: t, ts, tc (pluralization), tn (number formatting), td (date formatting).
• Locale Management: setLocale, getLocale, setLocales, setDefaultLocale.
• Routing: localePath, localeRoute, switchLocalePath.

The @i18n-micro/vitepress package provides VitePress bindings for i18n-micro. It offers a single runtime API, createI18n, which handles translations, path helpers, and provides the Vue plugin and route synchronization for the VitePress theme.

Depending on your needs, you can import from different entry points:

• @i18n-micro/vitepress: For client-side usage (includes createI18n, useI18n, and getLocaleFromPath).
• @i18n-micro/vitepress/theme: For defining the VitePress theme using defineI18nTheme.
• @i18n-micro/vitepress/config: For VitePress configuration using withI18n and buildVitePressLocales.
• @i18n-micro/vitepress/node: For Node.js/generator usage (includes createI18n with VitePress path methods).

In v3.0.0, routing and path logic were split into dedicated, tree-shakeable packages:

• @i18n-micro/route-strategy: Handles build-time route generation. It extends Nuxt pages with localized routes, aliases, and nested routes. It uses a RouteGenerator and extendPages API with various strategies like no_prefix, prefix, prefix_except_default, and prefix_and_default.
• @i18n-micro/path-strategy: Handles runtime path and locale management. It provides the PathStrategy for building localized paths, resolving redirects, and locale switching. It is designed to be tree-shakeable so only the selected strategy is bundled.