monaco-editor-nls-adapter 2.2.2 → 2.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "monaco-editor-nls-adapter",
-  "version": "2.2.2",
+  "version": "2.3.0",
   "description": "Multi-language NLS adapter for Monaco Editor 0.50.0+ (Self-hosted)",
   "main": "index.js",
   "module": "index.js",
@@ -13,6 +13,7 @@
       "require": "./index.js"
     },
     "./lite": {
+      "types": "./lite.d.ts",
       "import": "./lite.js",
       "require": "./lite.js"
     },
@@ -39,18 +40,25 @@
     "index.js",
     "lite.js",
     "index.d.ts",
+    "lite.d.ts",
     "loader.js",
+    "loader.d.ts",
     "proxy.js",
+    "proxy.d.ts",
     "transform.js",
+    "transform.d.ts",
     "codegen.js",
+    "scripts/",
     "vite-plugin.js",
+    "vite-plugin.d.ts",
     "locales/",
     "README.md",
     "README_zh.md"
   ],
   "scripts": {
-    "minify-locales": "for f in locales/*.json; do jq -c . \"$f\" > \"$f.tmp\" && mv \"$f.tmp\" \"$f\"; done",
-    "prepublishOnly": "npm run minify-locales"
+    "minify-locales": "node scripts/minify-locales.js",
+    "prepublishOnly": "npm run minify-locales",
+    "test": "node tests/simple.test.js && node tests/verify-on-demand.js"
   },
   "keywords": [
     "monaco-editor",

package/proxy.d.ts

@@ -0,0 +1,60 @@
+/**
+ * NLS 代理对象，由 loader/plugin 智能注入到 Monaco Editor 生命周期中。
+ * 兼容 VS Code 和 Monaco 0.50.0+ 的内部签名。
+ */
+export interface NLSProxy {
+  /** 
+   * 核心本地化翻译函数 / Core localization function.
+   * @param path 模块相对于 esm 的路径 (由 transform 注入) / Module path relative to 'esm'.
+   * @param data 翻译标识符 (key) 或包含 key 的配置对象 / Translation key or object.
+   * @param defaultMessage 默认回退消息 / Fallback message.
+   * @param args 模板插值参数 / Template interpolation arguments.
+   */
+  localize(path: string, data: any, defaultMessage: string, ...args: any[]): string;
+
+  /** 
+   * 同 localize，但返回包含原始文本的对象 / Same as localize, returns object with 'value' and 'original'.
+   */
+  localize2(path: string, data: any, defaultMessage: string, ...args: any[]): { value: string; original: string };
+
+  /** 
+   * 设置当前的语言包字典数据 / Set the current locale dictionary data.
+   * @param data 翻译数据字典 / Translation dictionary.
+   * @param locale 语言代码名称 / Locale code name (e.g. 'zh-hans').
+   */
+  setLocaleData(data: Record<string, any>, locale?: string): void;
+
+  /** 
+   * 获取当前已加载的完整字典数据 / Get the raw translation data.
+   */
+  getLocaleData(): Record<string, any> | null;
+
+  /** 
+   * 获取当前活跃的语言代码名称 / Get the current active locale name.
+   */
+  getLocaleName(): string;
+
+  /** 获取默认配置语言 (通常为已弃用或返回 undefined) */
+  getConfiguredDefaultLocale(): string | undefined;
+
+  /** VS Code 兼容接口：加载消息包 */
+  loadMessageBundle(file: string): (path: string, data: any, defaultMessage: string, ...args: any[]) => string;
+
+  /** VS Code 兼容接口：初始化配置 */
+  config(opt: any): (file: string) => any;
+
+  /** 
+   * 动态创建一个针对特定 Context 的代理实例 / Create a contextual proxy instance.
+   */
+  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;
+  };
+}
+
+/**
+ * 默认导出的 NLS 代理实例
+ */
+declare const proxy: NLSProxy;
+export default proxy;

package/scripts/minify-locales.js

@@ -0,0 +1,19 @@
+const fs = require('fs')
+const path = require('path')
+
+const localesDir = path.join(__dirname, '..', 'locales')
+
+function minifyLocaleFile(filePath) {
+  const original = fs.readFileSync(filePath, 'utf8')
+  const parsed = JSON.parse(original)
+  const minified = JSON.stringify(parsed)
+
+  if (original !== minified) {
+    fs.writeFileSync(filePath, minified)
+  }
+}
+
+for (const entry of fs.readdirSync(localesDir)) {
+  if (!entry.endsWith('.json')) continue
+  minifyLocaleFile(path.join(localesDir, entry))
+}

