@yxw007/translate 0.4.0 → 0.5.0

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2024 Potter.yan
-
-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.
+MIT License
+
+Copyright (c) 2024 Potter.yan
+
+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

@@ -53,7 +53,7 @@ English | [简体中文](./README_zh-CN.md)
   yarn add @yxw007/translate
   ```
 
-- pnpm 
+- pnpm
 
   ```bash
   pnpm i @yxw007/translate
@@ -75,7 +75,7 @@ English | [简体中文](./README_zh-CN.md)
 
 - Translation examples
   ```typescript
-  translator.addEngine(engines.google());
+  translator.addEngine(engines.google);
   const res1 = await translator.translate("hello", { from: "en", to: "zh" });
   console.log(res1);
 
@@ -90,9 +90,9 @@ English | [简体中文](./README_zh-CN.md)
   ```
 - Language detection examples
   ```typescript
-  translator.addEngine(engines.google());
+  translator.addEngine(engines.google);
   const res1 = await translator.checkLanguage("hello", { engine:"google" });
-  console.log("en");
+  console.log(res1);
 
   ```
   Output results
@@ -102,13 +102,13 @@ English | [简体中文](./README_zh-CN.md)
 
 ### Browser
 
-use jsDelivr CDN 
+use jsDelivr CDN
 
 - `development`
   ```html
   <script src="https://cdn.jsdelivr.net/npm/@yxw007/translate@0.0.7/dist/browser/index.umd.js"></script>
   ```
-  
+
 - `production`
 
   ```html
@@ -130,7 +130,7 @@ use jsDelivr CDN
     <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);
       })();
@@ -142,7 +142,7 @@ use jsDelivr CDN
   ```
 
 
-## 📚 API 
+## 📚 API
 
 ### Translator
 
@@ -166,6 +166,12 @@ class Translator {
   removeEngine(engineName: string) {
    ...
   }
+  getFromLanguages(engineName: string) {
+   ...
+  }
+  getToLanguages(engineName: string) {
+   ...
+  }
   translate<T extends Engines>(text: string | string[], options: TranslateOptions<T>) {
     ...
   }
@@ -179,7 +185,11 @@ Add a translation engine to transitorion engine to translator
 ```typescript
 type Engine = {
   name: string;
-  translate<T extends Engines>(text: string | string[], options: TranslateOptions<T>) {
+  getFromLanguages(): Record<string, string>;
+  getToLanguages(): Record<string, string>;
+  normalFromLanguage(language?: string): string;
+  normalToLanguage(language?: string): string;
+  translate(text: string | string[], options: EngineTranslateOptions) {
 };
 ```
 
@@ -191,6 +201,15 @@ You can pass a text or pass a text array, which will return a translated ```Prom
 translate<T extends Engines>(text: string | string[], options: TranslateOptions<T>)
 ```
 
+#### `getFromLanguages` / `getToLanguages`
+
+Read the language list for the specified engine.
+
+```typescript
+translator.getFromLanguages("google")
+translator.getToLanguages("google")
+```
+
 #### TranslateOptions
 
 ```typescript
@@ -209,17 +228,60 @@ export interface TranslateOptions {
 }
 ```
 
-> Note: To learn more about the support of each engine language, go to the following directory to view the corresponding configurations
-
-- 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)
+> Note: Each engine now maintains its own `from`/`to` language configuration. You can inspect the engine-scoped configuration under `src/language/engines/*`.
 
 ### Each translation of Engine's Option
 
 #### BaseEngineOption
 
 ```typescript
-interface BaseEngineOption {}
+interface BaseEngineOption {
+  fromLanguages?: Record<string, string>;
+  toLanguages?: Record<string, string>;
+}
+```
+
+> `fromLanguages` / `toLanguages` are only initialization options for engine factories that need custom language tables. They are not exposed as public fields on the engine instance.
+
+#### Custom 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);
+```
+
+Built-in engines are directly referenced:
+
+```typescript
+translator.addEngine(engines.google);
 ```
 
 #### AzureEngineOption
@@ -250,7 +312,7 @@ interface AmazonEngineOption extends BaseEngineOption{
 
 - Related document：https://docs.aws.amazon.com/translate/latest/dg/what-is.html
 - Related library：https://www.npmjs.com/package/@aws-sdk/client-translate
- 
+
 #### BaiduEngineOption
 
 ```typescript
