@batype/chainspec 2.1.0 → 2.2.0

package/README.md

@@ -7,7 +7,7 @@ API.main.users.getUser.request({path:{id:'42'}});
 API.main.users.getUser.useRequest({path:{id:'42'}});
 ```
 
-React + Vite本地生成器，普通Node/browser SDK与React/SWR入口分开。**不执行生成代码，不发送业务请求，不上传输入文档。**
+React + Vite本地生成器，普通Node/browser SDK与React/SWR入口分开。**不执行生成代码，不发送业务请求，不上传整份接口文档。可选自动翻译只发送缺失的分组名称。**
 
 [在线使用](https://batype.github.io/chainspec/) · [需求与设计](docs/design.md) · [支持边界](docs/limits.md) · [验证记录](docs/validation.md)
 
@@ -15,7 +15,7 @@ React + Vite本地生成器，普通Node/browser SDK与React/SWR入口分开。*
 
 ## 一次完整流程
 
-导入文件、粘贴JSON或从URL获取 → 编辑可复用的JSON配置 → 生成 → 搜索接口并预览调用、类型与诊断 → 下载完整SDK ZIP。输入与配置改动后，旧结果暂停复制/下载。输入面板可以折叠。支持亮色、暗色、系统主题和手机布局。
+导入文件、粘贴JSON或从URL获取 → 填写配置表单 → 生成 → 搜索接口并预览调用、类型与诊断 → 下载完整SDK ZIP。输入与配置改动后，旧结果暂停复制/下载。输入面板可以折叠。支持亮色、暗色、系统主题和手机布局。
 
 支持Swagger2.0、OpenAPI3.0/3.1 JSON的常见子集，本地引用、递归模型、枚举、组合类型、参数与JSON/平面表单。没有模型的响应使用unknown并提示；不是完整的OpenAPI或JSON Schema实现。远程引用、YAML和Swagger UI HTML需先转换。
 
@@ -121,7 +121,7 @@ node bin/chainspec.mjs --in openapi.json --out ./new-sdk --namespace main --stri
 
 ### 一份 JSON 配置，网页与代码库共用
 
-网页的配置区直接编辑JSON，支持导入/导出，完整SDK ZIP也包含`chainspec.config.json`。配置格式版本`version: 1`与生成器npm版本独立。
+网页的配置区使用表单填写，点击旁边“查看配置”可预览、复制JSON；支持配置导入/导出，导入后回填表单。完整SDK ZIP也包含`chainspec.config.json`。配置格式版本`version: 1`与生成器npm版本独立。
 
 ```json
 {
@@ -138,7 +138,7 @@ node bin/chainspec.mjs --in openapi.json --out ./new-sdk --namespace main --stri
 ```
 
 ```sh
-npm install -D @batype/chainspec@^2.1.0
+npm install -D @batype/chainspec@^2.2.0
 npx chainspec --config chainspec.config.json
 # 接口更新后重新生成：
 npx chainspec --config chainspec.config.json --update
@@ -150,7 +150,7 @@ npx chainspec --in https://example.com/api-json --out ./new-sdk
 
 `input`也可以是`./openapi.json`，在代码库保留对应文件即可。配置文件中的本地input/output路径相对于配置文件；显式CLI参数覆盖JSON，并相对于当前工作目录。还可配置`stripPrefix`、`baseUrl`。未知键及错误类型直接报错，配置文件不执行JavaScript。网页只读取当前导入的JSON，不根据本地路径自动读磁盘；配置中的URL需要点击“获取JSON”。输出目录只用于CLI。
 
-首个Tag保留为分组依据，中文标签仍保留在说明和搜索中。调用链只生成ASCII标识符：显式`controllerNames`优先，未映射的非ASCII分组从路径推导并提示；同一Tag保持同一分组，重名使用稳定后缀。建议为中文Tag显式映射并提交配置，让名字在路径变化后仍保持稳定。2.0已有中文调用名的SDK需重新生成并修改调用；原有英文别名与v2入参约定保持不变。
+首个Tag保留为分组依据，中文标签仍保留在说明和搜索中。2.2起网页/CLI默认自动翻译缺失的中文分组；已有映射直接复用，`translateNames:false`或`--no-translate`关闭外部翻译。调用链只生成ASCII标识符：显式`controllerNames`优先，未映射的非ASCII分组从路径推导并提示；同一Tag保持同一分组，重名使用稳定后缀。建议为中文Tag显式映射并提交配置，让名字在路径变化后仍保持稳定。2.0已有中文调用名的SDK需重新生成并修改调用；原有英文别名与v2入参约定保持不变。
 
 `--update`通过CLI生成的文件清单和SHA256检查所有生成文件；手改文件、额外文件、符号链接、未由CLI管理的旧目录会拒绝更新。自定义请求与业务代码放在SDK目录外。没有`--update`仍不会覆盖已有目录。
 
@@ -165,6 +165,78 @@ API.main.users.listOrders.request({
 // useRequest使用同样的位置；具体字段由文档推导。
 ```
 
+### 2.2 自动翻译、API Key 与名称缓存
+
+网页支持 MyMemory（免密钥）、有道智云、百度翻译和 Google Cloud Translation。只翻译当前分组规则下缺少映射的中文名称，同一分组每次只请求一次；`controllerNames`中的手工或粘贴值优先。英文结果转为camelCase，例如`SMS Management`→`smsManagement`。已有名称不会因为切换翻译服务而改变。
+
+配置示例：
+
+```json
+{
+  "version": 1,
+  "input": "./openapi.json",
+  "output": "./src/api",
+  "groupBy": "tag",
+  "translateNames": true,
+  "translation": {
+    "provider": "baidu",
+    "appIdEnv": "BAIDU_TRANSLATE_APP_ID",
+    "apiKeyEnv": "BAIDU_TRANSLATE_SECRET_KEY",
+    "proxyUrl": "http://127.0.0.1:4190/translate"
+  },
+  "controllerNames": {}
+}
+```
+
+真实密钥放在配置旁边的`.env`中，不写到JSON、SDK或翻译缓存中：
+
+```dotenv
+BAIDU_TRANSLATE_APP_ID=你的应用ID
+BAIDU_TRANSLATE_SECRET_KEY=你的密钥
+```
+
+| provider | apiKeyEnv 默认值 | appIdEnv 默认值 |
+|---|---|---|
+| google | GOOGLE_TRANSLATE_API_KEY | 不需要 |
+| baidu | BAIDU_TRANSLATE_SECRET_KEY | BAIDU_TRANSLATE_APP_ID |
+| youdao | YOUDAO_TRANSLATE_SECRET_KEY | YOUDAO_TRANSLATE_APP_KEY |
+| mymemory | 不需要 | 不需要 |
+
+CLI自动读取配置旁边的`.env`，系统已有环境变量优先。也可用`--env-file PATH`指定文件。可以复制[配置示例](examples/translation.config.json)和[环境变量模板](examples/translation.env.example)。
+
+```sh
+npx chainspec --config chainspec.config.json --update
+```
+
+成功翻译会写回配置文件的`controllerNames`，SDK中也有`controller-names.json`。这些JSON是可提交到代码库的名称缓存，下一次生成优先复用，无需再次调用翻译API；`--update`也会读取原SDK的缓存。CLI不覆盖生成期间被其他程序修改的配置。失败项只回退路径命名并诊断，不写入成功缓存，下次可以重试；不会改用其他服务发送名称。CLI未成功写回时会提示，已生成SDK中的缓存仍保留。
+
+网页默认在当前浏览器缓存名称，也把映射写入下载配置与ZIP中的`controller-names.json`。支持粘贴JSON、完整配置中的controllerNames，或每行`原分组=英文名`；支持复制映射和清除浏览器缓存。浏览器无法直接改写代码库文件，需将导出的配置保存回工程。
+
+#### 网页使用带密钥的服务
+
+GitHub Pages是静态网页。网页通过你自己的翻译代理调用有道、百度或Google，密钥保留在本机。包内附带本地代理：
+
+```sh
+# 配置和.env准备好后运行：
+npx chainspec translate-server --config chainspec.config.json --origin https://batype.github.io
+```
+
+将网页服务选择与JSON配置保持一致，代理地址填写`http://127.0.0.1:4190/translate`。开发预览时把`--origin`改成当前页面的origin（如`http://127.0.0.1:4185`）。代理只监听127.0.0.1，只允许指定origin，只接收分组名称和服务名，不接收浏览器传入的密钥。浏览器可能要求本地网络访问许可；也可在自己的后端部署HTTPS代理，按同样协议实现：`POST {text,provider}`→`{translatedText}`。CLI直接访问官方服务，`proxyUrl`仅用于网页。
+
+Node适配器使用[百度MD5签名](https://fanyi-api.baidu.com/doc_bd/21)、[有道v3 SHA256签名](https://ai.youdao.com/DOCSIRMA/html/trans/api/wbfy/index.html)、[Google Basic v2 API Key](https://docs.cloud.google.com/translate/docs/reference/rest/v2/translate)。MyMemory匿名额度目前为[每日5000字符](https://mymemory.translated.net/doc/usagelimits.php)，单次500字节；其他服务按用户账户权限和配额计费。本工具自动翻译每次最多100个分组、5000字符，每个名称最多500字节；超出部分会提示并回退路径命名，已有缓存继续生效。
+
+同步`generateSDK`始终离线。异步API可配置自己的翻译方法；Node官方适配器也可嵌入你的后端：
+
+```ts
+import {generateSDKAsync} from '@batype/chainspec';
+import {createNodeTranslator} from '@batype/chainspec/node';
+const translation = {provider:'google',apiKeyEnv:'GOOGLE_TRANSLATE_API_KEY'} as const;
+const project = await generateSDKAsync(jsonText, {groupBy:'tag',translation}, {
+  translate:createNodeTranslator(translation)
+});
+// 保存project.controllerNames供下次复用。
+```
+
 Node生成器API：
 
 ```ts
@@ -186,7 +258,7 @@ npx --yes --package=@batype/chainspec chainspec --in openapi.json --out ./new-sd
 
 ## 数据与安全边界
 
-只有点击获取链接或执行CLI时才GET指定的JSON；浏览器不携带Cookie/认证、不经过代理，目标站需允许CORS，HTTPS页面不能获取HTTP资源。生产CSP仅为URL导入允许HTTP(S)连接；Worker仍只解析文档，不获取外部引用。URL导入有20秒超时及8MiB流式限制，可取消。仅主题持久化，无云历史或遥测。输入最大8MiB、5000操作/模型。清空后移除当前输入和结果。不要未经检查就公开包含业务模型、地址和枚举的生成SDK。仓库、截图和测试使用合成API；用户提供的文档不进入公开源码。
+只有点击获取链接或执行CLI时才GET指定的JSON；浏览器不携带Cookie/认证、不经过代理，目标站需允许CORS，HTTPS页面不能获取HTTP资源。生产CSP仅为URL导入允许HTTP(S)连接；Worker仍只解析文档，不获取外部引用。URL导入有20秒超时及8MiB流式限制，可取消。仅主题和英文分组名称缓存持久化，无云历史或遥测。输入最大8MiB、5000操作/模型。清空后移除当前输入和结果。不要未经检查就公开包含业务模型、地址和枚举的生成SDK。仓库、截图和测试使用合成API；用户提供的文档不进入公开源码。
 
 类型不验证服务端数据；不猜鉴权凭据；不保证复杂序列化和所有Schema约束。int64依然是JS number，需要精度时由服务器返回string。参阅[限制](docs/limits.md)。
 

package/bin/chainspec.mjs

@@ -1,12 +1,14 @@
 #!/usr/bin/env node
 import { readFile, mkdir, writeFile, lstat, rm, readdir, rename } from "node:fs/promises";
 import { resolve, dirname, basename, join } from "node:path";
+import { loadEnvFile } from "node:process";
+import { createNodeTranslator } from "./translation-provider.mjs";
 import { createHash, randomUUID } from "node:crypto";
-import { generateSDK, parseConfig, fetchDocument, MAX_BYTES, VERSION } from "../lib/core/index.js";
+import { generateSDKAsync, parseConfig, parseControllerNames, fetchDocument, MAX_BYTES, VERSION } from "../lib/core/index.js";
 const args = process.argv.slice(2), opts = {};
 const marker = ".chainspec-generated.json";
 const digest = text => createHash("sha256").update(text).digest("hex");
-let inputPath, output, configPath, update = false;
+let inputPath, output, configPath, envPath, update = false;
 async function localJSON(path) {
   const stat = await lstat(path);
   if (!stat.isFile() || stat.size > MAX_BYTES)
@@ -18,8 +20,12 @@ async function exists(path) {
   catch (e) { if (e.code === "ENOENT") return null; throw e; }
 }
 try {
+  if (args[0] === "translate-server") {
+    const { runTranslationServer } = await import("./translation-server.mjs");
+    await runTranslationServer(args.slice(1));
+  } else {
   if (args.includes("--help") || !args.length) {
-    console.log("chainspec --config chainspec.config.json [--update]\nchainspec --in openapi.json|https://example.com/api-json --out ./new-sdk [--namespace main] [--strip-prefix /v1/api] [--group-by path|tag] [--base-url URL] [--no-hooks]\nPaths in JSON resolve relative to the config file; explicit CLI flags override JSON.\nCreates a new directory. --update replaces only an unchanged CLI-generated directory.");
+    console.log("chainspec --config chainspec.config.json [--update] [--no-translate] [--env-file .env]\nchainspec translate-server --config chainspec.config.json [--env-file .env] [--origin https://batype.github.io]\nchainspec --in openapi.json|https://example.com/api-json --out ./new-sdk [--namespace main] [--strip-prefix /v1/api] [--group-by path|tag] [--base-url URL] [--no-hooks]\nPaths in JSON resolve relative to the config file; explicit CLI flags override JSON.\nCreates a new directory. --update replaces only an unchanged CLI-generated directory.");
     process.exit(0);
   }
   if (args.includes("--version")) { console.log(VERSION); process.exit(0); }
@@ -27,16 +33,20 @@ try {
     const flag = args[i];
     if (flag === "--no-hooks") { opts.hooks = false; continue; }
     if (flag === "--update") { update = true; continue; }
-    if (!["--config", "--in", "--out", "--namespace", "--strip-prefix", "--group-by", "--base-url"].includes(flag))
+    if (flag === "--translate") { opts.translateNames = true; continue; }
+    if (flag === "--no-translate") { opts.translateNames = false; continue; }
+    if (!["--env-file", "--config", "--in", "--out", "--namespace", "--strip-prefix", "--group-by", "--base-url"].includes(flag))
       throw Error("Unknown option; use --help");
     const val = args[++i];
     if (!val || val.startsWith("--")) throw Error("Missing option value");
-    if (flag === "--config") configPath = resolve(val);
+    if (flag === "--env-file") envPath = resolve(val);
+    else if (flag === "--config") configPath = resolve(val);
     else if (flag === "--in") inputPath = val;
     else if (flag === "--out") output = val;
     else opts[{"--namespace":"namespace", "--strip-prefix":"stripPrefix", "--group-by":"groupBy", "--base-url":"baseUrl"}[flag]] = val;
   }
-  const config = configPath ? parseConfig(await localJSON(configPath)) : undefined;
+  const configText = configPath ? await localJSON(configPath) : undefined;
+  const config = configText ? parseConfig(configText) : undefined;
   const base = configPath ? dirname(configPath) : process.cwd();
   const source = inputPath ?? config?.input;
   const destination = output ? resolve(output) : config ? resolve(base, config.output) : undefined;
@@ -46,7 +56,6 @@ try {
   const text = /^[a-z][a-z\d+.-]*:/i.test(source)
     ? await fetchDocument(source)
     : await localJSON(resolve(inputPath ? process.cwd() : base, source));
-  const result = generateSDK(text, settings);
   const dir = destination;
   const old = await exists(dir);
   if (old) {
@@ -67,6 +76,20 @@ try {
         throw Error("Generated files changed; choose a new directory to preserve edits");
     }
   }
+  let cachedNames = {};
+  if (old && await exists(join(dir, "controller-names.json")))
+    cachedNames = parseControllerNames(await localJSON(join(dir, "controller-names.json")));
+  if (envPath) loadEnvFile(envPath);
+  else if (configPath) {
+    try { loadEnvFile(resolve(base, ".env")); }
+    catch (error) { if (error.code !== "ENOENT") throw error; }
+  }
+  const translate = createNodeTranslator(settings.translation ?? { provider: "mymemory" });
+  const result = await generateSDKAsync(text, {
+    ...settings, controllerNames: { ...cachedNames, ...settings.controllerNames },
+  }, { translate });
+  for (const diagnostic of result.diagnostics.filter(d => d.code.startsWith("translation-")))
+    console.warn(diagnostic.message);
   await mkdir(dirname(dir), { recursive: true });
   const stage = join(dirname(dir), `.${basename(dir)}.chainspec-${randomUUID()}`);
   await mkdir(stage, { mode: 0o700 });
@@ -88,7 +111,20 @@ try {
       catch (e) { await rm(dir, { recursive: true, force: true }); throw e; }
     }
   } finally { await rm(stage, { recursive: true, force: true }); }
+  if (configPath && config && JSON.stringify(config.controllerNames ?? {}) !== JSON.stringify(result.controllerNames)) {
+    const temp = `${configPath}.chainspec-${randomUUID()}.tmp`;
+    try {
+      if (await localJSON(configPath) !== configText) throw Error("Configuration changed during generation");
+      const mode = (await lstat(configPath)).mode & 0o777;
+      await writeFile(temp, JSON.stringify({ ...config, controllerNames: result.controllerNames }, null, 2) + "\n", { flag: "wx", mode });
+      await rename(temp, configPath);
+      console.log("Saved English group names to config; future runs reuse them without translation.");
+    } catch {
+      console.warn("SDK generated, but config cache was not saved (changed or not writable). Names remain in controller-names.json.");
+    } finally { await rm(temp, { force: true }); }
+  }
   console.log(`Generated ${result.operations.length} operations, ${result.schemaCount} schemas, ${result.diagnostics.length} diagnostics.\nOutput: ${dir}`);
+}
 } catch (error) {
   console.error(error?.code === "EEXIST" ? "Output already exists; choose a new directory or use --update." : error instanceof Error ? error.message : "Generation failed");
   process.exitCode = 1;

package/bin/translation-provider.d.ts

@@ -0,0 +1,2 @@
+import type { TranslationConfig } from "../lib/core/index.js";
+export declare function createNodeTranslator(config?: TranslationConfig, env?: Record<string, string | undefined>, transport?: typeof fetch): (text: string, signal?: AbortSignal) => Promise<string>;

package/bin/translation-provider.mjs

@@ -0,0 +1,64 @@
+import { createHash, randomUUID } from "node:crypto";
+import { setTimeout as delay } from "node:timers/promises";
+import { parseTranslationConfig, translateWithMyMemory, TranslationError, readTranslationResponse } from "../lib/core/index.js";
+
+/** Official provider adapters. Secrets are read lazily and never returned or logged. */
+export function createNodeTranslator(config = { provider: "mymemory" }, env = process.env, transport = fetch) {
+  const options = parseTranslationConfig(config);
+  let nextStart = 0;
+  const required = (key) => {
+    const value = env[key];
+    if (typeof value !== "string" || !value.trim()) throw new TranslationError(`缺少环境变量 ${key}，请在本地 .env 或系统环境变量中配置。`);
+    return value;
+  };
+  return async (text, signal) => {
+    signal?.throwIfAborted();
+    if (typeof text !== "string" || !text || Buffer.byteLength(text) > 500)
+      throw new TranslationError("自动翻译仅接受 500 字节以内的分组名称。");
+    if (options.provider === "mymemory") return translateWithMyMemory(text, signal);
+    const key = required(options.apiKeyEnv);
+    const appId = options.provider === "google" ? undefined : required(options.appIdEnv);
+    if (options.provider === "baidu") {
+      const now = Date.now(), start = Math.max(now, nextStart);
+      nextStart = start + 1100;
+      if (start > now) await delay(start - now, undefined, { signal });
+    }
+    const salt = randomUUID().replaceAll("-", "");
+    let url, body;
+    if (options.provider === "google") {
+      url = new URL("https://translation.googleapis.com/language/translate/v2");
+      url.searchParams.set("key", key);
+      body = new URLSearchParams({ q: text, source: "zh-CN", target: "en", format: "text" });
+    } else if (options.provider === "baidu") {
+      url = new URL("https://fanyi-api.baidu.com/api/trans/vip/translate");
+      const sign = createHash("md5").update(appId + text + salt + key, "utf8").digest("hex");
+      body = new URLSearchParams({ q: text, from: "zh", to: "en", appid: appId, salt, sign });
+    } else {
+      url = new URL("https://openapi.youdao.com/api");
+      const curtime = String(Math.floor(Date.now() / 1000));
+      const chars = Array.from(text);
+      const input = chars.length <= 20 ? text : chars.slice(0, 10).join("") + chars.length + chars.slice(-10).join("");
+      const sign = createHash("sha256").update(appId + input + salt + curtime + key, "utf8").digest("hex");
+      body = new URLSearchParams({ q: text, from: "zh-CHS", to: "en", appKey: appId, salt, curtime, sign, signType: "v3" });
+    }
+    let data;
+    try {
+      const response = await transport(url, {
+        method: "POST", headers: { "Content-Type": "application/x-www-form-urlencoded" }, body,
+        redirect: "error", credentials: "omit", referrerPolicy: "no-referrer",
+        signal: AbortSignal.any([AbortSignal.timeout(10_000), ...(signal ? [signal] : [])]),
+      });
+      if (!response.ok) { await response.body?.cancel(); throw Error("HTTP failure"); }
+      data = await readTranslationResponse(response);
+    } catch {
+      signal?.throwIfAborted();
+      throw new TranslationError("翻译服务请求失败，请检查网络、密钥权限和额度。");
+    }
+    const result = options.provider === "google" ? data?.data?.translations?.[0]?.translatedText
+      : options.provider === "baidu" ? (!data.error_code ? data?.trans_result?.[0]?.dst : undefined)
+      : (String(data.errorCode) === "0" ? data?.translation?.[0] : undefined);
+    if (typeof result !== "string" || !result.trim())
+      throw new TranslationError("翻译服务未返回译文，请检查应用 ID、密钥、服务开通状态及额度。");
+    return result;
+  };
+}

package/bin/translation-server.mjs

@@ -0,0 +1,82 @@
+import { createServer } from "node:http";
+import { readFile, lstat } from "node:fs/promises";
+import { loadEnvFile } from "node:process";
+import { resolve, dirname } from "node:path";
+import { parseConfig, parseTranslationConfig, TranslationError } from "../lib/core/index.js";
+import { createNodeTranslator } from "./translation-provider.mjs";
+
+/** Loopback-only bridge for a static web page. Never accepts keys from the browser. */
+export function createTranslationServer(translation, origin, translate = createNodeTranslator(translation)) {
+  const config = parseTranslationConfig(translation);
+  return createServer(async (req, res) => {
+    res.setHeader("Cache-Control", "no-store");
+    res.setHeader("X-Content-Type-Options", "nosniff");
+    if (req.headers.origin !== origin) { res.writeHead(403); res.end(); return; }
+    res.setHeader("Access-Control-Allow-Origin", origin);
+    res.setHeader("Vary", "Origin");
+    if (req.url !== "/translate") { res.writeHead(404); res.end(); return; }
+    if (req.method === "OPTIONS") {
+      res.setHeader("Access-Control-Allow-Methods", "POST, OPTIONS");
+      res.setHeader("Access-Control-Allow-Headers", "Content-Type");
+      if (req.headers["access-control-request-private-network"] === "true")
+        res.setHeader("Access-Control-Allow-Private-Network", "true");
+      res.writeHead(204); res.end(); return;
+    }
+    if (req.method !== "POST" || !/^application\/json(?:;|$)/i.test(req.headers["content-type"] ?? "")) {
+      res.writeHead(415); res.end(); return;
+    }
+    const abort = new AbortController();
+    res.on("close", () => { if (!res.writableEnded) abort.abort(); });
+    const reply = (status, data) => { res.writeHead(status, { "Content-Type": "application/json" }); res.end(JSON.stringify(data)); };
+    const chunks = [];
+    try {
+      let bytes = 0;
+      for await (const chunk of req) {
+        bytes += chunk.length;
+        if (bytes > 4096) { reply(413, { error: "Request too large" }); return; }
+        chunks.push(chunk);
+      }
+      const value = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+      if (typeof value.text !== "string" || !value.text || Buffer.byteLength(value.text) > 500 || value.provider !== config.provider) {
+        reply(400, { error: "Invalid group name or provider mismatch" }); return;
+      }
+      const translatedText = await translate(value.text, abort.signal);
+      if (!abort.signal.aborted) reply(200, { translatedText });
+    } catch (error) {
+      if (abort.signal.aborted) return;
+      reply(502, { error: error instanceof TranslationError ? error.message : "Translation failed" });
+    }
+  });
+}
+
+export async function runTranslationServer(args) {
+  if (args.includes("--help")) {
+    console.log("chainspec translate-server --config chainspec.config.json [--env-file .env] [--port 4190] [--origin https://batype.github.io]\nBinds only 127.0.0.1. Real API keys stay in the local environment.");
+    return;
+  }
+  let configPath, envPath, port = 4190, origin = "https://batype.github.io";
+  for (let i = 0; i < args.length; i++) {
+    const flag = args[i], value = args[++i];
+    if (!value || !["--config", "--env-file", "--port", "--origin"].includes(flag)) throw Error("Use translate-server --config FILE [--env-file .env] [--port 4190] [--origin https://batype.github.io]");
+    if (flag === "--config") configPath = resolve(value);
+    else if (flag === "--env-file") envPath = resolve(value);
+    else if (flag === "--port") port = Number(value);
+    else origin = value;
+  }
+  if (!configPath) throw Error("translate-server requires --config");
+  if (!Number.isInteger(port) || port < 1024 || port > 65535) throw Error("Port must be 1024–65535");
+  const url = new URL(origin);
+  if (url.origin !== origin || !["http:", "https:"].includes(url.protocol) || url.username || url.password) throw Error("--origin must be a single HTTP(S) origin without a path");
+  const stat = await lstat(configPath);
+  if (!stat.isFile() || stat.size > 8 * 1024 * 1024) throw Error("Invalid config file");
+  const config = parseConfig(await readFile(configPath, "utf8"));
+  if (envPath) loadEnvFile(envPath);
+  else {
+    try { loadEnvFile(resolve(dirname(configPath), ".env")); }
+    catch (error) { if (error.code !== "ENOENT") throw error; }
+  }
+  const server = createTranslationServer(config.translation ?? { provider: "mymemory" }, origin);
+  await new Promise((resolve, reject) => { server.once("error", reject); server.listen(port, "127.0.0.1", resolve); });
+  console.log(`Translation proxy: http://127.0.0.1:${port}/translate\nAllowed origin: ${origin}\nProvider: ${config.translation?.provider ?? "mymemory"}\nKeys are read only from local environment variables. Press Ctrl+C to stop.`);
+  return server;
+}

package/examples/translation.config.json

@@ -0,0 +1,16 @@
+{
+  "version": 1,
+  "input": "./openapi.json",
+  "output": "./src/api",
+  "namespace": "main",
+  "groupBy": "tag",
+  "hooks": true,
+  "translateNames": true,
+  "translation": {
+    "provider": "baidu",
+    "appIdEnv": "BAIDU_TRANSLATE_APP_ID",
+    "apiKeyEnv": "BAIDU_TRANSLATE_SECRET_KEY",
+    "proxyUrl": "http://127.0.0.1:4190/translate"
+  },
+  "controllerNames": {}
+}

package/examples/translation.env.example

@@ -0,0 +1,11 @@
+# Copy this file to .env next to chainspec.config.json, then fill only the chosen provider.
+# Google Cloud Translation Basic v2
+GOOGLE_TRANSLATE_API_KEY=
+
+# Baidu General Translation
+BAIDU_TRANSLATE_APP_ID=
+BAIDU_TRANSLATE_SECRET_KEY=
+
+# Youdao Text Translation v3 authentication
+YOUDAO_TRANSLATE_APP_KEY=
+YOUDAO_TRANSLATE_SECRET_KEY=

package/lib/core/config.d.ts

@@ -1,4 +1,4 @@
-import type { GeneratorOptions } from "./model.js";
+import type { GeneratorOptions, TranslationConfig } from "./model.js";
 /** Shared by the web editor and CLI. Paths resolve relative to the config file. */
 export type ChainSpecConfig = GeneratorOptions & {
     version: 1;
@@ -7,4 +7,7 @@ export type ChainSpecConfig = GeneratorOptions & {
 };
 export declare const DEFAULT_CONFIG: ChainSpecConfig;
 export declare function parseConfig(input: string | unknown): ChainSpecConfig;
+export declare const TRANSLATION_DEFAULTS: Record<TranslationConfig["provider"], TranslationConfig>;
+export declare function parseTranslationConfig(value: unknown): TranslationConfig;
+export declare function parseControllerNames(input: unknown): Record<string, string>;
 export declare function documentURL(input: string): URL;

package/lib/core/config.js

@@ -6,10 +6,12 @@ export const DEFAULT_CONFIG = {
     groupBy: "path",
     hooks: true,
     controllerNames: {},
+    translateNames: true,
+    translation: { provider: "mymemory" },
 };
 const keys = new Set([
     "version", "input", "output", "namespace", "groupBy", "stripPrefix",
-    "controllerNames", "baseUrl", "hooks",
+    "controllerNames", "baseUrl", "hooks", "translateNames", "translation",
 ]);
 export function parseConfig(input) {
     let value = input;
@@ -40,19 +42,68 @@ export function parseConfig(input) {
         throw new Error("groupBy 必须为 path 或 tag");
     if (value.hooks !== undefined && typeof value.hooks !== "boolean")
         throw new Error("hooks 必须为布尔值");
+    if (value.translateNames !== undefined && typeof value.translateNames !== "boolean")
+        throw new Error("translateNames 必须为布尔值");
+    if (value.translation !== undefined)
+        parseTranslationConfig(value.translation);
     if (value.stripPrefix && !value.stripPrefix.startsWith("/"))
         throw new Error("stripPrefix 必须以 / 开头");
     if (value.controllerNames !== undefined) {
-        if (!value.controllerNames || typeof value.controllerNames !== "object" || Array.isArray(value.controllerNames))
-            throw new Error("controllerNames 必须为原分组到英文名称的对象");
-        for (const alias of Object.values(value.controllerNames))
-            if (typeof alias !== "string" || !/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(alias))
-                throw new Error("controllerNames 的值必须为英文标识符，例如 sms");
+        parseControllerNames(value.controllerNames);
     }
     if (/^[a-z][a-z\d+.-]*:/i.test(value.input))
         documentURL(value.input);
     return { ...value, controllerNames: { ...value.controllerNames } };
 }
+export const TRANSLATION_DEFAULTS = {
+    mymemory: { provider: "mymemory" },
+    google: { provider: "google", apiKeyEnv: "GOOGLE_TRANSLATE_API_KEY" },
+    baidu: { provider: "baidu", appIdEnv: "BAIDU_TRANSLATE_APP_ID", apiKeyEnv: "BAIDU_TRANSLATE_SECRET_KEY" },
+    youdao: { provider: "youdao", appIdEnv: "YOUDAO_TRANSLATE_APP_KEY", apiKeyEnv: "YOUDAO_TRANSLATE_SECRET_KEY" },
+};
+export function parseTranslationConfig(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error("translation 必须为对象");
+    const v = value;
+    for (const key of Object.keys(v))
+        if (!["provider", "apiKeyEnv", "appIdEnv", "proxyUrl"].includes(key))
+            throw new Error("翻译配置仅保存 provider、环境变量名和 proxyUrl；真实密钥请放入环境变量");
+    if (typeof v.provider !== "string" || !Object.hasOwn(TRANSLATION_DEFAULTS, v.provider))
+        throw new Error("翻译服务需为 mymemory、google、baidu 或 youdao");
+    for (const key of ["apiKeyEnv", "appIdEnv"])
+        if (v[key] !== undefined && (typeof v[key] !== "string" || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(v[key])))
+            throw new Error(`${key} 需为环境变量名称`);
+    if (v.proxyUrl !== undefined) {
+        if (typeof v.proxyUrl !== "string")
+            throw new Error("proxyUrl 需为 HTTP(S) 地址");
+        documentURL(v.proxyUrl);
+    }
+    return { ...TRANSLATION_DEFAULTS[v.provider], ...v };
+}
+export function parseControllerNames(input) {
+    if (typeof input === "string") {
+        if (new TextEncoder().encode(input).length > 8 * 1024 * 1024)
+            throw new Error("映射文件最大 8 MiB");
+        try {
+            input = JSON.parse(input);
+        }
+        catch {
+            throw new Error("分组映射必须是有效 JSON 对象");
+        }
+    }
+    if (!input || typeof input !== "object" || Array.isArray(input))
+        throw new Error("controllerNames 必须为原分组到英文名称的对象");
+    const entries = Object.entries(input);
+    if (entries.length > 5000)
+        throw new Error("最多 5000 条分组映射");
+    for (const [tag, alias] of entries) {
+        if (!tag.trim())
+            throw new Error("请填写映射的原分组名称");
+        if (typeof alias !== "string" || !/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(alias))
+            throw new Error("controllerNames 的值必须为英文标识符，例如 sms");
+    }
+    return Object.fromEntries(entries);
+}
 export function documentURL(input) {
     let url;
     try {

package/lib/core/index.d.ts

@@ -1,8 +1,13 @@
 import type { GeneratorOptions, GeneratedProject } from "./model.js";
-export type { GeneratorOptions, GeneratedProject, Diagnostic, Operation, } from "./model.js";
+import { type TranslationControls } from "./translate.js";
+export type { TranslationConfig, GeneratorOptions, GeneratedProject, Diagnostic, Operation, } from "./model.js";
 export { MAX_BYTES, MAX_OPERATIONS } from "./model.js";
-export { parseConfig, DEFAULT_CONFIG } from "./config.js";
+export { parseConfig, parseControllerNames, parseTranslationConfig, TRANSLATION_DEFAULTS, DEFAULT_CONFIG } from "./config.js";
+export { resolveControllerNames, translateWithMyMemory, englishControllerName, TranslationError, readTranslationResponse } from "./translate.js";
+export type { TranslationControls } from "./translate.js";
 export type { ChainSpecConfig } from "./config.js";
 export { fetchDocument } from "./source.js";
-export declare const VERSION = "2.1.0";
+export declare const VERSION = "2.2.0";
 export declare function generateSDK(input: string | Record<string, any>, options?: GeneratorOptions): GeneratedProject;
+/** Async opt-in API; the synchronous generateSDK always remains offline. */
+export declare function generateSDKAsync(input: string | Record<string, any>, options?: GeneratorOptions, controls?: TranslationControls): Promise<GeneratedProject>;

package/lib/core/index.js

@@ -1,10 +1,12 @@
 import { parseDocument, normalize } from "./parse.js";
 import { createSchemaWriter } from "./schema.js";
 import { RUNTIME_SOURCE, HOOKS_SOURCE, RUNTIME_LICENSE } from "./templates.js";
+import { resolveControllerNames } from "./translate.js";
 export { MAX_BYTES, MAX_OPERATIONS } from "./model.js";
-export { parseConfig, DEFAULT_CONFIG } from "./config.js";
+export { parseConfig, parseControllerNames, parseTranslationConfig, TRANSLATION_DEFAULTS, DEFAULT_CONFIG } from "./config.js";
+export { resolveControllerNames, translateWithMyMemory, englishControllerName, TranslationError, readTranslationResponse } from "./translate.js";
 export { fetchDocument } from "./source.js";
-export const VERSION = "2.1.0";
+export const VERSION = "2.2.0";
 const q = JSON.stringify;
 const banner = "// Generated by ChainSpec. Do not edit; regenerate from your OpenAPI document.\n";
 export function generateSDK(input, options = {}) {
@@ -103,6 +105,12 @@ export function generateSDK(input, options = {}) {
         "client.ts": client(false),
         "index.ts": `export {createAPI,type API} from './client.js';\nexport {ApiError,defaultRequest} from './runtime.js';\nexport type {ClientConfig,RequestContext,TransportResponse,RequestAdapter,RequestOptions,Endpoint} from './runtime.js';\nexport type {Schemas,InputSchemas,OutputSchemas,Operations} from './types.js';\n`,
     };
+    // Cache only supplied/successfully translated names, never temporary path fallbacks.
+    const controllerNames = { ...options.controllerNames };
+    for (const op of operations)
+        if (Object.hasOwn(controllerNames, op.originalController))
+            controllerNames[op.originalController] = op.controller;
+    files["controller-names.json"] = JSON.stringify(controllerNames, null, 2);
     if (options.hooks !== false) {
         files["hooks.ts"] = HOOKS_SOURCE;
         files["react.ts"] =
@@ -126,7 +134,7 @@ export function generateSDK(input, options = {}) {
     const first = operations.find((o) => o.method === "GET") ?? operations[0];
     const access = `API.${namespace}[${q(first.controller)}][${q(first.name)}]`;
     files["README.md"] =
-        `# Generated SDK\n\nGenerated locally with ChainSpec ${VERSION}. Copy these files into your TypeScript project. No runtime code evaluation or request is performed by the generator.\n\n## Setup\n\nNode22+ or a browser with Fetch, Headers, FormData, Blob. TypeScript moduleResolution Bundler or NodeNext; .js imports resolve to the corresponding .ts sources.\n\nPlain SDK: import {createAPI} from './index.js'. No React/SWR dependency.\n\n${options.hooks === false ? "" : "React SDK: npm install swr@^2.5.1 react@^19.3.1, then import {createReactAPI} from './react.js'. Use the returned API as a module-level singleton (or memoize it per Provider/SSR request). Do not create clients on every render.\n\n"}## Calls\n\n\`\`\`ts\nimport {createAPI} from './index.js';\nconst API=createAPI({baseUrl:${q(baseUrl)},cacheScope:()=> 'tenant:user:auth-revision'});\n// Inspect generated Operations params/body before calling:\n// ${access}.request(params${first.body ? ", body" : ""}, options);\n\`\`\`\n\n.request() returns the documented response body. The first params object contains path/query/cookies. With a documented request body: request(params, body, options). Without one: request(params?, options). Headers are options.headers (standard HeadersInit) and may also be set globally or by beforeRequest. Empty params are {} when a body is present. Operations exposes params/body/headers/output types. Required arguments are required in TypeScript and checked for presence by the default runtime. Schema validation is NOT performed. Missing response schemas are unknown. JS numbers can lose int64 precision: ask your server for strings if required.\n\nGET/HEAD .useRequest(params, {enabled,headers,signal,swr}) reads with SWR; null params or enabled:false pauses it. If a query operation documents a body, use the same three positions as request. Other methods .useRequest(params, body, {headers,signal,swr}) (also .useMutation) bind params and an optional body, never send automatically. trigger() uses the bound body; trigger(body) supplies or overrides it. If a required body was not bound, TypeScript requires trigger(body). For operations without a body use .useRequest(params, options) then trigger(). Trigger options, such as throwOnError, are its second argument. Hook options are flat: headers/signal/interceptors are alongside swr, not under request. Hooks must be called unconditionally at React component/custom-hook top level. HEAD returns no body in Fetch.\n\nCache keys isolate client instances, base URL, operation, inputs, request headers and cacheScope. Change cacheScope after switching users/tenants or changing authorization within one client. Do not put tokens in cacheScope. Logout should also clear your SWR Provider cache. Request interceptors do not automatically change cache keys.\n\n## Extension points\n\n- request: async context => ({data,status,headers:new Headers()}) replaces the entire Fetch transport. context includes URL, method, headers, structured body, mediaType, operation and AbortSignal. Custom adapters must preserve the declared response shape; returning an Axios response unchanged is NOT compatible (normalize response.headers).\n- beforeRequest: async context => context (or void); global handlers run before per-call handlers. Add auth headers, tracing, or cancellation here.\n- afterResponse: async (response,context) => response (or void), for successful responses only. Unwrapping changes the schema contract; do not unwrap unless the server schema already describes the unwrapped body.\n- onError: async (error,context) => void; errors are rethrown. Non-2xx status becomes ApiError with status/data/headers. Network and AbortError are preserved. No automatic retry in .request(). SWR has its own configurable retries.\n\nSupported query serialization: form (arrays and flat objects), spaceDelimited, pipeDelimited, flat deepObject. Path/header simple serialization; header objects and nested query objects need a custom serializer. Cookie parameters require a custom Node request adapter (Fetch in browsers cannot set Cookie headers). JSON, flat multipart and URL-encoded bodies supported; nested forms need a custom adapter. JSON-schema constraints, auth schemes, oneOf exclusivity, server variables, parameter serialization and streaming may need application validation.\n\nThe generator supports local refs, not remote refs. Review manifest.json diagnostics, media choices and operation names. Do not add this SDK or its spec to a public repository without checking that disclosure is intended.\n`;
+        `# Generated SDK\n\nGenerated locally with ChainSpec ${VERSION}. Copy these files into your TypeScript project. The generator never evaluates SDK code or sends business API requests. Optional translation only sends missing group names.\n\n## Setup\n\nNode22+ or a browser with Fetch, Headers, FormData, Blob. TypeScript moduleResolution Bundler or NodeNext; .js imports resolve to the corresponding .ts sources.\n\nPlain SDK: import {createAPI} from './index.js'. No React/SWR dependency.\n\n${options.hooks === false ? "" : "React SDK: npm install swr@^2.5.1 react@^19.3.1, then import {createReactAPI} from './react.js'. Use the returned API as a module-level singleton (or memoize it per Provider/SSR request). Do not create clients on every render.\n\n"}## Calls\n\n\`\`\`ts\nimport {createAPI} from './index.js';\nconst API=createAPI({baseUrl:${q(baseUrl)},cacheScope:()=> 'tenant:user:auth-revision'});\n// Inspect generated Operations params/body before calling:\n// ${access}.request(params${first.body ? ", body" : ""}, options);\n\`\`\`\n\n.request() returns the documented response body. The first params object contains path/query/cookies. With a documented request body: request(params, body, options). Without one: request(params?, options). Headers are options.headers (standard HeadersInit) and may also be set globally or by beforeRequest. Empty params are {} when a body is present. Operations exposes params/body/headers/output types. Required arguments are required in TypeScript and checked for presence by the default runtime. Schema validation is NOT performed. Missing response schemas are unknown. JS numbers can lose int64 precision: ask your server for strings if required.\n\nGET/HEAD .useRequest(params, {enabled,headers,signal,swr}) reads with SWR; null params or enabled:false pauses it. If a query operation documents a body, use the same three positions as request. Other methods .useRequest(params, body, {headers,signal,swr}) (also .useMutation) bind params and an optional body, never send automatically. trigger() uses the bound body; trigger(body) supplies or overrides it. If a required body was not bound, TypeScript requires trigger(body). For operations without a body use .useRequest(params, options) then trigger(). Trigger options, such as throwOnError, are its second argument. Hook options are flat: headers/signal/interceptors are alongside swr, not under request. Hooks must be called unconditionally at React component/custom-hook top level. HEAD returns no body in Fetch.\n\nCache keys isolate client instances, base URL, operation, inputs, request headers and cacheScope. Change cacheScope after switching users/tenants or changing authorization within one client. Do not put tokens in cacheScope. Logout should also clear your SWR Provider cache. Request interceptors do not automatically change cache keys.\n\n## Extension points\n\n- request: async context => ({data,status,headers:new Headers()}) replaces the entire Fetch transport. context includes URL, method, headers, structured body, mediaType, operation and AbortSignal. Custom adapters must preserve the declared response shape; returning an Axios response unchanged is NOT compatible (normalize response.headers).\n- beforeRequest: async context => context (or void); global handlers run before per-call handlers. Add auth headers, tracing, or cancellation here.\n- afterResponse: async (response,context) => response (or void), for successful responses only. Unwrapping changes the schema contract; do not unwrap unless the server schema already describes the unwrapped body.\n- onError: async (error,context) => void; errors are rethrown. Non-2xx status becomes ApiError with status/data/headers. Network and AbortError are preserved. No automatic retry in .request(). SWR has its own configurable retries.\n\nSupported query serialization: form (arrays and flat objects), spaceDelimited, pipeDelimited, flat deepObject. Path/header simple serialization; header objects and nested query objects need a custom serializer. Cookie parameters require a custom Node request adapter (Fetch in browsers cannot set Cookie headers). JSON, flat multipart and URL-encoded bodies supported; nested forms need a custom adapter. JSON-schema constraints, auth schemes, oneOf exclusivity, server variables, parameter serialization and streaming may need application validation.\n\nThe generator supports local refs, not remote refs. Review manifest.json diagnostics, media choices and operation names. Do not add this SDK or its spec to a public repository without checking that disclosure is intended.\n`;
     diagnostics.push({
         level: "info",
         code: "static-types",
@@ -145,5 +153,17 @@ export function generateSDK(input, options = {}) {
         schemaCount,
         diagnostics,
         files,
+        controllerNames,
     };
 }
+/** Async opt-in API; the synchronous generateSDK always remains offline. */
+export async function generateSDKAsync(input, options = {}, controls = {}) {
+    const prepared = await resolveControllerNames(input, options, controls);
+    controls.signal?.throwIfAborted();
+    const project = generateSDK(input, { ...options, controllerNames: prepared.controllerNames });
+    project.diagnostics.push(...prepared.diagnostics);
+    const manifest = JSON.parse(project.files["manifest.json"]);
+    manifest.diagnostics = project.diagnostics;
+    project.files["manifest.json"] = JSON.stringify(manifest, null, 2);
+    return project;
+}

package/lib/core/model.d.ts

@@ -12,6 +12,15 @@ export type GeneratorOptions = {
     controllerNames?: Record<string, string>;
     baseUrl?: string;
     hooks?: boolean;
+    translateNames?: boolean;
+    translation?: TranslationConfig;
+};
+export type TranslationConfig = {
+    provider: "mymemory" | "google" | "baidu" | "youdao";
+    apiKeyEnv?: string;
+    appIdEnv?: string;
+    /** Browser-only proxy; CLI talks directly to the configured official provider. */
+    proxyUrl?: string;
 };
 export type Parameter = {
     name: string;
@@ -26,6 +35,7 @@ export type Operation = {
     method: string;
     path: string;
     controller: string;
+    originalController: string;
     name: string;
     originalId?: string;
     tags: string[];
@@ -51,6 +61,7 @@ export type GeneratedProject = {
     schemaCount: number;
     diagnostics: Diagnostic[];
     files: Record<string, string>;
+    controllerNames: Record<string, string>;
 };
 export declare const MAX_BYTES: number;
 export declare const MAX_OPERATIONS = 5000;

package/lib/core/parse.js

@@ -93,7 +93,8 @@ export function normalize(doc, options, diagnostics) {
                 "default";
             const originalGroup = op["x-sdk-controller"] ??
                 (options.groupBy === "tag" ? (tags[0] ?? pathGroup) : pathGroup);
-            const alias = options.controllerNames?.[originalGroup];
+            const alias = Object.hasOwn(options.controllerNames ?? {}, originalGroup)
+                ? options.controllerNames[originalGroup] : undefined;
             if (alias !== undefined && !/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(alias))
                 throw new Error(`分组「${originalGroup}」的别名需为英文标识符`);
             let controller = assignedGroups.get(originalGroup) ?? nameOf(alias ?? (/^[\x00-\x7F]+$/.test(originalGroup) ? originalGroup : pathGroup), "group_" + hash(originalGroup));
@@ -324,6 +325,7 @@ export function normalize(doc, options, diagnostics) {
                 method: method.toUpperCase(),
                 path,
                 controller,
+                originalController: originalGroup,
                 name,
                 originalId,
                 tags,

package/lib/core/translate.d.ts

@@ -0,0 +1,22 @@
+import type { Diagnostic, GeneratorOptions, Json } from "./model.js";
+export type TranslationControls = {
+    signal?: AbortSignal;
+    /** Optional adapter for self-hosted translation or offline tests. */
+    translate?: (name: string, signal?: AbortSignal) => Promise<string>;
+    onProgress?: (progress: {
+        current: number;
+        total: number;
+    }) => void;
+};
+/** Only these locally authored messages may be shown; provider errors may contain credentials. */
+export declare class TranslationError extends Error {
+}
+export declare function englishControllerName(text: string): string;
+/** GET only: never contributes source text to a translation memory. */
+export declare function translateWithMyMemory(name: string, signal?: AbortSignal): Promise<string>;
+export declare function translateViaProxy(name: string, options: GeneratorOptions, signal?: AbortSignal): Promise<string>;
+export declare function readTranslationResponse(response: Response): Promise<any>;
+export declare function resolveControllerNames(input: string | Json, options?: GeneratorOptions, controls?: TranslationControls): Promise<{
+    controllerNames: Record<string, string>;
+    diagnostics: Diagnostic[];
+}>;

package/lib/core/translate.js

@@ -0,0 +1,150 @@
+import { normalize, parseDocument } from "./parse.js";
+import { parseControllerNames, parseTranslationConfig } from "./config.js";
+/** Only these locally authored messages may be shown; provider errors may contain credentials. */
+export class TranslationError extends Error {
+}
+export function englishControllerName(text) {
+    const decoded = text.replace(/&(amp|quot|apos|lt|gt|nbsp|#39);/g, (entity) => ({ "&amp;": "&", "&quot;": '"', "&apos;": "'", "&#39;": "'", "&lt;": "<", "&gt;": ">", "&nbsp;": " " })[entity]);
+    if (decoded.length > 200 || /[^\x20-\x7E]/.test(decoded) || !/[A-Za-z]/.test(decoded))
+        throw new Error("翻译结果不是有效英文名称");
+    const words = decoded.replace(/([A-Z]+)([A-Z][a-z])/g, "$1 $2")
+        .replace(/([a-z0-9])([A-Z])/g, "$1 $2").split(/[^A-Za-z0-9]+/).filter(Boolean);
+    let name = words.map((word, i) => {
+        const lower = word.toLowerCase();
+        return i ? lower[0].toUpperCase() + lower.slice(1) : lower;
+    }).join("");
+    if (!/^[A-Za-z]/.test(name))
+        name = "_" + name;
+    if (["constructor", "prototype", "__proto__", "then"].includes(name))
+        name += "Api";
+    return name;
+}
+/** GET only: never contributes source text to a translation memory. */
+export async function translateWithMyMemory(name, signal) {
+    if (new TextEncoder().encode(name).length > 500)
+        throw new Error("单个分组名称超过免费接口 500 字节限制");
+    const url = new URL("https://api.mymemory.translated.net/get");
+    url.searchParams.set("q", name);
+    url.searchParams.set("langpair", "zh-CN|en");
+    const response = await fetch(url, {
+        credentials: "omit", referrerPolicy: "no-referrer",
+        signal: AbortSignal.any([AbortSignal.timeout(10_000), ...(signal ? [signal] : [])]),
+    });
+    if (!response.ok) {
+        await response.body?.cancel();
+        throw new Error("免费翻译服务暂不可用或已限流");
+    }
+    if (!response.body)
+        throw new Error("翻译服务返回为空");
+    const reader = response.body.getReader();
+    const chunks = [];
+    let bytes = 0;
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            bytes += value.byteLength;
+            if (bytes > 128 * 1024)
+                throw new Error("翻译响应过大");
+            chunks.push(value);
+        }
+    }
+    finally {
+        await reader.cancel().catch(() => { });
+        reader.releaseLock();
+    }
+    const joined = new Uint8Array(bytes);
+    let offset = 0;
+    for (const chunk of chunks) {
+        joined.set(chunk, offset);
+        offset += chunk.length;
+    }
+    const data = JSON.parse(new TextDecoder().decode(joined));
+    if (data.quotaFinished || Number(data.responseStatus) !== 200 || typeof data.responseData?.translatedText !== "string")
+        throw new Error("免费翻译额度已用完或服务暂不可用");
+    return data.responseData.translatedText;
+}
+export async function translateViaProxy(name, options, signal) {
+    const config = parseTranslationConfig(options.translation ?? { provider: "mymemory" });
+    if (!config.proxyUrl)
+        throw new TranslationError("该翻译服务需要配置浏览器代理地址；可先运行 chainspec translate-server，或直接使用 CLI 生成。");
+    const response = await fetch(config.proxyUrl, {
+        method: "POST", credentials: "omit", referrerPolicy: "no-referrer", redirect: "error",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ text: name, provider: config.provider }),
+        signal: AbortSignal.any([AbortSignal.timeout(15_000), ...(signal ? [signal] : [])]),
+    });
+    const data = await readTranslationResponse(response);
+    if (!response.ok || typeof data.translatedText !== "string")
+        throw new TranslationError("翻译代理调用失败，请检查代理服务、环境变量密钥和所选服务是否一致。");
+    return data.translatedText;
+}
+export async function readTranslationResponse(response) {
+    if (!response.body)
+        throw new Error("Empty translation response");
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let bytes = 0, text = "";
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            bytes += value.byteLength;
+            if (bytes > 128 * 1024)
+                throw new Error("Translation response too large");
+            text += decoder.decode(value, { stream: true });
+        }
+        text += decoder.decode();
+        return JSON.parse(text);
+    }
+    finally {
+        await reader.cancel().catch(() => { });
+        reader.releaseLock();
+    }
+}
+export async function resolveControllerNames(input, options = {}, controls = {}) {
+    const controllerNames = parseControllerNames(options.controllerNames ?? {});
+    const diagnostics = [];
+    if (options.translateNames === false)
+        return { controllerNames, diagnostics };
+    const operations = normalize(parseDocument(input), options, []).operations;
+    const missing = [...new Set(operations.map((op) => op.originalController))]
+        .filter((name) => /\p{Script=Han}/u.test(name) && !Object.hasOwn(controllerNames, name)).sort();
+    const config = parseTranslationConfig(options.translation ?? { provider: "mymemory" });
+    const translate = controls.translate ?? (config.provider === "mymemory"
+        ? translateWithMyMemory : (name, signal) => translateViaProxy(name, options, signal));
+    let characters = 0;
+    for (let i = 0; i < missing.length; i++) {
+        controls.signal?.throwIfAborted();
+        const name = missing[i];
+        if (i >= 100 || characters + name.length > 5000) {
+            diagnostics.push({ level: "warning", code: "translation-limit", message: "本次自动翻译达到分组/字符上限，剩余分组按路径命名；成功结果已缓存。" });
+            break;
+        }
+        controls.onProgress?.({ current: i + 1, total: missing.length });
+        if (new TextEncoder().encode(name).length > 500) {
+            diagnostics.push({ level: "warning", code: "translation-name-too-long", message: "分组名称超过自动翻译长度限制，已按路径命名。", location: name });
+            continue;
+        }
+        characters += name.length;
+        let translated;
+        try {
+            translated = await translate(name, controls.signal);
+        }
+        catch (error) {
+            controls.signal?.throwIfAborted();
+            diagnostics.push({ level: "warning", code: "translation-unavailable", message: error instanceof TranslationError
+                    ? error.message : "翻译服务不可用、鉴权失败或额度用完；已保留成功缓存，其余分组按路径命名。", location: name });
+            break;
+        }
+        try {
+            controllerNames[name] = englishControllerName(translated);
+        }
+        catch {
+            diagnostics.push({ level: "warning", code: "translation-invalid", message: "服务未返回有效英文名称，已按路径命名；下次可以重试。", location: name });
+        }
+    }
+    return { controllerNames, diagnostics };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@batype/chainspec",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "Generate typed chainable TypeScript SDKs and SWR hooks from OpenAPI JSON, locally.",
   "type": "module",
   "license": "MIT",
@@ -11,6 +11,10 @@
     ".": {
       "types": "./lib/core/index.d.ts",
       "import": "./lib/core/index.js"
+    },
+    "./node": {
+      "types": "./bin/translation-provider.d.ts",
+      "import": "./bin/translation-provider.mjs"
     }
   },
   "bin": {
@@ -21,7 +25,8 @@
     "bin/",
     "README.md",
     "LICENSE",
-    "THIRD-PARTY-LICENSES.txt"
+    "THIRD-PARTY-LICENSES.txt",
+    "examples/"
   ],
   "scripts": {
     "templates": "node scripts/embed-templates.mjs",