monaco-editor-nls-adapter 1.0.0 → 2.0.0

package/README.md

@@ -13,10 +13,24 @@ Multi-language NLS adapter for Monaco Editor 0.50.0+ (Self-hosted). Bridge the g
 
 - **Self-hosted Locales**: No external CDN dependencies; all language data is bundled locally.
 - **Monaco 0.50.0+ Ready**: Fully compatible with the latest internal NLS signatures of Monaco Editor.
+- **SourceMap Support**: Powered by `magic-string` for accurate source-to-bundle mapping and worry-free debugging.
 - **Zero-Config Lazy Loading**: Support for asynchronous initialization with Webpack/Vite chunk splitting.
 - **TypeScript Support**: First-class TS definitions for an excellent developer experience.
-- **Smart Detection**: Automatically detect browser language or manually switch as needed.
+- **Flexible API**: Advanced interfaces like `getCurrentLocale` and `setMessages` (custom data).
 - **Cross-Bundler**: Native support for **Webpack** (Loader) and **Vite/Rollup** (Plugin).
+- **Zero Configuration**: Automatic detection of `pnpm` and monorepo paths out of the box.
+- **Ultra-lightweight**: Redundant test files removed for even faster installation.
+
+## 📦 Supported Frameworks
+
+This adapter is compatible with all modern frontend frameworks:
+
+- **Vue 2**: Seamless integration with Vue CLI and Webpack projects.
+- **Vue 3**: Full support for Vite and Vue CLI configurations.
+- **React**: Compatible with native React apps and `@monaco-editor/react` (supports disabling CDN).
+- **Angular**: Compatible with Angular CLI (Webpack/Vite) build environments.
+- **SSR Frameworks**: Ready for **Next.js** and **Nuxt** server-side rendering environments.
+- **Universal**: Theoretically supports any web project built with **Webpack**, **Vite**, or **Rollup**.
 
 ## 🚀 Installation
 
@@ -31,16 +45,23 @@ npm install monaco-editor-nls-adapter
 In your `webpack.config.js`, add the adapter's loader to process Monaco Editor's ESM files.
 
 ```javascript
+const { loader } = require('monaco-editor-nls-adapter');
+
 module.exports = {
   module: {
     rules: [
       {
         test: /\.js$/,
-        // Crucial: Only process monaco-editor core files to avoid side effects
-        include: /node_modules[\\/]monaco-editor[\\/]esm/,
+        // Crucial: Only process monaco-editor ESM files
+        include: /monaco-editor[\\/]esm/,
         use: [
           {
-            loader: 'monaco-editor-nls-adapter/loader'
+            loader: loader,
+            options: {
+              // Optional: Custom monaco path fragment
+              // Detected automatically in most project structures (npm, pnpm, yarn)
+              // monacoPath: 'monaco-editor/esm'
+            }
           }
         ]
       }
@@ -49,17 +70,42 @@ module.exports = {
 }
 ```
 
-### 2. Vite / Rollup (Plugin)
+### 2. Vue CLI (`vue.config.js`)
+
+For projects using Vue CLI, you can configure the loader via `chainWebpack`:
+
+```javascript
+const { loader } = require('monaco-editor-nls-adapter');
+
+module.exports = {
+  chainWebpack: config => {
+    config.module
+      .rule('monaco-editor-nls')
+      .test(/\.js$/)
+      .include.add(/monaco-editor[\\/]esm/)
+      .end()
+      .use('nls-loader')
+      .loader(loader)
+      .end();
+  }
+};
+```
+
+### 3. Vite / Rollup (Plugin)
 
 In your `vite.config.js` or `vite.config.ts`:
 
 ```javascript
 import { defineConfig } from 'vite';
-import monacoNlsPlugin from 'monaco-editor-nls-adapter/vite-plugin';
+import { vitePlugin } from 'monaco-editor-nls-adapter';
 
 export default defineConfig({
   plugins: [
-    monacoNlsPlugin()
+    vitePlugin({
+      // Optional: Custom monaco path fragment
+      // Automatically detected (works with pnpm and monorepos)
+      // monacoPath: 'monaco-editor/esm'
+    })
   ]
 });
 ```