@@ -328,7 +390,7 @@ export interface TencentEngineOption extends BaseEngineOption {
 }
 ```
 
-> Description: Option Param Please obtain it from the corresponding platform. 
+> Description: Option Param Please obtain it from the corresponding platform.
 - Related documentation：https://console.cloud.tencent.com/cam/capi
 
 - Region Configuration table
@@ -374,6 +436,9 @@ export interface TencentEngineOption extends BaseEngineOption {
       const base = "https://translate.yandex.net/api/v1.5/tr.json/translate";
       return {
         name: "yandex",
+         async checkLanguage<T extends Engines>(text: string): Promise<string> {
+          //TODO: This can be done with translate, in which case the target language configuration is reused.
+        },
         async translate<T extends Engines>(text: string | string[], opts: EngineTranslateOptions<T>) {
           const { from, to } = opts;
           if (!Array.isArray(text)) {
@@ -393,7 +458,7 @@ export interface TencentEngineOption extends BaseEngineOption {
     }
     ```
   - Add the plugin to Engines(Location:```/src/engines/index.ts```)
-  
+
     ```typescript
     import { xx } from "./xx";
     export const engines = {
@@ -407,14 +472,14 @@ export interface TencentEngineOption extends BaseEngineOption {
     } as const;
     ```
   - Add the origin language configuration supported by the engine
- 
+
     ```typescript
     //Note: If the origin and target languages are the same, you can directly use the target language to configure them, otherwise please configure them separately
-    //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,
       ...
@@ -436,9 +501,9 @@ export interface TencentEngineOption extends BaseEngineOption {
     ```
 
   - Add the target language that is supported by the engine
- 
+
     ```typescript
-    //src/language/target/index.ts  
+    //src/language/target/index.ts
     import azure from "./azure";
     ...
     import xxx from "./amazon";

package/README_zh-CN.md

@@ -56,7 +56,7 @@ Translate 是一个支持多翻译引擎的翻译工具库，它提供了一套
   yarn add @yxw007/translate
   ```
 
-- pnpm 
+- pnpm
 
   ```bash
   pnpm i @yxw007/translate
@@ -78,7 +78,7 @@ Translate 是一个支持多翻译引擎的翻译工具库，它提供了一套
 
 - 翻译例子
   ```typescript
-  translator.addEngine(engines.google());
+  translator.addEngine(engines.google);
   const res1 = await translator.translate("hello", { from: "en", to: "zh" });
   console.log(res1);
 
@@ -93,9 +93,9 @@ Translate 是一个支持多翻译引擎的翻译工具库，它提供了一套
   ```
 - 语言检测例子
   ```typescript
-  translator.addEngine(engines.google());
+  translator.addEngine(engines.google);
   const res1 = await translator.checkLanguage("hello", { engine:"google" });
-  console.log("en");
+  console.log(res1);
   ```
 
   输出结果
@@ -105,13 +105,13 @@ Translate 是一个支持多翻译引擎的翻译工具库，它提供了一套
 
 ### 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 +133,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 +144,7 @@ Translate 是一个支持多翻译引擎的翻译工具库，它提供了一套
 
   ```
 
-## 📚 API 
+## 📚 API
 
 ### Translator
 
@@ -168,6 +168,12 @@ class Translator {
   removeEngine(engineName: string) {
    ...
   }
+  getFromLanguages(engineName: string) {
+   ...
+  }
+  getToLanguages(engineName: string) {
+   ...
+  }
   translate<T extends Engines>(text: string | string[], options: TranslateOptions<T>) {
     ...
   }
@@ -181,7 +187,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 +203,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 +230,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
@@ -252,7 +314,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
@@ -330,7 +392,7 @@ export interface TencentEngineOption extends BaseEngineOption {
 }
 ```
 
-> 说明：option param 请从对应平台获取。 
+> 说明：option param 请从对应平台获取。
 - 相关文档：https://console.cloud.tencent.com/cam/capi
 
 - region 配置表
@@ -376,6 +438,9 @@ export interface TencentEngineOption extends BaseEngineOption {
       const base = "https://translate.yandex.net/api/v1.5/tr.json/translate";
       return {
         name: "xx",
+        async checkLanguage<T extends Engines>(text: string): Promise<string> {
+          //TODO: 可以用translate来实现，这样的话就复用target语言配置
+        },
         async translate<T extends Engines>(text: string | string[], opts: EngineTranslateOptions<T>) {
           const { from, to } = opts;
           if (!Array.isArray(text)) {
@@ -395,7 +460,7 @@ export interface TencentEngineOption extends BaseEngineOption {
     }
     ```
   - 将插件添加至engines(位置：```/src/engines/index.ts```)
-  
+
     ```typescript
     import { xxx } from "./xxx";
     export const engines = {
@@ -409,14 +474,14 @@ export interface TencentEngineOption extends BaseEngineOption {
     } 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,
       ...
@@ -438,9 +503,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";
@@ -463,7 +528,7 @@ export interface TencentEngineOption extends BaseEngineOption {
       xxx: ValuesOf<typeof xxx>;
     };
   ```
-  
+
 - 打包
   ```bash
   pnpm build