monaco-editor-nls-adapter 2.0.0 → 2.1.1

package/README.md

@@ -13,12 +13,15 @@ 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.
+- **SourceMap Support**: Powered by `magic-string` for accurate source-to-bundle mapping.
+- **Ultra-Optimized (Mini & Lite)**:
+  - **JSON Minification**: All locale files are pre-minified, reducing the stat size by ~15%.
+  - **Slim/Lite Export**: Use `./lite` for a zero-bloat experience with no dynamic scanning.
 - **TypeScript Support**: First-class TS definitions for an excellent developer experience.
 - **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
@@ -110,6 +113,26 @@ export default defineConfig({
 });
 ```
 
+### 4. Bundle Optimization (Optional)
+
+If you are concerned about bundle size or the "Stat size" reported by bundle analyzers, you can use the **Lite Version**. 
+
+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.
+
+```javascript
+// 1. Import from /lite
+import { setMessages } from 'monaco-editor-nls-adapter/lite';
+
+// 2. Manually import ONLY the language you need
+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
 
 ### Initialization
@@ -150,10 +173,13 @@ See: [Framework Integration Best Practices (Examples)](./examples/framework-inte
 
 | 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. |
+| `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. |
+| `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

@@ -15,10 +15,14 @@
 - **适配 Monaco 0.50.0+**: 完全兼容 Monaco Editor 最新的内部 NLS 调用签名。
 - **性能优化 (懒加载)**: 通过 Webpack/Vite 的动态导入实现按需分包加载。
 - **SourceMap 支持**: 基于 `magic-string` 实现转换后的精准还原，调试无忧。
+- **极致优化 (Mini & Lite)**: 
+  - **内置 JSON 压缩**: 所有语言包均已移除空格，Stat size 减少约 15%。
+  - **Slim/Lite 导出**: 提供 `./lite` 入口，不包含动态加载逻辑，可实现 **0 冗余** 打包。
 - **TypeScript 支持**: 完善的类型定义，为开发提供极佳的智能感知。
 - **灵活的 API**: 提供 `getCurrentLocale` 和 `setMessages` (自定义数据) 等高级接口。
 - **跨构建工具支持**: 原生支持 **Webpack** (Loader) 以及 **Vite/Rollup** (Plugin)。
 - **智能路径探测**: 自动识别 `pnpm` 和 monorepo 路径，**零配置**即可使用。
+- **环境鲁棒性**: 内置全局单例状态管理，支持微前端和多版本依赖嵌套场景。
 - **轻量化**: 移除了冗余测试文件，发布包体积进一步精简。
 
 ## 📦 支持的框架
@@ -110,6 +114,26 @@ export default defineConfig({
 });
 ```
 
+### 4. 极致体积优化 (可选)
+
+如果你对打包后的 JS 文件体积非常敏感，或者 bundle analyzer 显示 `monaco-editor-nls-adapter` 的 `Stat size` 过大（这是由于默认入口包含所有语言包的动态引用导致的），可以使用 **Lite 版本**。
+
+Lite 版本不具备内置的语言包发现逻辑，需要你手动导入所需的语言 JSON。这样构建工具（Webpack/Vite）只会打包你真正使用的那门语言，而不会扫描整个 `./locales` 目录。
+
+```javascript
+// 1. 从 /lite 入口导入
+import { setMessages } from 'monaco-editor-nls-adapter/lite';
+
+// 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';
+```
+
 ## 📖 使用指南
 
 ### 初始化
@@ -150,10 +174,13 @@ import * as monaco from 'monaco-editor';
 
 | 函数 | 说明 |
 | --- | --- |
-| `init(locale?: string): boolean` | 同步初始化。如果不传参数，尝试探测浏览器语言。返回是否加载成功。 |
-| `initAsync(locale?: string): Promise<boolean>` | 异步初始化。利用动态 import 拆分语言包。返回是否加载成功。 |
-| `getCurrentLocale(): string` | 获取当前已生效的语言代码。如果是自定义数据，返回 `custom`。 |
-| `setMessages(data: object)` | 手动注入翻译字典。格式需符合 Monaco 的 NLS 结构。 |
+| `init(locale?: string): boolean` | 同步初始化。如果不传参数，尝试探测浏览器语言。注意：此方法会导致构建工具引入全量语言包（或触发全量扫描）。 |
+| `initAsync(locale?: string): Promise<boolean>` | 异步初始化。利用动态 import 拆分语言包。 |
+| `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,55 +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;
 
 /**
- * 手动设置翻译数据字典
- * @param messages 符合 Monaco NLS 格式的 JSON 对象
+ * 获取当前加载的原始翻译数据字典 / Get current raw translation data.
+ */
+export function getLocaleData(): Record<string, any> | null;
+
+/**
+ * 手动设置翻译数据字典 / 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;
+
+/**
+ * 设置当前的本地化字典数据到代理中 / Set locale data into the proxy directly.
  */
-export function setMessages(messages: Record<string, any>): void;
+export function setLocaleData(data: Record<string, any>, locale?: string): void;
 
 /**
- * NLS 代理对象声明
+ * 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/index.js

@@ -1,4 +1,5 @@
-const proxy = require('./proxy')
+const lite = require('./lite')
+const proxy = lite.proxy
 
 /**
  * 语言映射字典，用于将常见的浏览器语言代码还原为本包中支持的代码。
@@ -29,58 +30,49 @@ const LOCALE_MAP = {
   '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 是否强制重新初始化，即使语言相同。
+ * 此方法使用同步 require，会触发构建工具打包所有相关 JSON。
+ * @param {string} locale 语言代码
+ * @param {boolean} force 是否强制重新初始化
  */
 function init(locale, force = false) {
-  // SSR 环境安全检查
   const isBrowser = typeof window !== 'undefined' && typeof navigator !== 'undefined'
-
-  // 如果没有传递 locale，尝试从浏览器环境获取
   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) {
+  if (lite.getCurrentLocale() === targetLocale && !force) {
     return true
   }
 
   try {
+    // 这里的动态 require 是导致全量打包的主要原因，若需精简请改用 lite.setMessages()
     const data = require(`./locales/${targetLocale}.json`)
-    proxy.setLocaleData(data)
-    CURRENT_LOCALE = targetLocale
+    lite.setMessages(data, targetLocale)
     return true
   } catch (e) {
     if (isBrowser) {
-      console.warn(`[monaco-editor-nls-adapter] 无法加载本地语言包: ${targetLocale}。回退到默认设置。`, e)
+      console.warn(`[monaco-editor-nls-adapter] 无法加载本地语言包: ${targetLocale}`, e)
     }
     return false
   }
 }
 
 /**
- * 异步初始化 Monaco Editor 的本地化。
- * 使用动态 import()，允许 Webpack 将语言包拆分为独立的 chunk。
- * @param {string} locale 语言代码。
- * @param {boolean} force 是否强制重新加载。
- * @returns {Promise<boolean>}
+ * 异步加载语言包。
+ * @param {string} locale 语言代码
+ * @param {boolean} force 是否强制重新初始化
  */
 async function initAsync(locale, force = false) {
   const isBrowser = typeof window !== 'undefined' && typeof navigator !== 'undefined'
-
   if (!locale && isBrowser) {
     locale = navigator.language || navigator.userLanguage
   }
@@ -90,7 +82,7 @@ async function initAsync(locale, force = false) {
     targetLocale = LOCALE_MAP[targetLocale]
   }
 
-  if (CURRENT_LOCALE === targetLocale && !force) {
+  if (lite.getCurrentLocale() === targetLocale && !force) {
     return true
   }
 
@@ -98,14 +90,12 @@ async function initAsync(locale, force = false) {
   IS_LOADING = true
 
   try {
-    // 使用动态 import 实现懒加载，并添加 Webpack 魔术注释以优化分包命名
     const module = await import(/* webpackChunkName: "nls-[request]" */ `./locales/${targetLocale}.json`)
-    proxy.setLocaleData(module.default || module)
-    CURRENT_LOCALE = targetLocale
+    lite.setMessages(module.default || module, targetLocale)
     return true
   } catch (e) {
     if (isBrowser) {
-      console.warn(`[monaco-editor-nls-adapter] 无法异步加载语言包: ${targetLocale}。`, e)
+      console.warn(`[monaco-editor-nls-adapter] 无法异步加载语言包: ${targetLocale}`, e)
     }
     return false
   } finally {
@@ -113,30 +103,8 @@ async function initAsync(locale, force = false) {
   }
 }
 
-/**
- * 获取当前已生效的语言代码
- */
-function getCurrentLocale() {
-  return CURRENT_LOCALE
-}
-
-/**
- * 手动设置翻译数据字典
- * @param {Object} data 符合 Monaco NLS 格式的 JSON 对象
- */
-function setMessages(data) {
-  proxy.setLocaleData(data)
-  CURRENT_LOCALE = 'custom'
-}
-
 module.exports = {
+  ...lite,
   init: init,
-  initAsync: initAsync,
-  getCurrentLocale: getCurrentLocale,
-  setMessages: setMessages,
-  setLocaleData: proxy.setLocaleData, // 向后兼容
-  proxy: proxy,
-  // 插件导出 (便于在 config 文件中使用)
-  vitePlugin: require('./vite-plugin'),
-  loader: __dirname + '/loader.js'
+  initAsync: initAsync
 }

package/lite.js

@@ -0,0 +1,43 @@
+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 对象
+ * @param {string} locale 语言代码标识 (可选)
+ */
+function setMessages(data, locale = 'custom') {
+  proxy.setLocaleData(data, locale)
+}
+
+module.exports = {
+  getCurrentLocale,
+  getLocaleName,
+  getLocaleData,
+  setMessages,
+  setLocaleData: proxy.setLocaleData,
+  proxy,
+  // 插件导出 (仍保留，以便用户可以从 lite 引用所有工具)
+  vitePlugin: require('./vite-plugin'),
+  loader: __dirname + '/loader.js'
+}

package/loader.js

@@ -4,9 +4,14 @@ const { transform } = require('./transform')
  * Webpack Loader for Monaco Editor NLS Adapter
  */
 module.exports = function (source) {
+  // 极致性能优化：第一层极速过滤
+  if (!this.resourcePath.endsWith('.js') || this.resourcePath.indexOf('monaco-editor') === -1) {
+    return source
+  }
+
   if (this.cacheable) this.cacheable()
   
-  // 获取 loader options (Webpack 5 推荐 this.getOptions)
+  // 获取 loader options
   const options = (typeof this.getOptions === 'function') ? this.getOptions() : this.query
   
   // 使用共享的 transform 逻辑