@@ -70,35 +116,47 @@ export default defineConfig({
 
 Call `init` or `initAsync` **before** importing `monaco-editor` or creating any editor instances.
 
-```typescript
 import * as nlsAdapter from 'monaco-editor-nls-adapter';
 
-/**
- * Option 1: Synchronous (Standard)
- * Recommended for small clusters or if you don't mind the initial bundle size.
- */
+// 1. Synchronous (Standard)
 nlsAdapter.init('zh-hans');
 
-/**
- * Option 2: Asynchronous (Performance Optimization)
- * Leverages Webpack/Vite dynamic imports for code splitting.
- */
+// 2. Asynchronous (Code Splitting)
 // await nlsAdapter.initAsync('zh-hans');
 
-/**
- * Option 3: Automatic Browser Detection
- */
-// nlsAdapter.init(); // Sync
-// await nlsAdapter.initAsync(); // Async
+// 3. Get current locale
+console.log(nlsAdapter.getCurrentLocale()); // 'zh-hans'
 
-import * as monaco from 'monaco-editor';
-
-monaco.editor.create(document.getElementById('container'), {
-  value: 'console.log("Hello Localization!");',
-  language: 'javascript'
+// 4. Custom Messages (Override built-in locales)
+/*
+nlsAdapter.setMessages({
+  'vs/editor/common/editorContextKeys': {
+    'editor.action.clipboardCopyAction': 'Copy (Custom)'
+  }
 });
+*/
+
+import * as monaco from 'monaco-editor';
+// ... create editor as usual
 ```
 
+### Framework Integration (React / Vue)
+
+This package works seamlessly with major frameworks. Special note for **React** (@monaco-editor/react): Make sure to use `loader.config({ monaco })` to disable CDN and map to your local, localized monaco instance.
+
+See: [Framework Integration Best Practices (Examples)](./examples/framework-integration.md)
+
+### API Reference
+
+| Function | Description |
+| --- | --- |
+| `init(locale?: string): boolean` | Synchronous initialization. Tries to detect browser language if omitted. Returns success status. |
+| `initAsync(locale?: string): Promise<boolean>` | Asynchronous initialization with dynamic imports. Returns success status. |
+| `getCurrentLocale(): string` | Returns the currently active locale code. Returns `custom` if set via `setMessages`. |
+| `setMessages(data: object)` | Manually inject translation data. Must follow Monaco's NLS structure. |
+| `vitePlugin(options?: object)` | Vite plugin function. |
+| `loader: string` | Absolute path to the Webpack loader. |
+
 ## 🗂 Supported Locales
 
 | Code | Language |

package/README_zh.md

@@ -14,9 +14,23 @@
 - **自托管语言包**: 无需依赖外部 CDN；所有语言数据在本地打包。
 - **适配 Monaco 0.50.0+**: 完全兼容 Monaco Editor 最新的内部 NLS 调用签名。
 - **性能优化 (懒加载)**: 通过 Webpack/Vite 的动态导入实现按需分包加载。
+- **SourceMap 支持**: 基于 `magic-string` 实现转换后的精准还原，调试无忧。
 - **TypeScript 支持**: 完善的类型定义，为开发提供极佳的智能感知。
-- **智能语言识别**: 支持自动识别浏览器语言或手动切换。
+- **灵活的 API**: 提供 `getCurrentLocale` 和 `setMessages` (自定义数据) 等高级接口。
 - **跨构建工具支持**: 原生支持 **Webpack** (Loader) 以及 **Vite/Rollup** (Plugin)。
+- **智能路径探测**: 自动识别 `pnpm` 和 monorepo 路径，**零配置**即可使用。
+- **轻量化**: 移除了冗余测试文件，发布包体积进一步精简。
+
+## 📦 支持的框架
+
+本适配器与主流前端框架均可完美兼容：
+
+- **Vue 2**: 完美适配 Vue CLI 和 Webpack 项目。
+- **Vue 3**: 深度支持 Vite 和 Vue CLI 配置。
+- **React**: 适配原生 React 应用及 `@monaco-editor/react` (支持禁用 CDN)。
+- **Angular**: 支持 Angular CLI (Webpack/Vite) 构建环境。
+- **SSR 框架**: 兼容 **Next.js** 和 **Nuxt** 等服务端渲染环境。
+- **通用**: 理论上支持任何基于 **Webpack**、**Vite** 或 **Rollup** 构建的 web 项目。
 
 ## 🚀 安装
 
@@ -31,16 +45,23 @@ npm install monaco-editor-nls-adapter
 在 `webpack.config.js` 中，添加此适配器的 loader 来处理 Monaco Editor 的 ESM 源码。
 
 ```javascript
+const { loader } = require('monaco-editor-nls-adapter');
+
 module.exports = {
   module: {
     rules: [
       {
         test: /\.js$/,
-        // 重要：仅处理 monaco-editor 的 esm 目录，避免对业务代码产生副作用
-        include: /node_modules[\\/]monaco-editor[\\/]esm/,
+        // 重要：仅处理 monaco-editor 的 esm 目录
+        include: /monaco-editor[\\/]esm/,
         use: [
           {
-            loader: 'monaco-editor-nls-adapter/loader'
+            loader: loader,
+            options: {
+              // 可选：自定义 monaco 路径片段
+              // 插件会自动探测 node_modules 下的 monaco-editor/esm，通常无需配置
+              // monacoPath: 'monaco-editor/esm'
+            }
           }
         ]
       }
@@ -49,17 +70,42 @@ module.exports = {
 }
 ```
 
-### 2. Vite / Rollup (Plugin)
+### 2. Vue CLI (`vue.config.js`)
+
+对于使用 Vue CLI 的项目，建议使用 `chainWebpack` 进行配置：
+
+```javascript
+const { loader } = require('monaco-editor-nls-adapter');
+
+module.exports = {
+  chainWebpack: config => {
+    config.module
+      .rule('monaco-editor-nls')
+      .test(/\.js$/)
+      .include.add(/monaco-editor[\\/]esm/)
+      .end()
+      .use('nls-loader')
+      .loader(loader)
+      .end();
+  }
+};
+```
+
+### 3. Vite / Rollup (Plugin)
 
 在 `vite.config.js` 中，添加此插件：
 
 ```javascript
 import { defineConfig } from 'vite';
-import monacoNlsPlugin from 'monaco-editor-nls-adapter/vite-plugin';
+import { vitePlugin } from 'monaco-editor-nls-adapter';
 
 export default defineConfig({
   plugins: [
-    monacoNlsPlugin()
+    vitePlugin({
+      // 可选：自定义 monaco 路径片段
+      // 插件会自动探测物理路径（支持 pnpm），通常无需配置
+      // monacoPath: 'monaco-editor/esm'
+    })
   ]
 });
 ```
@@ -70,35 +116,47 @@ export default defineConfig({
 
 在导入 `monaco-editor` 或创建任何实例**之前**，先调用 `init` 或 `initAsync`。
 
-```typescript
 import * as nlsAdapter from 'monaco-editor-nls-adapter';
 
-/**
- * 方式 1: 同步初始化 (标准用法)
- * 适用于语言包体量较小，或不介意首屏全量包含翻译数据的场景。
- */
+// 1. 同步初始化 (标准用法)
 nlsAdapter.init('zh-hans');
 
-/**
- * 方式 2: 异步初始化 (性能优化推荐)
- * 利用 Webpack/Vite 的动态 import 实现分包，仅加载当前所需语言。
- */
+// 2. 异步初始化 (分包懒加载)
 // await nlsAdapter.initAsync('zh-hans');
 
-/**
- * 方式 3: 自动识别浏览器语言
- */
-// nlsAdapter.init(); // 同步
-// await nlsAdapter.initAsync(); // 异步
+// 3. 获取当前语言
+console.log(nlsAdapter.getCurrentLocale()); // 'zh-hans'
 
-import * as monaco from 'monaco-editor';
-
-monaco.editor.create(document.getElementById('container'), {
-  value: 'console.log("Hello Localization!");',
-  language: 'javascript'
+// 4. 使用自定义翻译数据 (不使用内置语言包)
+/*
+nlsAdapter.setMessages({
+  'vs/editor/common/editorContextKeys': {
+    'editor.action.clipboardCopyAction': '复制 (Custom)'
+  }
 });
+*/
+
+import * as monaco from 'monaco-editor';
+// ... 之后正常创建编辑器
 ```
 
+### 框架集成 (React / Vue)
+
+本项目与主流框架完美配合。特别注意：若使用 **React** (@monaco-editor/react)，请务必通过 `loader.config({ monaco })` 禁用 CDN 并映射到本地实例。
+
+详细的框架集成指南请参考：[框架集成最佳实践 (Examples)](./examples/framework-integration.md)
+
+### API 详述
+
+| 函数 | 说明 |
+| --- | --- |
+| `init(locale?: string): boolean` | 同步初始化。如果不传参数，尝试探测浏览器语言。返回是否加载成功。 |
+| `initAsync(locale?: string): Promise<boolean>` | 异步初始化。利用动态 import 拆分语言包。返回是否加载成功。 |
+| `getCurrentLocale(): string` | 获取当前已生效的语言代码。如果是自定义数据，返回 `custom`。 |
+| `setMessages(data: object)` | 手动注入翻译字典。格式需符合 Monaco 的 NLS 结构。 |
+| `vitePlugin(options?: object)` | Vite 插件函数。 |
+| `loader: string` | Webpack Loader 的绝对路径。 |
+
 ## 🗂 支持的语言列表
 
 | 语言代码 | 对应语言 |

package/index.d.ts

@@ -1,16 +1,5 @@
-export interface NLSProxy {
-  localize(path: string, data: any, defaultMessage: string, ...args: any[]): string;
-  localize2(path: string, data: any, defaultMessage: string, ...args: any[]): { value: string; original: string };
-  setLocaleData(data: Record<string, any>): void;
-  getConfiguredDefaultLocale(): string | undefined;
-  loadMessageBundle(file: string): (path: string, data: any, defaultMessage: string, ...args: any[]) => string;
-  config(opt: any): (file: string) => any;
-  create(key: string, data: any): {
-    localize: (idx: any, defaultValue: string, ...args: any[]) => string;
-    localize2: (idx: any, defaultValue: string, ...args: any[]) => { value: string; original: string };
-    getConfiguredDefaultLocale: () => string | undefined;
-  };
-}
+import { NLSProxy } from './proxy';
+import monacoNlsPlugin from './vite-plugin';
 
 /**
  * 支持的语言代码类型
@@ -21,18 +10,47 @@ export type LocaleCode =
 
 /**
  * 初始化 Monaco Editor 的语言包
- * @param locale 语言代码，如 'zh-hans'。如果不传，将尝试检测浏览器语言。
+ * @param locale 语言代码，如 'zh-hans'
+ * @param force 是否强制重新初始化
+ * @returns 是否加载成功
  */
-export function init(locale?: LocaleCode | string): void;
+export function init(locale?: LocaleCode | string, force?: boolean): boolean;
 
 /**
  * 异步初始化 Monaco Editor 的语言包
- * 使用动态 import()，支持 Webpack 分包和懒加载。
  * @param locale 语言代码
+ * @param force 是否强制重新加载
+ * @returns 是否加载成功
  */
-export function initAsync(locale?: LocaleCode | string): Promise<void>;
+export function initAsync(locale?: LocaleCode | string, force?: boolean): Promise<boolean>;
 
 /**
- * NLS 代理对象，由 loader 注入到 Monaco 源码中
+ * 获取当前已生效的语言代码
+ */
+export function getCurrentLocale(): string;
+
+/**
+ * 手动设置翻译数据字典
+ * @param messages 符合 Monaco NLS 格式的 JSON 对象
+ */
+export function setMessages(messages: Record<string, any>): void;
+
+/**
+ * NLS 代理对象声明
  */
 export const proxy: NLSProxy;
+
+/**
+ * Vite 插件导出
+ */
+export const vitePlugin: typeof monacoNlsPlugin;
+
+/**
+ * Webpack Loader 绝对路径导出 (用于 webpack.config.js)
+ */
+export const loader: string;
+
+// 重新导出子模块中的类型，方便从主模块引用
+export { NLSProxy } from './proxy';
+export { PluginOptions } from './vite-plugin';
+export { transform } from './transform';

package/index.js

@@ -11,17 +11,39 @@ const LOCALE_MAP = {
   'zh-hk': 'zh-hant',
   'en-us': 'en',
   'en-gb': 'en',
-  'en': 'en'
+  'en': 'en',
+  'ja-jp': 'ja',
+  'ja': 'ja',
+  'ko-kr': 'ko',
+  'ko': 'ko',
+  'de-de': 'de',
+  'de': 'de',
+  'fr-fr': 'fr',
+  'fr': 'fr',
+  'es-es': 'es',
+  'es': 'es',
+  'it-it': 'it',
+  'it': 'it',
+  'ru-ru': 'ru',
+  'ru': 'ru',
+  'pt-br': 'pt-br'
 }
 
+let CURRENT_LOCALE = ''
+let IS_LOADING = false
+
 /**
  * 使用指定的语言代码初始化 Monaco Editor 的本地化。
  * 此方法会从本地 /locales 目录加载 JSON 数据。
  * @param {string} locale 语言代码 (例如 'zh-hans', 'ja', 'ko')。如果不传，将尝试检测浏览器语言。
+ * @param {boolean} force 是否强制重新初始化，即使语言相同。
  */
-function init(locale) {
+function init(locale, force = false) {
+  // SSR 环境安全检查
+  const isBrowser = typeof window !== 'undefined' && typeof navigator !== 'undefined'
+
   // 如果没有传递 locale，尝试从浏览器环境获取
-  if (!locale && typeof navigator !== 'undefined') {
+  if (!locale && isBrowser) {
     locale = navigator.language || navigator.userLanguage
   }
 
@@ -31,43 +53,90 @@ function init(locale) {
     targetLocale = LOCALE_MAP[targetLocale]
   }
 
+  // 幂等检查：如果已经加载过该语言且非强制，则直接返回
+  if (CURRENT_LOCALE === targetLocale && !force) {
+    return true
+  }
+
   try {
     const data = require(`./locales/${targetLocale}.json`)
     proxy.setLocaleData(data)
+    CURRENT_LOCALE = targetLocale
+    return true
   } catch (e) {
-    console.error(`[monaco-editor-nls-adapter] 无法加载本地语言包: ${targetLocale}。回退到默认设置。`, e)
+    if (isBrowser) {
+      console.warn(`[monaco-editor-nls-adapter] 无法加载本地语言包: ${targetLocale}。回退到默认设置。`, e)
+    }
+    return false
   }
 }
 
 /**
  * 异步初始化 Monaco Editor 的本地化。
- * 使用动态 import()，允许 Webpack 将语言包拆分为独立的 chunk，实现按需加载。
- * @param {string} locale 语言代码。如果不传，将尝试检测浏览器语言。
- * @returns {Promise<void>}
+ * 使用动态 import()，允许 Webpack 将语言包拆分为独立的 chunk。
+ * @param {string} locale 语言代码。
+ * @param {boolean} force 是否强制重新加载。
+ * @returns {Promise<boolean>}
  */
-async function initAsync(locale) {
-  // 如果没有传递 locale，尝试从浏览器环境获取
-  if (!locale && typeof navigator !== 'undefined') {
+async function initAsync(locale, force = false) {
+  const isBrowser = typeof window !== 'undefined' && typeof navigator !== 'undefined'
+
+  if (!locale && isBrowser) {
     locale = navigator.language || navigator.userLanguage
   }
 
-  // 小写化并查找映射
   let targetLocale = (locale || 'zh-hans').toLowerCase()
   if (LOCALE_MAP[targetLocale]) {
     targetLocale = LOCALE_MAP[targetLocale]
   }
 
+  if (CURRENT_LOCALE === targetLocale && !force) {
+    return true
+  }
+
+  if (IS_LOADING && !force) return false
+  IS_LOADING = true
+
   try {
-    // 使用动态 import 实现懒加载
-    const module = await import(`./locales/${targetLocale}.json`)
+    // 使用动态 import 实现懒加载，并添加 Webpack 魔术注释以优化分包命名
+    const module = await import(/* webpackChunkName: "nls-[request]" */ `./locales/${targetLocale}.json`)
     proxy.setLocaleData(module.default || module)
+    CURRENT_LOCALE = targetLocale
+    return true
   } catch (e) {
-    console.error(`[monaco-editor-nls-adapter] 无法异步加载语言包: ${targetLocale}。`, e)
+    if (isBrowser) {
+      console.warn(`[monaco-editor-nls-adapter] 无法异步加载语言包: ${targetLocale}。`, e)
+    }
+    return false
+  } finally {
+    IS_LOADING = false
   }
 }
 
+/**
+ * 获取当前已生效的语言代码
+ */
+function getCurrentLocale() {
+  return CURRENT_LOCALE
+}
+
+/**
+ * 手动设置翻译数据字典
+ * @param {Object} data 符合 Monaco NLS 格式的 JSON 对象
+ */
+function setMessages(data) {
+  proxy.setLocaleData(data)
+  CURRENT_LOCALE = 'custom'
+}
+
 module.exports = {
   init: init,
   initAsync: initAsync,
-  proxy: proxy
+  getCurrentLocale: getCurrentLocale,
+  setMessages: setMessages,
+  setLocaleData: proxy.setLocaleData, // 向后兼容
+  proxy: proxy,
+  // 插件导出 (便于在 config 文件中使用)
+  vitePlugin: require('./vite-plugin'),
+  loader: __dirname + '/loader.js'
 }

package/loader.js

@@ -6,6 +6,20 @@ const { transform } = require('./transform')
 module.exports = function (source) {
   if (this.cacheable) this.cacheable()
   
+  // 获取 loader options (Webpack 5 推荐 this.getOptions)
+  const options = (typeof this.getOptions === 'function') ? this.getOptions() : this.query
+  
   // 使用共享的 transform 逻辑
-  return transform(source, this.resourcePath)
+  const result = transform(source, this.resourcePath, options || {})
+  
+  // 如果返回包含 SourceMap 的对象，则使用 this.callback 提示 Webpack
+  if (result && typeof result === 'object') {
+    if (this.callback) {
+      this.callback(null, result.code, result.map)
+      return
+    }
+    return result.code
+  }
+
+  return result
 }

package/package.json

@@ -1,9 +1,35 @@
 {
   "name": "monaco-editor-nls-adapter",
-  "version": "1.0.0",
+  "version": "2.0.0",
   "description": "Multi-language NLS adapter for Monaco Editor 0.50.0+ (Self-hosted)",
   "main": "index.js",
+  "module": "index.js",
   "types": "index.d.ts",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js",
+      "require": "./index.js"
+    },
+    "./proxy": {
+      "types": "./proxy.d.ts",
+      "require": "./proxy.js"
+    },
+    "./loader": {
+      "types": "./loader.d.ts",
+      "require": "./loader.js"
+    },
+    "./vite-plugin": {
+      "types": "./vite-plugin.d.ts",
+      "require": "./vite-plugin.js"
+    },
+    "./transform": {
+      "types": "./transform.d.ts",
+      "require": "./transform.js"
+    },
+    "./locales/*": "./locales/*"
+  },
   "files": [
     "index.js",
     "index.d.ts",
@@ -11,7 +37,7 @@
     "proxy.js",
     "transform.js",
     "vite-plugin.js",
-    "locales/*.json",
+    "locales/",
     "README.md",
     "README_zh.md"
   ],
@@ -37,5 +63,7 @@
   "peerDependencies": {
     "monaco-editor": ">= 0.50.0"
   },
-  "dependencies": {}
+  "dependencies": {
+    "magic-string": "^0.30.0"
+  }
 }

package/proxy.js

@@ -10,19 +10,18 @@ function _format(message, args) {
     return message
   }
   return String(message).replace(/\{(\d+)\}/g, function (match, rest) {
-    const index = rest[0]
+    const index = parseInt(rest, 10)
     return typeof args[index] !== 'undefined' ? args[index] : match
   })
 }
 
 function localize(path, data, defaultMessage, ...args) {
-  // 针对 Monaco 0.50.0 签名的参数修正：
-  // 1. 当通过 loader 调用时，path 是被注入的。
-  // 2. 当通过 create 调用时，path 也会被显式作为第一个参数传入。
   const key = (data && typeof data === 'object') ? data.key : data
   const localeData = CURRENT_LOCALE_DATA || {}
   
-  let message = (localeData[path] || {})[key]
+  const fileData = localeData[path] || {}
+  let message = fileData[key]
+  
   // 强化回退逻辑：如果翻译为空或未找到，则回退到默认消息
   if (message === undefined || message === null || message === '') {
     message = defaultMessage