monaco-editor-nls-adapter 2.1.0 → 2.1.1

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
@@ -174,8 +175,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 路径，**零配置**即可使用。
+- **环境鲁棒性**: 内置全局单例状态管理，支持微前端和多版本依赖嵌套场景。
 - **轻量化**: 移除了冗余测试文件，发布包体积进一步精简。
 
 ## 📦 支持的框架
@@ -175,8 +176,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "monaco-editor-nls-adapter",
-  "version": "2.1.0",
+  "version": "2.1.1",
   "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 = {}) {
   // 统一路径分隔符