or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

build-optimizations.mdindex.mdplugin-configuration.mdresource-processing.mdsfc-integration.md
tile.json

tessl/npm-intlify--unplugin-vue-i18n

Unplugin that provides comprehensive Vue I18n integration capabilities for various bundlers including Vite, Webpack, and Nuxt

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@intlify/unplugin-vue-i18n@6.0.x

To install, run

npx @tessl/cli install tessl/npm-intlify--unplugin-vue-i18n@6.0.0

index.mddocs/

@intlify/unplugin-vue-i18n

@intlify/unplugin-vue-i18n is an unplugin that provides comprehensive Vue I18n integration capabilities for various bundlers including Vite, Webpack, and Nuxt. It enables i18n resource pre-compilation to optimize Vue I18n performance by transforming locale messages into JavaScript functions or AST objects during build time.

Package Information

  • Package Name: @intlify/unplugin-vue-i18n
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @intlify/unplugin-vue-i18n

Core Imports

import VueI18nPlugin from "@intlify/unplugin-vue-i18n/vite";
import { PluginOptions, SFCLangFormat, VueI18nModule } from "@intlify/unplugin-vue-i18n";

For Webpack:

import VueI18nPlugin from "@intlify/unplugin-vue-i18n/webpack";

For direct unplugin usage:

import { unplugin, unpluginFactory } from "@intlify/unplugin-vue-i18n";

For types only:

import type { PluginOptions, SFCLangFormat } from "@intlify/unplugin-vue-i18n/types";

Basic Usage

Vite Configuration

// vite.config.ts
import { defineConfig } from 'vite';
import vue from '@vitejs/plugin-vue';
import VueI18nPlugin from '@intlify/unplugin-vue-i18n/vite';
import path from 'path';

export default defineConfig({
  plugins: [
    vue(),
    VueI18nPlugin({
      include: [path.resolve(__dirname, './src/locales/**')],
      runtimeOnly: true,
      compositionOnly: true
    })
  ]
});

Webpack Configuration

// webpack.config.js
const VueI18nPlugin = require('@intlify/unplugin-vue-i18n/webpack');

module.exports = {
  plugins: [
    VueI18nPlugin({
      include: [path.resolve(__dirname, './src/locales/**')],
      runtimeOnly: true,
      compositionOnly: true
    })
  ]
};

Using Pre-compiled Messages

// Import all locale messages automatically
import messages from '@intlify/unplugin-vue-i18n/messages';
import { createI18n } from 'vue-i18n';

const i18n = createI18n({
  locale: 'en',
  messages
});

Architecture

@intlify/unplugin-vue-i18n is built around several key components:

  • Unplugin Core: Universal plugin system supporting Vite, Webpack, and other bundlers
  • Resource Plugin: Pre-compiles i18n resources (JSON, YAML, JS, TS) at build time
  • SFC Integration: Processes <i18n> custom blocks in Vue Single File Components
  • Virtual Module System: Provides @intlify/unplugin-vue-i18n/messages for bulk message imports
  • Directive Optimization: Optimizes v-t translation directives for better performance
  • Vue I18n Build Selection: Automatically selects appropriate Vue I18n builds (runtime vs full)

Capabilities

Plugin Configuration

Core plugin configuration and initialization for different bundlers. Supports universal unplugin architecture with bundler-specific optimizations.

/**
 * Main unplugin factory function
 * @param options - Plugin configuration options
 * @param meta - Unplugin context metadata
 * @returns Array of unplugin options
 */
function unpluginFactory(
  options?: PluginOptions,
  meta: UnpluginContextMeta
): UnpluginOptions[];

/**
 * Main unplugin instance for universal bundler support
 */
const unplugin: UnpluginInstance<PluginOptions | undefined, boolean>;

/**
 * Plugin configuration options interface
 */
interface PluginOptions {
  include?: string | string[];
  onlyLocales?: string | string[];
  allowDynamic?: boolean;
  module?: VueI18nModule;
  dropMessageCompiler?: boolean;
  runtimeOnly?: boolean;
  compositionOnly?: boolean;
  ssr?: boolean;
  fullInstall?: boolean;
  forceStringify?: boolean;
  defaultSFCLang?: SFCLangFormat;
  globalSFCScope?: boolean;
  strictMessage?: boolean;
  escapeHtml?: boolean;
  optimizeTranslationDirective?: boolean | string | string[];
  transformI18nBlock?: (src: string | Buffer) => string;
}

type SFCLangFormat = 'json' | 'json5' | 'yml' | 'yaml';
type VueI18nModule = 'vue-i18n' | 'petite-vue-i18n';

Plugin Configuration

Resource Processing

Pre-compilation and transformation of i18n resource files including JSON, YAML, JavaScript, and TypeScript locale files. Handles static bundling and virtual module generation.

// Virtual import for all messages
declare module '@intlify/unplugin-vue-i18n/messages' {
  import type { I18nOptions } from 'vue-i18n';
  const messages: I18nOptions['messages'];
  export default messages;
}

Resource Processing

SFC Integration

Processing of Vue Single File Component <i18n> custom blocks with support for multiple formats, scoping, and import functionality.

