@yxw007/translate 0.4.1 → 1.0.0

package/README_zh-CN.md

@@ -11,6 +11,7 @@
 Translate 是一个支持多翻译引擎的翻译工具库，它提供了一套简单的api，让你可以轻松将一种语种翻译成另外一种语种。
 
 ## ❓ 为什么需要Translate?
+
 1. 市面上不少翻译工具库，基本都不太维护了
 2. 不是ts写的，使用时提示不够友好
 3. 功能单一，不支持批量翻译 or 只支持一种翻译引擎
@@ -19,6 +20,7 @@ Translate 是一个支持多翻译引擎的翻译工具库，它提供了一套
 > 说明：Translate 全部帮你搞定以上问题，未来将拓展更多内容
 
 ## ✨ 特点
+
 - 🌐 **多环境支持**：Node环境、浏览器环境
 - ✨ **简单易用**：提供了简洁的API，就可以轻松帮你翻译
 - 🌍 **支持多翻译引擎**：Google、Azure Translate、Amazon Translate、Deepl、Baidu、OpenAI等（未来将拓展更多）
@@ -28,6 +30,8 @@ Translate 是一个支持多翻译引擎的翻译工具库，它提供了一套
 
 > **特别提醒：虽然库已支持浏览器环境使用，但是请仅使用google engine翻译(google不需要key)，使用其他翻译engine 需要配置key，在前端使用会导致key泄露，千万不要这么做**
 
+> 浏览器产物已排除 Node 专用工具，例如文件系统辅助方法。浏览器环境请仅使用适合在前端暴露的翻译能力。
+
 ## 💻翻译引擎，集成情况
 
 | name             | 支持 | 描述                                                                       |
@@ -41,6 +45,39 @@ Translate 是一个支持多翻译引擎的翻译工具库，它提供了一套
 | tencent          | ✔    | 已投产，可以正常使用                                                       |
 | yandex           |      | 由于我没有平台支持的银行账号，所以未调通（欢迎有条件的朋友帮忙调通，感谢） |
 
+## 🛠 开发命令
+
+当前项目已将 `rollup`、`eslint`、`prettier` 分别替换为 `rolldown`、`oxlint`、`oxfmt`。
+
+```bash
+pnpm build
+pnpm lint
+pnpm lint:fix
+pnpm format
+pnpm format:check
+pnpm test
+```
+
+- `pnpm build`：使用 `rolldown` 构建 Node 与浏览器产物，并用 TypeScript 生成 `.d.ts` 声明文件。
+- `pnpm lint`：执行 `oxlint` 和 `oxfmt --check`。
+- `pnpm lint:fix`：执行 `oxlint --fix` 并用 `oxfmt` 自动格式化代码。
+- `pnpm format`：使用 `oxfmt` 格式化仓库代码。
+- `pnpm test`：运行默认稳定、无需外网的测试。
+
+依赖真实网络和第三方密钥的集成测试默认关闭。如需手动运行，请先设置 `RUN_INTEGRATION_TESTS=true` 再执行 `pnpm test`。
+
+- Bash
+
+  ```bash
+  RUN_INTEGRATION_TESTS=true pnpm test
+  ```
+
+- PowerShell
+
+  ```powershell
+  $env:RUN_INTEGRATION_TESTS = "true"
+  pnpm test
+  ```
 
 ## 🚀 安装
 
@@ -56,7 +93,7 @@ Translate 是一个支持多翻译引擎的翻译工具库，它提供了一套
   yarn add @yxw007/translate
   ```
 
-- pnpm 
+- pnpm
 
   ```bash
   pnpm i @yxw007/translate
@@ -67,18 +104,21 @@ Translate 是一个支持多翻译引擎的翻译工具库，它提供了一套
 ### Node
 
 - ESM
+
   ```typescript
-  import { translator, engines } from "@yxw007/translate"
+  import { translator, engines } from "@yxw007/translate";
   ```
 
 - Commonjs
