@yxw007/translate 0.5.0 → 1.0.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

@@ -9,6 +9,7 @@ English | [简体中文](./README_zh-CN.md)
 ![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/yxw007/translate/ci.yml)
 
 ## ❓ Why do I need translate?
+
 1. a lot of translation tool libraries on the market, basically not very well-maintained
 2. not written by ts, not friendly enough when using the prompts
 3. single function, does not support batch translation Or only support a translation engine
@@ -17,6 +18,7 @@ English | [简体中文](./README_zh-CN.md)
 > Note: Translate helps you to solve all the above problems, and will expand more in the future!
 
 ## ✨ Features
+
 - 🌐 **Multi-environment support**: Node environment, browser environment
 - ✨ **Easy to use**: provides a concise API, you can easily help you to translate
 - 🌍 **Multi-translation engine support**: Google, Azure Translate, Amazon Translate, Deepl, Baidu, OpenAI, etc. (will expand more in the future)
@@ -26,6 +28,8 @@ English | [简体中文](./README_zh-CN.md)
 
 > **Special reminder: although the library has supported the use of the browser environment, but please only use the google engine translation (google does not need key), the use of other translation engine need to configure the key, the use of the front-end will lead to key leakage, do not do it**
 
+> Browser bundles exclude Node-only helpers such as filesystem utilities. Keep browser usage focused on engines that are safe to expose client-side.
+
 ## 💻Translation engines, integration cases
 
 | Name             | Support | Description                                                                                                                                               |
@@ -39,6 +43,40 @@ English | [简体中文](./README_zh-CN.md)
 | tencent          | ✔       | Commissioned and ready for use                                                                                                                            |
 | yandex           |         | I have not tuned in as I do not have a bank account supported by the platform (help from those who are in a position to do so is welcome and appreciated) |
 
+## 🛠 Development
+
+This project now uses `rolldown`, `oxlint`, and `oxfmt` instead of `rollup`, `eslint`, and `prettier`.
+
+```bash
+pnpm build
+pnpm lint
+pnpm lint:fix
+pnpm format
+pnpm format:check
+pnpm test
+```
+
+- `pnpm build`: builds Node and browser bundles with `rolldown`, then emits `.d.ts` files with TypeScript.
+- `pnpm lint`: runs `oxlint` and `oxfmt --check`.
+- `pnpm lint:fix`: applies `oxlint --fix` and formats files with `oxfmt`.
+- `pnpm format`: formats the repository with `oxfmt`.
+- `pnpm test`: runs stable offline-safe tests.
+
+Integration tests that require real network access and third-party credentials are disabled by default. To run them manually, set `RUN_INTEGRATION_TESTS=true` before running `pnpm test`.
+
+- Bash
+
+  ```bash
+  RUN_INTEGRATION_TESTS=true pnpm test
+  ```
+
+- PowerShell
+
+  ```powershell
+  $env:RUN_INTEGRATION_TESTS = "true"
+  pnpm test
+  ```
+
 ## 🚀 Install
 
 - npm
@@ -64,16 +102,19 @@ English | [简体中文](./README_zh-CN.md)
 ### 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");
   ```
 
 - Translation examples
+
   ```typescript
   translator.addEngine(engines.google);
   const res1 = await translator.translate("hello", { from: "en", to: "zh" });
@@ -84,18 +125,22 @@ English | [简体中文](./README_zh-CN.md)
   ```
 
   Output results
+
   ```bash
   ['你好']
   ["你好", "好的"]
   ```
+
 - Language detection examples
+
   ```typescript
   translator.addEngine(engines.google);
-  const res1 = await translator.checkLanguage("hello", { engine:"google" });
+  const res1 = await translator.checkLanguage("hello", { engine: "google" });
   console.log(res1);
-
   ```
+
   Output results
+
   ```bash
   en
   ```
@@ -105,6 +150,7 @@ English | [简体中文](./README_zh-CN.md)
 use jsDelivr CDN
 
 - `development`
+
   ```html
   <script src="https://cdn.jsdelivr.net/npm/@yxw007/translate@0.0.7/dist/browser/index.umd.js"></script>
   ```
@@ -141,7 +187,6 @@ use jsDelivr CDN
 
   ```
 
-
 ## 📚 API
 
 ### Translator