interface VueQuery {
  vue?: boolean;
  src?: boolean;
  global?: boolean;
  type?: 'script' | 'template' | 'style' | 'custom' | 'i18n';
  blockType?: string;
  index?: number;
  locale?: string;
  lang?: string;
  raw?: boolean;
  issuerPath?: string;
}

function parseVueRequest(id: string): {
  filename: string;
  query: VueQuery;
};

SFC Integration

Build Optimizations

Vue I18n build selection, tree-shaking, and performance optimizations including runtime-only builds and message compiler optimization.

interface BuildOptimizations {
  runtimeOnly: boolean;
  compositionOnly: boolean;
  fullInstall: boolean;
  dropMessageCompiler: boolean;
  ssr: boolean;
}

Build Optimizations

Core Plugin Functions

Internal plugin functions and utilities for advanced usage and customization.

/**
 * Resolve and normalize plugin options
 * @param options - Raw plugin options
 * @returns Resolved options with defaults applied
 */
function resolveOptions(options: PluginOptions): ResolvedOptions;

/**
 * Resource processing plugin instance
 * @param options - Resolved plugin options
 * @param meta - Unplugin context metadata
 * @returns Unplugin options for resource processing
 */
function resourcePlugin(
  options: ResolvedOptions,
  meta: UnpluginContextMeta
): UnpluginOptions;

/**
 * Translation directive optimization plugin
 * @param options - Resolved plugin options
 * @returns Unplugin options for directive optimization
 */
function directivePlugin(options: ResolvedOptions): UnpluginOptions;

/**
 * Resolved plugin options with computed defaults
 */
interface ResolvedOptions {
  include: string | string[] | undefined;
  exclude: string | undefined;
  module: string;
  onlyLocales: string[];
  forceStringify: boolean;
  defaultSFCLang: string;
  globalSFCScope: boolean;
  runtimeOnly: boolean;
  dropMessageCompiler: boolean;
  compositionOnly: boolean;
  fullInstall: boolean;
  ssrBuild: boolean;
  allowDynamic: boolean;
  strictMessage: boolean;
  escapeHtml: boolean;
  optimizeTranslationDirective: boolean | string | string[];
  translationIdentifiers: Map<string, TranslationDirectiveResolveIndetifier>;
  transformI18nBlock: ((src: string | Buffer) => string) | null;
}

/**
 * Translation directive resolver identifier
 */
interface TranslationDirectiveResolveIndetifier {
  type: 'identifier' | 'object';
  key: string;
  style?: 'script-setup' | 'setup-hook';
}

Utility Functions

Internal utilities for plugin operations, logging, and path handling.

/**
 * Package name constant
 */
const PKG_NAME = 'unplugin-vue-i18n';

/**
 * Resolve plugin namespace for debugging
 * @param name - Namespace name
 * @returns Formatted namespace string
 */
function resolveNamespace(name: string): string;

/**
 * Normalize file paths across platforms
 * @param id - File path to normalize
 * @returns Normalized path string
 */
function normalizePath(id: string): string;

/**
 * Warning logger function
 * @param args - Arguments to log
 */
function warn(...args: unknown[]): void;

/**
 * Error logger function
 * @param args - Arguments to log
 */
function error(...args: unknown[]): void;

/**
 * Throw formatted error with plugin context
 * @param message - Error message
 * @throws Formatted error with plugin branding
 */
function raiseError(message: string): void;

/**
 * Get Vite plugin by name from config
 * @param config - Vite user config
 * @param name - Plugin name to find
 * @returns Found plugin or null
 */
function getVitePlugin(config: UserConfig, name: string): RollupPlugin | null;

/**
 * Validate Vue plugin compatibility
 * @param vuePlugin - Vue plugin instance
 * @returns Whether plugin is compatible
 */
function checkVuePlugin(vuePlugin: RollupPlugin | null): boolean;

Types

type SFCLangFormat = 'json' | 'json5' | 'yml' | 'yaml';

type VueI18nModule = 'vue-i18n' | 'petite-vue-i18n';

interface PluginOptions {
  include?: string | string[];
  onlyLocales?: string | string[];
  allowDynamic?: boolean;
  module?: VueI18nModule;
  dropMessageCompiler?: boolean;
  runtimeOnly?: boolean;
  compositionOnly?: boolean;
  ssr?: boolean;
  fullInstall?: boolean;
  forceStringify?: boolean;
  defaultSFCLang?: SFCLangFormat;
  globalSFCScope?: boolean;
  strictMessage?: boolean;
  escapeHtml?: boolean;
  optimizeTranslationDirective?: boolean | string | string[];
  transformI18nBlock?: (src: string | Buffer) => string;
}

/**
 * SFC parsing result with descriptor and errors
 */
interface SFCParseResult {
  descriptor: SFCDescriptor;
  errors: (CompilerError | SyntaxError)[];
}

/**
 * Vue plugin resolved options interface
 */
interface VuePluginResolvedOptions {
  isProduction: boolean;
  root: string;
  compiler: typeof import('vue/compiler-sfc');
  template?: Partial<SFCTemplateCompileOptions>;
}