monaco-editor-nls-adapter 2.1.0 → 2.2.0

package/README.md

@@ -21,6 +21,7 @@ Multi-language NLS adapter for Monaco Editor 0.50.0+ (Self-hosted). Bridge the g
 - **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.
+- **Resilient**: Global singleton state for micro-frontends and nested dependency environments.
 - **Ultra-lightweight**: Redundant test files removed for even faster installation.
 
 ## 📦 Supported Frameworks
@@ -112,14 +113,34 @@ export default defineConfig({
 });
 ```
 
-### 4. Bundle Optimization (Optional)
+### 4. On-demand Packaging (Recommended)
 
-If you are concerned about bundle size or the "Stat size" reported by bundle analyzers, you can use the **Lite Version**. 
+By default, the adapter's entry point contains dynamic references that may cause bundlers to include all available locales (~13MB total stat size).
 
-The default entry point uses dynamic `require`/`import` with template strings, which may cause build tools (Webpack/Vite) to scan and include all available locales or report a large "original size." The Lite version eliminates this by providing only the core logic.
+You can use the `languages` option to specify **only** the languages you need. This is easier than the Lite version because it retains the full automation of `init()` and `initAsync()` while significantly reducing the bundle size.
 
+#### Vite Configuration (`vite.config.js`)
 ```javascript
-// 1. Import from /lite
+vitePlugin({
+  languages: ['zh-hans', 'en'] // Only include Simplified Chinese and English
+})
+```
+
+#### Webpack Configuration (`webpack.config.js`)
+```javascript
+{
+  loader: loader,
+  options: {
+    languages: ['zh-hans', 'ja'] // Only include Simplified Chinese and Japanese
+  }
+}
+```
+
+> [!TIP]
+> **Extreme Optimization (Lite Version)**: If you want zero code injection, you can bypass the main entry point entirely and use the Lite version. See below:
+
+```javascript
+// 1. Import from /lite (No dynamic loading logic included)
 import { setMessages } from 'monaco-editor-nls-adapter/lite';
 
 // 2. Manually import ONLY the language you need
@@ -127,9 +148,6 @@ import zhHans from 'monaco-editor-nls-adapter/locales/zh-hans.json';
 
 // 3. Initialize BEFORE monaco-editor loads
 setMessages(zhHans, 'zh-hans');
-
-// 4. Import monaco-editor as usual
-import * as monaco from 'monaco-editor';
 ```
 
 ## 📖 Usage
@@ -174,8 +192,11 @@ See: [Framework Integration Best Practices (Examples)](./examples/framework-inte
 | --- | --- |
 | `init(locale?: string): boolean` | Synchronous initialization. **Note**: This will trigger the bundler to scan all locales in the directory. |
 | `initAsync(locale?: string): Promise<boolean>` | Asynchronous initialization with dynamic imports. |
-| `getCurrentLocale(): string` | Returns the currently active locale code. Returns `custom` if set via `setMessages`. |
+| `getLocaleName(): string` | [New] Returns the currently active locale code name (e.g., 'zh-hans'). |
+| `getLocaleData(): object` | [New] Returns the current raw translation dictionary object. |
+| `getCurrentLocale(): string` | Returns the currently active locale (alias for `getLocaleName`). |
 | `setMessages(data: object, locale?: string)` | Manually inject translations. Recommended with `./lite` for minimum footprint. |
+| `setLocaleData(data: object, locale?: string)` | Alias to `setMessages`. Sets the locale data into the proxy directly. |
 | `vitePlugin(options?: object)` | Vite plugin function. |
 | `loader: string` | Absolute path to the Webpack loader. |
 

package/README_zh.md

@@ -22,6 +22,7 @@
 - **灵活的 API**: 提供 `getCurrentLocale` 和 `setMessages` (自定义数据) 等高级接口。
 - **跨构建工具支持**: 原生支持 **Webpack** (Loader) 以及 **Vite/Rollup** (Plugin)。
 - **智能路径探测**: 自动识别 `pnpm` 和 monorepo 路径，**零配置**即可使用。
+- **环境鲁棒性**: 内置全局单例状态管理，支持微前端和多版本依赖嵌套场景。
 - **轻量化**: 移除了冗余测试文件，发布包体积进一步精简。
 
 ## 📦 支持的框架
@@ -113,24 +114,41 @@ export default defineConfig({
 });
 ```
 
-### 4. 极致体积优化 (可选)
+### 4. 语言包按需打包 (推荐优化方案)
 