+
   ```typescript
-  const { translator, engines }  = required("@yxw007/translate")
+  const { translator, engines } = required("@yxw007/translate");
   ```
 
 - 翻译例子
+
   ```typescript
-  translator.addEngine(engines.google());
+  translator.addEngine(engines.google);
   const res1 = await translator.translate("hello", { from: "en", to: "zh" });
   console.log(res1);
 
@@ -87,31 +127,36 @@ Translate 是一个支持多翻译引擎的翻译工具库，它提供了一套
   ```
 
   输出结果
+
   ```bash
   ['你好']
   ["你好", "好的"]
   ```
+
 - 语言检测例子
+
   ```typescript
-  translator.addEngine(engines.google());
-  const res1 = await translator.checkLanguage("hello", { engine:"google" });
+  translator.addEngine(engines.google);
+  const res1 = await translator.checkLanguage("hello", { engine: "google" });
   console.log(res1);
   ```
 
   输出结果
+
   ```bash
   en
   ```
 
 ### Browser
 
-使用 jsDelivr CDN 
+使用 jsDelivr CDN
 
 - `development`
+
   ```html
   <script src="https://cdn.jsdelivr.net/npm/@yxw007/translate@0.0.7/dist/browser/index.umd.js"></script>
   ```
-  
+
 - `production`
 
   ```html
@@ -133,7 +178,7 @@ Translate 是一个支持多翻译引擎的翻译工具库，它提供了一套
     <script>
       (async () => {
         const { engines, translator } = translate;
-        translator.addEngine(engines.google());
+        translator.addEngine(engines.google);
         const res = await translator.translate("hello", { from: "en", to: "zh" });
         console.log(res);
       })();
@@ -144,7 +189,7 @@ Translate 是一个支持多翻译引擎的翻译工具库，它提供了一套
 
   ```
 
-## 📚 API 
+## 📚 API
 
 ### Translator
 
