monaco-editor-nls-adapter 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,134 @@
+# monaco-editor-nls-adapter
+
+[![npm version](https://img.shields.io/npm/v/monaco-editor-nls-adapter.svg)](https://www.npmjs.com/package/monaco-editor-nls-adapter)
+[![License](https://img.shields.io/npm/l/monaco-editor-nls-adapter.svg)](https://github.com/your-username/monaco-editor-nls-adapter/blob/main/LICENSE)
+
+Multi-language NLS adapter for Monaco Editor 0.50.0+ (Self-hosted). Bridge the gap for localization in modern building environments.
+
+[简体中文](./README_zh.md) | English
+
+---
+
+## 🌟 Features
+
+- **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.
+- **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.
+- **Cross-Bundler**: Native support for **Webpack** (Loader) and **Vite/Rollup** (Plugin).
+
+## 🚀 Installation
+
+```bash
+npm install monaco-editor-nls-adapter
+```
+
+## 🛠 Configuration
+
+### 1. Webpack (Loader)
+
+In your `webpack.config.js`, add the adapter's loader to process Monaco Editor's ESM files.
+
+```javascript
+module.exports = {
+  module: {
+    rules: [
+      {
+        test: /\.js$/,
+        // Crucial: Only process monaco-editor core files to avoid side effects
+        include: /node_modules[\\/]monaco-editor[\\/]esm/,
+        use: [
+          {
+            loader: 'monaco-editor-nls-adapter/loader'
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+### 2. 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';
+
+export default defineConfig({
+  plugins: [
+    monacoNlsPlugin()
+  ]
+});
+```
+
+## 📖 Usage
+
+### Initialization
+
+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.
+ */
+nlsAdapter.init('zh-hans');
+
+/**
+ * Option 2: Asynchronous (Performance Optimization)
+ * Leverages Webpack/Vite dynamic imports for code splitting.
+ */
+// await nlsAdapter.initAsync('zh-hans');
+
+/**
+ * Option 3: Automatic Browser Detection
+ */
+// nlsAdapter.init(); // Sync
+// await nlsAdapter.initAsync(); // Async
+
+import * as monaco from 'monaco-editor';
+
+monaco.editor.create(document.getElementById('container'), {
+  value: 'console.log("Hello Localization!");',
+  language: 'javascript'
+});
+```
+
+## 🗂 Supported Locales
+
+| Code | Language |
+| --- | --- |
+| `zh-hans` | Simplified Chinese (简体中文) |
+| `zh-hant` | Traditional Chinese (繁体中文) |
+| `en` | English |
+| `ja` | Japanese (日本語) |
+| `ko` | Korean (한국어) |
+| `de` | German (Deutsch) |
+| `fr` | French (Français) |
+| `es` | Spanish (Español) |
+| `it` | Italian (Italiano) |
+| `ru` | Russian (Русский) |
+| `pl` | Polish (Polski) |
+| `tr` | Turkish (Türkçe) |
+| `cs` | Czech (Čeština) |
+| `pt-br` | Portuguese - Brazil (Português) |
+
+## ❓ FAQ
+
+### Why do I need this instead of `monaco-editor-nls`?
+Since version 0.50.0, Monaco Editor updated its internal `localize` function signature. Existing plugins often rely on older versions or external CDNs. This adapter provides a clean, self-hosted proxy and a modern build-time transformation for both Webpack and Vite.
+
+## 📄 License
+
+MIT
+
+---
+
+## 💖 Credits & Attribution
+
+The localized language packs (`.json` files) in the `/locales` directory are sourced from the [monaco-editor-nls](https://github.com/wang12124468/monaco-editor-nls) project. Special thanks to the original authors for their contributions to the community.

package/README_zh.md

@@ -0,0 +1,137 @@
+# monaco-editor-nls-adapter
+
+[![npm version](https://img.shields.io/npm/v/monaco-editor-nls-adapter.svg)](https://www.npmjs.com/package/monaco-editor-nls-adapter)
+[![License](https://img.shields.io/npm/l/monaco-editor-nls-adapter.svg)](https://github.com/your-username/monaco-editor-nls-adapter/blob/main/LICENSE)
+
+针对 Monaco Editor 0.50.0 及以上版本的多语言本地化适配器。专为现代化构建工具（Webpack, Vite）设计的自托管解决方案。
+
+简体中文 | [English](./README.md)
+
+---
+
+## 🌟 特性
+
+- **自托管语言包**: 无需依赖外部 CDN；所有语言数据在本地打包。
+- **适配 Monaco 0.50.0+**: 完全兼容 Monaco Editor 最新的内部 NLS 调用签名。
+- **性能优化 (懒加载)**: 通过 Webpack/Vite 的动态导入实现按需分包加载。
+- **TypeScript 支持**: 完善的类型定义，为开发提供极佳的智能感知。
+- **智能语言识别**: 支持自动识别浏览器语言或手动切换。
+- **跨构建工具支持**: 原生支持 **Webpack** (Loader) 以及 **Vite/Rollup** (Plugin)。
+
+## 🚀 安装
+
+```bash
+npm install monaco-editor-nls-adapter
+```
+
+## 🛠 配置
+
+### 1. Webpack (Loader)
+
+在 `webpack.config.js` 中，添加此适配器的 loader 来处理 Monaco Editor 的 ESM 源码。
+
+```javascript
+module.exports = {
+  module: {
+    rules: [
+      {
+        test: /\.js$/,
+        // 重要：仅处理 monaco-editor 的 esm 目录，避免对业务代码产生副作用
+        include: /node_modules[\\/]monaco-editor[\\/]esm/,
+        use: [
+          {
+            loader: 'monaco-editor-nls-adapter/loader'
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+### 2. Vite / Rollup (Plugin)
+
+在 `vite.config.js` 中，添加此插件：
+
+```javascript
+import { defineConfig } from 'vite';
+import monacoNlsPlugin from 'monaco-editor-nls-adapter/vite-plugin';
+
+export default defineConfig({
+  plugins: [
+    monacoNlsPlugin()
+  ]
+});
+```
+
+## 📖 使用指南
+
+### 初始化
+
+在导入 `monaco-editor` 或创建任何实例**之前**，先调用 `init` 或 `initAsync`。
+
+```typescript
+import * as nlsAdapter from 'monaco-editor-nls-adapter';
+
+/**
+ * 方式 1: 同步初始化 (标准用法)
+ * 适用于语言包体量较小，或不介意首屏全量包含翻译数据的场景。
+ */
+nlsAdapter.init('zh-hans');
+
+/**
+ * 方式 2: 异步初始化 (性能优化推荐)
+ * 利用 Webpack/Vite 的动态 import 实现分包，仅加载当前所需语言。
+ */
+// await nlsAdapter.initAsync('zh-hans');
+
+/**
+ * 方式 3: 自动识别浏览器语言
+ */
+// nlsAdapter.init(); // 同步
+// await nlsAdapter.initAsync(); // 异步
+
+import * as monaco from 'monaco-editor';
+
+monaco.editor.create(document.getElementById('container'), {
+  value: 'console.log("Hello Localization!");',
+  language: 'javascript'
+});
+```
+
+## 🗂 支持的语言列表
+
+| 语言代码 | 对应语言 |
+| --- | --- |
+| `zh-hans` | 简体中文 |
+| `zh-hant` | 繁体中文 |
+| `en` | 英语 (English) |
+| `ja` | 日本语 (Japanese) |
+| `ko` | 韩语 (Korean) |
+| `de` | 德语 (German) |
+| `fr` | 法语 (French) |
+| `es` | 西班牙语 (Spanish) |
+| `it` | 意大利语 (Italian) |
+| `ru` | 俄语 (Russian) |
+| `pl` | 波兰语 (Polish) |
+| `tr` | 土耳其语 (Turkish) |
+| `cs` | 捷克语 (Czech) |
+| `pt-br` | 葡萄牙语 - 巴西 (Portuguese) |
+
+## ❓ 常见问题 (FAQ)
+
+### 为什么选择此适配器而不是 `monaco-editor-nls`?
+自 0.50.0 版本起，Monaco Editor 更新了内部 `localize` 函数的签名。现有许多插件依赖于旧版本或外部 CDN。此适配器提供了一个完全自托管的代理和针对最新版本的现代转换逻辑。
+
+### 它能配合 `@monaco-editor/react` 使用吗？
+可以。请先在您的构建工具（Webpack/Vite）中配置好插件/Loader，然后在应用入口处生命周期（通常是根组件渲染前）调用 `nlsAdapter.init()` 即可。
+
+## 📄 许可证
+
+MIT
+
+---
+
+## 💖 致谢与归属声明
+
+`/locales` 目录中的语言包（`.json` 文件）来源于 [monaco-editor-nls](https://github.com/wang12124468/monaco-editor-nls) 项目。在此对原作者及社区的贡献表示衷心的感谢。

package/index.d.ts

@@ -0,0 +1,38 @@
+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;
+  };
+}
+
+/**
+ * 支持的语言代码类型
+ */
+export type LocaleCode = 
+  | 'zh-hans' | 'zh-cn' | 'zh-hant' | 'zh-tw'
+  | 'en' | 'ja' | 'ko' | 'de' | 'fr' | 'es' | 'it' | 'ru' | 'pl' | 'tr' | 'cs' | 'pt-br';
+
+/**
+ * 初始化 Monaco Editor 的语言包
+ * @param locale 语言代码，如 'zh-hans'。如果不传，将尝试检测浏览器语言。
+ */
+export function init(locale?: LocaleCode | string): void;
+
+/**
+ * 异步初始化 Monaco Editor 的语言包
+ * 使用动态 import()，支持 Webpack 分包和懒加载。
+ * @param locale 语言代码
+ */
+export function initAsync(locale?: LocaleCode | string): Promise<void>;
+
+/**
+ * NLS 代理对象，由 loader 注入到 Monaco 源码中
+ */
+export const proxy: NLSProxy;

package/index.js

@@ -0,0 +1,73 @@
+const proxy = require('./proxy')
+
+/**
+ * 语言映射字典，用于将常见的浏览器语言代码还原为本包中支持的代码。
+ */
+const LOCALE_MAP = {
+  'zh-cn': 'zh-hans',
+  'zh-hans': 'zh-hans',
+  'zh-tw': 'zh-hant',
+  'zh-hant': 'zh-hant',
+  'zh-hk': 'zh-hant',
+  'en-us': 'en',
+  'en-gb': 'en',
+  'en': 'en'
+}
+
+/**
+ * 使用指定的语言代码初始化 Monaco Editor 的本地化。
+ * 此方法会从本地 /locales 目录加载 JSON 数据。
+ * @param {string} locale 语言代码 (例如 'zh-hans', 'ja', 'ko')。如果不传，将尝试检测浏览器语言。
+ */
+function init(locale) {
+  // 如果没有传递 locale，尝试从浏览器环境获取
+  if (!locale && typeof navigator !== 'undefined') {
+    locale = navigator.language || navigator.userLanguage
+  }
+
+  // 小写化并查找映射
+  let targetLocale = (locale || 'zh-hans').toLowerCase()
+  if (LOCALE_MAP[targetLocale]) {
+    targetLocale = LOCALE_MAP[targetLocale]
+  }
+
+  try {
+    const data = require(`./locales/${targetLocale}.json`)
+    proxy.setLocaleData(data)
+  } catch (e) {
+    console.error(`[monaco-editor-nls-adapter] 无法加载本地语言包: ${targetLocale}。回退到默认设置。`, e)
+  }
+}
+
+/**
+ * 异步初始化 Monaco Editor 的本地化。
+ * 使用动态 import()，允许 Webpack 将语言包拆分为独立的 chunk，实现按需加载。
+ * @param {string} locale 语言代码。如果不传，将尝试检测浏览器语言。
+ * @returns {Promise<void>}
+ */
+async function initAsync(locale) {
+  // 如果没有传递 locale，尝试从浏览器环境获取
+  if (!locale && typeof navigator !== 'undefined') {
+    locale = navigator.language || navigator.userLanguage
+  }
+
+  // 小写化并查找映射
+  let targetLocale = (locale || 'zh-hans').toLowerCase()
+  if (LOCALE_MAP[targetLocale]) {
+    targetLocale = LOCALE_MAP[targetLocale]
+  }
+
+  try {
+    // 使用动态 import 实现懒加载
+    const module = await import(`./locales/${targetLocale}.json`)
+    proxy.setLocaleData(module.default || module)
+  } catch (e) {
+    console.error(`[monaco-editor-nls-adapter] 无法异步加载语言包: ${targetLocale}。`, e)
+  }
+}
+
+module.exports = {
+  init: init,
+  initAsync: initAsync,
+  proxy: proxy
+}

package/loader.js

@@ -0,0 +1,11 @@
+const { transform } = require('./transform')
+
+/**
+ * Webpack Loader for Monaco Editor NLS Adapter
+ */
+module.exports = function (source) {
+  if (this.cacheable) this.cacheable()
+  
+  // 使用共享的 transform 逻辑
+  return transform(source, this.resourcePath)
+}