-如果你对打包后的 JS 文件体积非常敏感，或者 bundle analyzer 显示 `monaco-editor-nls-adapter` 的 `Stat size` 过大（这是由于默认入口包含所有语言包的动态引用导致的），可以使用 **Lite 版本**。
+默认情况下，由于 `index.js` 包含动态引用，构建工具可能会扫描并打包 `./locales` 目录下的所有语言文件（Stat size 较大）。
 
-Lite 版本不具备内置的语言包发现逻辑，需要你手动导入所需的语言 JSON。这样构建工具（Webpack/Vite）只会打包你真正使用的那门语言，而不会扫描整个 `./locales` 目录。
+你可以通过 `languages` 配置项来指定**仅打包**需要的语言。这比手动使用 Lite 版本更方便，因为它依然保留了 `init()` 和 `initAsync()` 的全自动加载能力，同时大幅减少产物体积。
 
+#### Vite 配置 (`vite.config.js`)
 ```javascript
-// 1. 从 /lite 入口导入
+vitePlugin({
+  languages: ['zh-hans', 'en'] // 最终产物仅包含中、英语言包
+})
+```
+
+#### Webpack 配置 (`webpack.config.js`)
+```javascript
+{
+  loader: loader,
+  options: {
+    languages: ['zh-hans', 'ja'] // 最终产物仅包含中、日语言包
+  }
+}
+```
+
+> [!TIP]
+> **极致优化 (Lite 版本)**: 如果你连按需打包的代码注入也不想要，可以完全绕过 `index.js`，手动导入 JSON 并调用 `setMessages`。详见下文：
+
+```javascript
+// 1. 从 /lite 入口导入 (不含任何动态加载逻辑)
 import { setMessages } from 'monaco-editor-nls-adapter/lite';
 
-// 2. 手动导入特定的语言 JSON (由你自己决定包含哪门语言)
+// 2. 手动导入特定的语言 JSON
 import zhHans from 'monaco-editor-nls-adapter/locales/zh-hans.json';
 
 // 3. 初始化 (必须要在 monaco 加载前运行)
 setMessages(zhHans, 'zh-hans');
-
-// 4. 正常使用 monaco-editor
-import * as monaco from 'monaco-editor';
 ```
 
 ## 📖 使用指南
@@ -175,8 +193,11 @@ import * as monaco from 'monaco-editor';
 | --- | --- |
 | `init(locale?: string): boolean` | 同步初始化。如果不传参数，尝试探测浏览器语言。注意：此方法会导致构建工具引入全量语言包（或触发全量扫描）。 |
 | `initAsync(locale?: string): Promise<boolean>` | 异步初始化。利用动态 import 拆分语言包。 |
-| `getCurrentLocale(): string` | 获取当前已生效的语言代码。如果是自定义数据，返回 `custom`。 |
+| `getLocaleName(): string` | [新] 获取当前生效的语言代码名称（如 'zh-hans'）。 |
+| `getLocaleData(): object` | [新] 获取当前已加载的完整本地化字典对象。 |
+| `getCurrentLocale(): string` | 获取当前已生效的语言代码（`getLocaleName` 的存量别名）。 |
 | `setMessages(data: object, locale?: string)` | 手动注入翻译字典。建议配合 `./lite` 入口使用以优化体积。 |
+| `setLocaleData(data: object, locale?: string)` | 同 `setMessages`，直接将数据注入代理层。 |
 | `vitePlugin(options?: object)` | Vite 插件函数。 |
 | `loader: string` | Webpack Loader 的绝对路径。 |
 

package/index.d.ts

@@ -2,61 +2,80 @@ import { NLSProxy } from './proxy';
 import monacoNlsPlugin from './vite-plugin';
 
 /**
- * 支持的语言代码类型
+ * 预设的支持语言代码类型 (也可传递任意字符串)
+ * Preset of supported locale codes (any string may be used).
  */
 export type LocaleCode = 