@@ -168,6 +213,12 @@ class Translator {
   removeEngine(engineName: string) {
    ...
   }
+  getFromLanguages(engineName: string) {
+   ...
+  }
+  getToLanguages(engineName: string) {
+   ...
+  }
   translate<T extends Engines>(text: string | string[], options: TranslateOptions<T>) {
     ...
   }
@@ -181,7 +232,11 @@ class Translator {
 ```typescript
 export type Engine = {
   name: string;
-  translate: <T extends Engines>(text: string | string[], opts: EngineTranslateOptions<T>) => Promise<string[]>;
+  getFromLanguages: () => Record<string, string>;
+  getToLanguages: () => Record<string, string>;
+  normalFromLanguage: (language?: string) => string;
+  normalToLanguage: (language?: string) => string;
+  translate: (text: string | string[], opts: EngineTranslateOptions) => Promise<string[]>;
 };
 ```
 
@@ -193,6 +248,15 @@ export type Engine = {
 translate: <T extends Engines>(text: string | string[], opts: EngineTranslateOptions<T>) => Promise<string[]>;
 ```
 
+#### `getFromLanguages` / `getToLanguages`
+
+读取指定 Engine 的语言列表。
+
+```typescript
+translator.getFromLanguages("google");
+translator.getToLanguages("google");
+```
+
 #### TranslateOptions
 
 ```typescript
@@ -211,17 +275,60 @@ export type TranslateOptions<T extends Engines> = {
 };
 ```
 
-> 提示：如需了解各Engine语言支持情况，请到以下目录查看对应配置
-
-- from: [https://github.com/yxw007/translate/blob/master/src/language/origin/index.ts](https://github.com/yxw007/translate/blob/master/src/language/origin/index.ts)
-- to: [https://github.com/yxw007/translate/blob/master/src/language/target/index.ts](https://github.com/yxw007/translate/blob/master/src/language/target/index.ts)
+> 提示：现在每个 Engine 都单独维护自己的 `from`/`to` 语言配置，可直接查看 `src/language/engines/*`。
 
 ### 各翻译Engine的Option
 
 #### BaseEngineOption
 
 ```typescript
-interface BaseEngineOption {}
+interface BaseEngineOption {
+  fromLanguages?: Record<string, string>;
+  toLanguages?: Record<string, string>;
+}
+```
+
+> `fromLanguages` / `toLanguages` 仅用于某些工厂型 engine 初始化时传入自定义语言表，不会作为 engine 实例的公开字段暴露给上层。
+
+#### 自定义 Engine
+
+```typescript
+import { Translator, type Engine } from "@yxw007/translate";
+
+const translator = new Translator();
+
+const fromLanguages = { Auto: "auto", English: "en" };
+const toLanguages = { Chinese: "zh", Japanese: "ja" };
+
+const customEngine: Engine = {
+  name: "custom",
+  getFromLanguages() {
+    return fromLanguages;
+  },
+  getToLanguages() {
+    return toLanguages;
+  },
+  normalFromLanguage(language) {
+    if (!language || language === "auto") return "auto";
+    return fromLanguages[language as keyof typeof fromLanguages] ?? "";
+  },
+  normalToLanguage(language) {
+    if (!language) return "";
+    return toLanguages[language as keyof typeof toLanguages] ?? "";
+  },
+  async translate(text, options) {
+    const list = Array.isArray(text) ? text : [text];
+    return list.map((item) => `[${options.from}->${options.to}] ${item}`);
+  },
+};
+
+translator.addEngine(customEngine);
+```
+
+内置 engine 直接引用即可：
+
+```typescript
+translator.addEngine(engines.google);
 ```
 
 #### AzureEngineOption
@@ -237,11 +344,10 @@ interface AzureEngineOption extends BaseEngineOption {
 
 - 相关文档：[rest-api-guide](https://learn.microsoft.com/zh-cn/azure/ai-services/translator/reference/rest-api-guide?WT.mc_id=Portal-Microsoft_Azure_ProjectOxford)
 
-
 #### AmazonEngineOption
 
 ```typescript
-interface AmazonEngineOption extends BaseEngineOption{
+interface AmazonEngineOption extends BaseEngineOption {
   region: string;
   accessKeyId: string;
   secretAccessKey: string;
@@ -252,7 +358,7 @@ interface AmazonEngineOption extends BaseEngineOption{
 
 - 相关文档：https://docs.aws.amazon.com/translate/latest/dg/what-is.html
 - 相关库：https://www.npmjs.com/package/@aws-sdk/client-translate
- 
+
 #### BaiduEngineOption
 
 ```typescript
@@ -324,34 +430,34 @@ export type OpenAIModel = (typeof OPEN_AI_MODELS)[number];
 
 ```typescript
 export interface TencentEngineOption extends BaseEngineOption {
-	secretId: string;
-	secretKey: string;
-	region?: string;
+  secretId: string;
+  secretKey: string;
+  region?: string;
 }
 ```
 
-> 说明：option param 请从对应平台获取。 
+> 说明：option param 请从对应平台获取。
+
 - 相关文档：https://console.cloud.tencent.com/cam/capi
 
 - region 配置表
-  | 地域                   | 取值             |
+  | 地域 | 取值 |
   | ---------------------- | ---------------- |
-  | 亚太东南（曼谷）       | ap-bangkok       |
-  | 华北地区（北京）       | ap-beijing       |
-  | 西南地区（成都）       | ap-chengdu       |
-  | 西南地区（重庆）       | ap-chongqing     |
-  | 华南地区（广州）       | ap-guangzhou     |
-  | 港澳台地区（中国香港） | ap-hongkong      |
-  | 亚太东北（首尔）       | ap-seoul         |
-  | 华东地区（上海）       | ap-shanghai      |
-  | 华东地区（上海金融）   | ap-shanghai-fsi  |
-  | 华南地区（深圳金融）   | ap-shenzhen-fsi  |
-  | 亚太东南（新加坡）     | ap-singapore     |
-  | 亚太东北（东京）       | ap-tokyo         |
-  | 欧洲地区（法兰克福）   | eu-frankfurt     |
-  | 美国东部（弗吉尼亚）   | na-ashburn       |
-  | 美国西部（硅谷）       | na-siliconvalley |
-
+  | 亚太东南（曼谷） | ap-bangkok |
+  | 华北地区（北京） | ap-beijing |
+  | 西南地区（成都） | ap-chengdu |
+  | 西南地区（重庆） | ap-chongqing |
+  | 华南地区（广州） | ap-guangzhou |
+  | 港澳台地区（中国香港） | ap-hongkong |
+  | 亚太东北（首尔） | ap-seoul |
+  | 华东地区（上海） | ap-shanghai |
+  | 华东地区（上海金融） | ap-shanghai-fsi |
+  | 华南地区（深圳金融） | ap-shenzhen-fsi |
+  | 亚太东南（新加坡） | ap-singapore |
+  | 亚太东北（东京） | ap-tokyo |
+  | 欧洲地区（法兰克福） | eu-frankfurt |
+  | 美国东部（弗吉尼亚） | na-ashburn |
+  | 美国西部（硅谷） | na-siliconvalley |
 
 ## 🤝 贡献
 
@@ -364,8 +470,8 @@ export interface TencentEngineOption extends BaseEngineOption {
   ```
 
 - 添加新Engine
-
   - 添加新平台engine插件
+
     ```typescript
     export interface XXEngineOption extends BaseEngineOption {
       key: string;
@@ -397,8 +503,9 @@ export interface TencentEngineOption extends BaseEngineOption {
       };
     }
     ```
-  - 将插件添加至engines(位置：```/src/engines/index.ts```)
-  
+
+  - 将插件添加至engines(位置：`/src/engines/index.ts`)
+
     ```typescript
     import { xxx } from "./xxx";
     export const engines = {
@@ -408,18 +515,19 @@ export interface TencentEngineOption extends BaseEngineOption {
       baidu,
       deepl,
       openai,
-      xxx
+      xxx,
     } as const;
     ```
+
   - 添加对应Engine支持的origin语言配置
- 
+
     ```typescript
     //说明：如果origin与target语言都一样，那么可以直接用target语言配置即可，否则请单独配置
-    //src/language/origin/index.ts  
+    //src/language/origin/index.ts
     import azure from "../target/azure";
     ...
     import xxx from "../target/xxx"
-    
+
     export const originLanguages = {
       azure: azure,
       ...
@@ -441,9 +549,9 @@ export interface TencentEngineOption extends BaseEngineOption {
     ```
 
   - 添加对应Engine支持的target语言配置
- 
+
     ```typescript
-    //src/language/target/index.ts  
+    //src/language/target/index.ts
     import azure from "./azure";
     ...
     import xxx from "./amazon";
@@ -465,9 +573,14 @@ export interface TencentEngineOption extends BaseEngineOption {
       ...
       xxx: ValuesOf<typeof xxx>;
     };
+    ```
+
+  ```
+
   ```
-  
+
 - 打包
+
   ```bash
   pnpm build
   ```
@@ -478,10 +591,11 @@ export interface TencentEngineOption extends BaseEngineOption {
   ```
 
 > **提示：目前库已可以正常使用，欢迎大家体验、如果你有任何问题和建议都可以提Issue给我反馈。
-如果你感兴趣，特别欢迎你的加入，让我们一起完善好这个工具。
-帮忙点个star⭐，让更多人知道这个工具，感谢大家🙏**
+> 如果你感兴趣，特别欢迎你的加入，让我们一起完善好这个工具。
+> 帮忙点个star⭐，让更多人知道这个工具，感谢大家🙏**
 
 ## 🌹 特别致谢
+
 - [franciscop/translate](https://github.com/franciscop/translate.git)
 
 > 说明：感谢[franciscop/translate](https://github.com/franciscop/translate.git)为我快速实现这个库提供了思路，同时也间接了他的部分代码。非常感谢🙏