package/transform.d.ts

@@ -0,0 +1,16 @@
+import { PluginOptions } from './vite-plugin';
+
+/**
+ * 转换 Monaco Editor 源代码以注入本地化路径。
+ * 支持 Webpack Loader 和 Vite Plugin 调用。
+ * 
+ * @param source 源代码内容
+ * @param id 文件路径 (resourcePath 或 vite id)
+ * @param options 配置项
+ * @returns 转换后的对象 { code, map } 或原始字符串
+ */
+export function transform(
+  source: string, 
+  id: string, 
+  options?: PluginOptions
+): { code: string; map: any } | string;

package/transform.js

@@ -13,10 +13,11 @@ const LOCALIZE_REGEX = /nls\.localize(\d?)\(/g
 function transform(source, id, options = {}) {
   // 统一路径分隔符
   const resourcePath = id.replace(/\\/g, '/')
+  const hasCustomMonacoPath = typeof options.monacoPath === 'string' && options.monacoPath.length > 0
   let monacoRoot = options.monacoPath || 'monaco-editor/esm'
 
   // 4. 自动路径探测增强：如果是默认路径且在 node_modules 中，尝试自动定位物理路径
-  if (monacoRoot === 'monaco-editor/esm' && !CACHED_MONACO_ROOT) {
+  if (!hasCustomMonacoPath && monacoRoot === 'monaco-editor/esm' && !CACHED_MONACO_ROOT) {
     try {
       // 尝试自动定位 monaco-editor 的安装目录 (适配 pnpm, npm, yarn)
       const pkgPath = require.resolve('monaco-editor/package.json', { paths: [process.cwd()] })
@@ -27,7 +28,7 @@ function transform(source, id, options = {}) {
   }
 
   // 优先匹配物理路径，否则回退到特征字符串匹配
-  const matchPath = CACHED_MONACO_ROOT || monacoRoot
+  const matchPath = hasCustomMonacoPath ? monacoRoot : (CACHED_MONACO_ROOT || monacoRoot)
 
   if (resourcePath.includes(matchPath)) {
     // 计算模块路径 (相对于 esm 目录)

package/vite-plugin.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 为 Vite/Rollup 应用注入 Monaco Editor 本地化路径转换的插件。
+ * [Vite/Rollup Plugin] Inject localization path transformations into Monaco Editor.
+ */
+declare function monacoNlsPlugin(options?: monacoNlsPlugin.PluginOptions): any;
+
+declare namespace monacoNlsPlugin {
+  /**
+   * 插件配置项 / Plugin configuration options.
+   */
+  export interface PluginOptions {
+    /** 
+     * 匹配 monaco-editor 源码的目录名或物理路径片段。
+     * [Optional] The path fragment to identify Monaco Editor's source directory (e.g. 'monaco-editor/esm').
+     * 默认会自动探测 node_modules 下的 monaco-editor/esm，通常无需配置。
+     * Matches npm, pnpm, and yarn local paths automatically if using default 'monaco-editor'.
+     */
+    monacoPath?: string;
+
+    /**
+     * 需要包含在最终产物中的语言包列表。
+     * [Optional] List of languages to include in the bundle (e.g. ['zh-hans', 'en']).
+     * 如果不指定，则默认包含所有可用的语言包。
+     * If not specified, all available language packs will be included.
+     */
+    languages?: string[];
+  }
+}
+
+export = monacoNlsPlugin;

package/vite-plugin.js

@@ -1,5 +1,5 @@
 const { transform } = require('./transform')
-const { generateLocalesCode } = require('./codegen')
+const { replaceLocaleLoaders } = require('./codegen')
 
 /**
  * Vite Plugin for Monaco Editor NLS Adapter
@@ -24,23 +24,8 @@ function monacoNlsPlugin(options = {}) {
 
       // 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,
+          code: replaceLocaleLoaders(code, languages),
           map: null // 对于这种简单的替换，暂不生成 sourcemap 以保持性能
         }
       }