-  | 'zh-hans' | 'zh-cn' | 'zh-hant' | 'zh-tw'
+  | 'zh-hans' | 'zh-cn' | 'zh-hant' | 'zh-tw' | 'zh-hk'
   | 'en' | 'ja' | 'ko' | 'de' | 'fr' | 'es' | 'it' | 'ru' | 'pl' | 'tr' | 'cs' | 'pt-br';
 
 /**
- * 初始化 Monaco Editor 的语言包
- * @param locale 语言代码，如 'zh-hans'
- * @param force 是否强制重新初始化
- * @returns 是否加载成功
+ * [全量入口] 使用指定的语言代码初始化 Monaco Editor 的本地化。
+ * 注意：由于包含动态 require 逻辑，在 Webpack/Vite 环境下可能会导致扫描并打包全量语言 JSON。
+ * [Full Entry] Initialize Monaco Editor localization with a specific locale.
+ * WARNING: Uses dynamic require, which may bundle all locales in development/production.
+ * 
+ * @param locale 语言代码 (如 'zh-hans') / Locale code identifier.
+ * @param force 是否强制重新初始化 / Force re-initialization.
+ * @returns 是否加载成功 / Success status.
  */
 export function init(locale?: LocaleCode | string, force?: boolean): boolean;
 
 /**
- * 异步初始化 Monaco Editor 的语言包
- * @param locale 语言代码
- * @param force 是否强制重新加载
- * @returns 是否加载成功
+ * [全量入口] 异步初始化 Monaco Editor 的本地化。
+ * 使用动态 import 拆分语言包，有助于减小主包体积。
+ * [Full Entry] Asynchronously initialize Monaco localization.
+ * Uses dynamic import for chunk splitting.
+ * 
+ * @param locale 语言代码 / Locale code.
+ * @param force 是否强制加载 / Force re-load.
+ * @returns 是否加载成功 / Success status.
  */
 export function initAsync(locale?: LocaleCode | string, force?: boolean): Promise<boolean>;
 
 /**
- * 获取当前已生效的语言代码名称
+ * 获取当前已生效的语言代码名称 / Get the current active locale name.
  */
 export function getLocaleName(): string;
 
 /**
- * 获取当前加载的原始翻译数据
+ * 获取当前已生效的语言代码名称 (同 getLocaleName) / Get current locale (alias).
+ */
+export function getCurrentLocale(): string;
+
+/**
+ * 获取当前加载的原始翻译数据字典 / Get current raw translation data.
  */
 export function getLocaleData(): Record<string, any> | null;
 
 /**
- * 手动设置翻译数据字典
- * @param messages 符合 Monaco NLS 格式的 JSON 对象
- * @param locale 语言代码 (可选标识符)
+ * 手动设置翻译数据字典 / Set current translation messages manually.
+ * @param messages 符合 Monaco NLS 格式的 JSON 对象 / Dictionary following Monaco NLS format.
+ * @param locale 语言代码标识符 (可选) / Locale code identifier.
  */
 export function setMessages(messages: Record<string, any>, locale?: string): void;
 
 /**
- * NLS 代理对象声明
+ * 设置当前的本地化字典数据到代理中 / Set locale data into the proxy directly.
+ */
+export function setLocaleData(data: Record<string, any>, locale?: string): void;
+
+/**
+ * NLS 代理对象声明 / The NLS proxy instance.
  */
 export const proxy: NLSProxy;
 
 /**
- * Vite 插件导出
+ * Vite 插件导出 / Vite plugin for build-time transformation.
  */
 export const vitePlugin: typeof monacoNlsPlugin;
 
 /**
- * Webpack Loader 绝对路径导出 (用于 webpack.config.js)
+ * Webpack Loader 导出 (用于 webpack.config.js) / Webpack loader path.
  */
 export const loader: string;
 
-// 重新导出子模块中的类型，方便从主模块引用
+// 重新导出子模块中的类型以便全局引用
 export { NLSProxy } from './proxy';
 export { PluginOptions } from './vite-plugin';
 export { transform } from './transform';

package/lite.js

@@ -1,12 +1,26 @@
 const proxy = require('./proxy')
 
 /**
- * 获取当前已生效的语言代码
+ * 获取当前已生效的语言代码名称 (向后兼容)
  */
 function getCurrentLocale() {
   return proxy.getLocaleName()
 }
 