@@ -195,7 +240,7 @@ type Engine = {
 
 #### `translate`
 
-You can pass a text or pass a text array, which will return a translated ```Promise<string[]>```
+You can pass a text or pass a text array, which will return a translated `Promise<string[]>`
 
 ```typescript
 translate<T extends Engines>(text: string | string[], options: TranslateOptions<T>)
@@ -206,8 +251,8 @@ translate<T extends Engines>(text: string | string[], options: TranslateOptions<
 Read the language list for the specified engine.
 
 ```typescript
-translator.getFromLanguages("google")
-translator.getToLanguages("google")
+translator.getFromLanguages("google");
+translator.getToLanguages("google");
 ```
 
 #### TranslateOptions
@@ -217,7 +262,7 @@ export interface TranslateOptions {
   from?: FromLanguage<T>;
   to: ToLanguage<T>;
   engine?: Engines;
-   /**
+  /**
    * Cache time in milliseconds
    */
   cache_time?: number;
@@ -297,11 +342,10 @@ interface AzureEngineOption extends BaseEngineOption {
 
 - Relative document：[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;
@@ -384,34 +428,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;
 }
 ```
 
 > Description: Option Param Please obtain it from the corresponding platform.
+
 - Related documentation：https://console.cloud.tencent.com/cam/capi
 
 - Region Configuration table
-  | 地域                   | 取值             |
+  | 地域 | 取值 |
   | ---------------------- | ---------------- |
-  | 亚太东南（曼谷）       | 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 |
 
 ## 🤝 Contribute
 
@@ -424,8 +468,8 @@ export interface TencentEngineOption extends BaseEngineOption {
   ```
 
 - Add new Engine
-
   - Add a new platform ENGINE plugin
+
     ```typescript
     export interface XXEngineOption extends BaseEngineOption {
       key: string;
@@ -436,7 +480,7 @@ 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> {
+        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>) {
@@ -457,7 +501,8 @@ export interface TencentEngineOption extends BaseEngineOption {
       };
     }
     ```
-  - Add the plugin to Engines(Location:```/src/engines/index.ts```)
+
+  - Add the plugin to Engines(Location:`/src/engines/index.ts`)
 
     ```typescript
     import { xx } from "./xx";
@@ -468,9 +513,10 @@ export interface TencentEngineOption extends BaseEngineOption {
       baidu,
       deepl,
       openai,
-      xx
+      xx,
     } as const;
     ```
+
   - Add the origin language configuration supported by the engine
 
     ```typescript
@@ -525,8 +571,10 @@ export interface TencentEngineOption extends BaseEngineOption {
       ...
       xxx: ValuesOf<typeof xxx>;
     };
+    ```
 
 - Build
+
   ```bash
   pnpm build
   ```
@@ -538,8 +586,8 @@ export interface TencentEngineOption extends BaseEngineOption {
 
 > **Tips: At present, the library can be used normally. Welcome everyone to experience. If you have any questions and suggestions, you can mention the feedback to me.If you are interested, you are welcome to join, let us improve this tool together. Help to click star ⭐, let more people know this tool, thank you for everyone🙏**
 
-
 ## 🌹 Thanks
+
 - [franciscop/translate](https://github.com/franciscop/translate.git)
 
 > Note：Thanks to [franciscop/translate](https://github.com/franciscop/translate.git) for giving me ideas for a quick implementation of this library, and also indirectly some of his code. Much appreciated.🙏
@@ -547,4 +595,3 @@ export interface TencentEngineOption extends BaseEngineOption {
 ## 📄 License
 
 Translate is released under the MIT license. See the [`LICENSE`](./LICENSE) file.
-

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
+  ```
 
 ## 🚀 安装
 
@@ -67,16 +104,19 @@ 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);
   const res1 = await translator.translate("hello", { from: "en", to: "zh" });
@@ -87,18 +127,22 @@ Translate 是一个支持多翻译引擎的翻译工具库，它提供了一套
   ```
 
   输出结果
+
   ```bash
   ['你好']
   ["你好", "好的"]
   ```
+
 - 语言检测例子
+
   ```typescript
   translator.addEngine(engines.google);
-  const res1 = await translator.checkLanguage("hello", { engine:"google" });
+  const res1 = await translator.checkLanguage("hello", { engine: "google" });
   console.log(res1);
   ```
 
   输出结果
+
   ```bash
   en
   ```
@@ -108,6 +152,7 @@ Translate 是一个支持多翻译引擎的翻译工具库，它提供了一套
 使用 jsDelivr CDN
 
 - `development`
+
   ```html
   <script src="https://cdn.jsdelivr.net/npm/@yxw007/translate@0.0.7/dist/browser/index.umd.js"></script>
   ```
@@ -208,8 +253,8 @@ translate: <T extends Engines>(text: string | string[], opts: EngineTranslateOpt
 读取指定 Engine 的语言列表。
 
 ```typescript
-translator.getFromLanguages("google")
-translator.getToLanguages("google")
+translator.getFromLanguages("google");
+translator.getToLanguages("google");
 ```
 
 #### TranslateOptions
@@ -299,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;
@@ -386,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 请从对应平台获取。
+
 - 相关文档：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 |
 
 ## 🤝 贡献
 
@@ -426,8 +470,8 @@ export interface TencentEngineOption extends BaseEngineOption {
   ```
 
 - 添加新Engine
-
   - 添加新平台engine插件
+
     ```typescript
     export interface XXEngineOption extends BaseEngineOption {
       key: string;
@@ -459,7 +503,8 @@ export interface TencentEngineOption extends BaseEngineOption {
       };
     }
     ```
-  - 将插件添加至engines(位置：```/src/engines/index.ts```)
+
+  - 将插件添加至engines(位置：`/src/engines/index.ts`)
 
     ```typescript
     import { xxx } from "./xxx";
@@ -470,9 +515,10 @@ export interface TencentEngineOption extends BaseEngineOption {
       baidu,
       deepl,
       openai,
-      xxx
+      xxx,
     } as const;
     ```
+
   - 添加对应Engine支持的origin语言配置
 
     ```typescript
@@ -527,9 +573,14 @@ export interface TencentEngineOption extends BaseEngineOption {
       ...
       xxx: ValuesOf<typeof xxx>;
     };
+    ```
+
+  ```
+
   ```
 
 - 打包
+
   ```bash
   pnpm build
   ```
@@ -540,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)为我快速实现这个库提供了思路，同时也间接了他的部分代码。非常感谢🙏