+/**
+ * 获取当前已生效的语言名称
+ */
+function getLocaleName() {
+  return proxy.getLocaleName()
+}
+
+/**
+ * 获取当前加载的原始翻译数据
+ */
+function getLocaleData() {
+  return proxy.getLocaleData()
+}
+
 /**
  * 手动设置翻译数据字典
  * @param {Object} data 符合 Monaco NLS 格式的 JSON 对象
@@ -17,10 +31,12 @@ function setMessages(data, locale = 'custom') {
 }
 
 module.exports = {
-  getCurrentLocale: getCurrentLocale,
-  setMessages: setMessages,
+  getCurrentLocale,
+  getLocaleName,
+  getLocaleData,
+  setMessages,
   setLocaleData: proxy.setLocaleData,
-  proxy: proxy,
+  proxy,
   // 插件导出 (仍保留，以便用户可以从 lite 引用所有工具)
   vitePlugin: require('./vite-plugin'),
   loader: __dirname + '/loader.js'

package/loader.js

@@ -1,11 +1,16 @@
 const { transform } = require('./transform')
+const { generateLocalesCode } = require('./codegen')
 
 /**
  * Webpack Loader for Monaco Editor NLS Adapter
  */
 module.exports = function (source) {
-  // 极致性能优化：第一层极速过滤
-  if (!this.resourcePath.endsWith('.js') || this.resourcePath.indexOf('monaco-editor') === -1) {
+  const resourcePath = this.resourcePath.replace(/\\/g, '/')
+  const isAdapter = resourcePath.endsWith('monaco-editor-nls-adapter/index.js') || resourcePath.endsWith('monaco-editor-nls-adapter/index.ts')
+  const isMonaco = resourcePath.indexOf('monaco-editor') !== -1
+
+  // 1. 第一层过滤：仅处理 monaco-editor 或 适配器自身入口
+  if (!isAdapter && !isMonaco) {
     return source
   }
 
@@ -13,18 +18,41 @@ module.exports = function (source) {
   
   // 获取 loader options
   const options = (typeof this.getOptions === 'function') ? this.getOptions() : this.query
-  
-  // 使用共享的 transform 逻辑
-  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
+  const languages = (options && Array.isArray(options.languages)) ? options.languages : null
+
+  // 2. 处理适配器自身的 index.js (按需打包语言包)
+  if (isAdapter && languages) {
+    let newCode = source
+    
+    // 替换同步 require
+    const syncCode = generateLocalesCode(languages, false)
+    if (syncCode) {
+      newCode = newCode.replace(/require\(`\.\/locales\/\$\{targetLocale\}\.json`\)/g, syncCode)
+    }
+
+    // 替换异步 import
+    const asyncCode = generateLocalesCode(languages, true)
+    if (asyncCode) {
+      newCode = newCode.replace(/import\(.*?\`\.\/locales\/\$\{targetLocale\}\.json\`\)/g, asyncCode)
+    }
+
+    return newCode
+  }
+
+  // 3. 处理 Monaco Editor 源代码 (注入本地化逻辑)
+  if (isMonaco) {
+    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.code
+    return result
   }
 
-  return result
+  return source
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "monaco-editor-nls-adapter",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "Multi-language NLS adapter for Monaco Editor 0.50.0+ (Self-hosted)",
   "main": "index.js",
   "module": "index.js",

package/proxy.js

@@ -3,9 +3,12 @@
  * 此文件通过注入 path 参数，替代了对原本 'monaco-editor-nls/vscode-nls' 的内部依赖方式。
  */
 
-// 状态变量，记录当前的语言数据和代码
-let CURRENT_LOCALE_DATA = null
-let CURRENT_LOCALE_NAME = ''
+// 使用全局对象存储状态，确保在多实例或多版本共存时（如多版本依赖嵌套）状态依然同步
+const globalObj = typeof globalThis !== 'undefined' ? globalThis : (typeof window !== 'undefined' ? window : global)
+globalObj.__MONACO_NLS_ADAPTER_STATE__ = globalObj.__MONACO_NLS_ADAPTER_STATE__ || { data: null, name: '' }
+
+// 辅助访问器
+const getState = () => globalObj.__MONACO_NLS_ADAPTER_STATE__
 
 // 提前编译正则表达式以提升运行时性能
 const FORMAT_REGEX = /\{(\d+)\}/g
@@ -34,9 +37,10 @@ function _format(message, args) {
  */
 function localize(path, data, defaultMessage, ...args) {
   const key = (data && typeof data === 'object') ? data.key : data
+  const state = getState()
   
   // 优化点：使用可选链或短路评估快速定位翻译
-  const fileData = (CURRENT_LOCALE_DATA && CURRENT_LOCALE_DATA[path])
+  const fileData = (state.data && state.data[path])
   const message = fileData ? fileData[key] : undefined
   
   // 强化回退逻辑：如果翻译为空或未找到，则回退到默认消息
@@ -60,22 +64,23 @@ function localize2(path, data, defaultMessage, ...args) {
  * @param {string} locale 语言代码
  */
 function setLocaleData(data, locale = 'custom') {
-  CURRENT_LOCALE_DATA = data
-  CURRENT_LOCALE_NAME = locale
+  const state = getState()
+  state.data = data
+  state.name = locale
 }
 
 /**
  * 获取当前已加载的完整字典数据
  */
 function getLocaleData() {
-  return CURRENT_LOCALE_DATA
+  return getState().data
 }
 
 /**
  * 获取当前生效的语言名称
  */
 function getLocaleName() {
-  return CURRENT_LOCALE_NAME
+  return getState().name
 }
 
 // 以下为适配 monaco-editor 内部调用的兼容性 Shim 函数

package/transform.js

@@ -2,13 +2,13 @@ const MagicString = require('magic-string')
 
 let CACHED_MONACO_ROOT = null
 
+// 提前编译正则表达式以提升运行时性能
+const NLS_IMPORT_REGEX = /(import\s+.*?\s+from\s+['"])(.*?\/nls\.js)(['"])/g
+const NLS_REQUIRE_REGEX = /(require\(['"])(.*?\/nls\.js)(['"]\))/g
+const LOCALIZE_REGEX = /nls\.localize(\d?)\(/g
+
 /**
  * 转换 Monaco Editor 源代码以注入本地化路径
- * @param {string} source 源代码内容
- * @param {string} id 文件路径 (resourcePath 或 vite id)
- * @param {Object} options 配置项
- * @param {string} options.monacoPath 匹配 Monaco Editor 的路径片段，默认为 'monaco-editor/esm'
- * @returns {Object|string} 转换后的对象 { code, map } 或原始字符串
  */
 function transform(source, id, options = {}) {
   // 统一路径分隔符

package/vite-plugin.js

@@ -1,25 +1,50 @@
 const { transform } = require('./transform')
+const { generateLocalesCode } = require('./codegen')
 
 /**
  * Vite Plugin for Monaco Editor NLS Adapter
  * @param {Object} options 插件配置
  * @param {string} options.monacoPath 匹配 Monaco Editor ESM 路径的特征字符串，默认为 'monaco-editor/esm'
+ * @param {string[]} options.languages 需要包含的语言包列表 (如 ['zh-hans', 'en'])。不传则全量打包。
  */
 function monacoNlsPlugin(options = {}) {
   const monacoRoot = options.monacoPath || 'monaco-editor/esm'
-  
+  const languages = Array.isArray(options.languages) ? options.languages : null
+
   return {
     name: 'vite-plugin-monaco-nls-adapter',
     enforce: 'pre',
     transform(code, id) {
-      // 极致性能优化：第一层极速过滤，避免非目标文件的正则与替换开销
-      if (!id.endsWith('.js') || id.indexOf('monaco-editor') === -1) return
+      if (!id.endsWith('.js')) return
 
       // 统一路径格式
       const normalizedId = id.replace(/\\/g, '/')
-      
-      // 快速过滤非目标文件 (进一步细化)
-      if (normalizedId.includes(monacoRoot)) {
+
+      // 1. 处理适配器自身的 index.js (按需打包语言包)
+      if (languages && (normalizedId.endsWith('monaco-editor-nls-adapter/index.js') || normalizedId.endsWith('monaco-editor-nls-adapter/index.ts'))) {
+        let newCode = code
+        
+        // 替换同步 require
+        const syncCode = generateLocalesCode(languages, false)
+        if (syncCode) {
+          newCode = newCode.replace(/require\(`\.\/locales\/\$\{targetLocale\}\.json`\)/g, syncCode)
+        }
+
+        // 替换异步 import
+        const asyncCode = generateLocalesCode(languages, true)
+        if (asyncCode) {
+          // 注意：index.js 中的 import 是带注释的: import(/* webpackChunkName: "nls-[request]" */ `./locales/${targetLocale}.json`)
+          newCode = newCode.replace(/import\(.*?\`\.\/locales\/\$\{targetLocale\}\.json\`\)/g, asyncCode)
+        }
+
+        return {
+          code: newCode,
+          map: null // 对于这种简单的替换，暂不生成 sourcemap 以保持性能
+        }
+      }
+
+      // 2. 处理 Monaco Editor 源代码 (注入本地化逻辑)
+      if (normalizedId.indexOf('monaco-editor') !== -1 && normalizedId.includes(monacoRoot)) {
         const result = transform(code, id, options)
         
         // 如果 transform 返回的是对象 ({ code, map })，直接返回