npm - @thor123141245r/ai-translate - Versions diffs - 1.0.0 → 1.0.1 - Mend

@thor123141245r/ai-translate 1.0.0 → 1.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (3) hide show

package/README.md CHANGED Viewed

@@ -1,124 +1,170 @@
-# ai-translate：可复用的 AI 翻译 CLI 与 i18n JSON 批量翻译
-本仓库是 npm 包 `@thor123141245r/ai-translate` 的源码，提供两类能力：
-- 通用文件翻译：把任意文本文件分块后交给大模型翻译（适合 Markdown、代码注释、技术文档等）
-- i18n JSON 翻译：以 `en.json` 为标准，批量生成/补齐多语言 JSON（严格保留 key 与结构，只翻译字符串 value）
-设计目标是“结构在本地处理，模型只做翻译”，避免把大文件或结构化数据整段塞进模型上下文导致不稳定。
-## 功能概览
-- CLI：
-  - `ai-translate` 通用文件翻译
-  - `ai-translate i18n` i18n JSON 批量翻译
-- 模块：`AiTranslateTransform`、`TextSplitterStream`、`translateI18nDir` 等可复用组件
-- 配置：`.ai-translate.json` 本地或全局配置（支持环境变量覆盖）
-- 兼容多模型提供方：ollama / openai / anthropic / mistral / deepseek（通过 LangChain 官方 SDK）
-- i18n 专用能力：
-  - 仅翻译 value，不改 key
-  - 批处理调用，避免上下文混乱
-  - 占位符保护（例如 `{{name}}`、`{name}`、`%s`）
-  - 本地缓存，减少重复翻译
-## 参数一览
-### CLI 参数
-| 参数 | 作用 | 备注 |
+# ai-translate: Reusable AI Translation CLI + i18n JSON Batch Translator
+Source repo for the npm package `@thor123141245r/ai-translate`.
+Looking for Chinese docs? See `README.zh-CN.md`.
+This project provides two main capabilities:
+- General file translation: split a file into chunks and translate with an LLM (good for Markdown, technical docs, code comments, etc.)
+- i18n JSON translation: use `en.json` as the canonical source of truth and batch-generate/fill other locale JSON files (preserve keys and structure, translate string values only)
+The key design principle is: keep structure handling local, and let the model only translate text. This avoids unstable results caused by sending large structured files into the LLM context.
+## Features
+- CLI:
+  - `ai-translate` for general file translation
+  - `ai-translate i18n` for i18n JSON translation based on a source JSON
+- Reusable modules: `AiTranslateTransform`, `TextSplitterStream`, `translateI18nDir`
+- Config file: `.ai-translate.json` (supports env var overrides)
+- Providers via LangChain SDK: ollama / openai / anthropic / mistral / deepseek
+- i18n-specific:
+  - Translate values only; never modify keys/structure
+  - Batch model calls to keep context stable
+  - Placeholder protection (e.g. `{{name}}`, `{name}`, `%s`)
+  - Local cache to reduce repeated translations
+## CLI
+### General translation flags
+| Flag | Description | Notes |
 | --- | --- | --- |
-| `-h`, `--help` | 输出帮助信息 |  |
-| `-v`, `--version` | 输出版本号 |  |
-| `-c`, `--config DIR` | 指定配置目录或配置文件路径 | 读取 `.ai-translate.json` |
-| `-f`, `--from LANG` | 源语言 | 可用英文名或 BCP47 代码 |
-| `-t`, `--to LANG` | 目标语言 | 可用英文名或 BCP47 代码 |
-| `-i`, `--input FILE` | 输入文件路径 |  |
-| `-o`, `--output FILE` | 输出文件路径 |  |
-| `--format FORMAT` | 指定输入格式 | 支持 `cpp`、`go`、`java`、`js`、`php`、`proto`、`python`、`rst`、`ruby`、`rust`、`scala`、`swift`、`markdown`、`latex`、`html` |
-| `set KEY VALUE` | 写入配置项 | `KEY` 见下表 |
-| `i18n` | 以 `en.json` 为标准批量翻译多语言 JSON | 只翻译 value，不改 key/结构 |
-### 配置参数
-| 参数 | 作用 | 默认值 |
+| `-h`, `--help` | Show help |  |
+| `-v`, `--version` | Show version |  |
+| `-c`, `--config DIR` | Config directory or config file path | reads `.ai-translate.json` |
+| `-f`, `--from LANG` | Source language | English name or BCP47 code |
+| `-t`, `--to LANG` | Target language | English name or BCP47 code |
+| `-i`, `--input FILE` | Input file path |  |
+| `-o`, `--output FILE` | Output file path |  |
+| `--format FORMAT` | Input format | cpp/go/java/js/php/proto/python/rst/ruby/rust/scala/swift/markdown/latex/html |
+| `set KEY VALUE` | Write config key | see config section |
+| `i18n` | i18n JSON translation | translate values only |
+### Config keys
+| Key | Description | Default |
 | --- | --- | --- |
-| `provider` | 模型提供方 | `ollama` |
-| `model` | 模型名称 | `qwen2.5:7b` |
-| `apiKey` | 模型 API Key | 空 |
-| `baseUrl` | 模型 Base URL | 空 |
-| `temperature` | 模型温度 | `0.1` |
-| `maxRetries` | 最大重试次数 | `10` |
-| `chunkSize` | 文本分块大小 | `1000` |
-## 快速开始
-### 1) 安装与运行方式
-无需全局安装，推荐直接用 `npx` / `pnpx`：
+| `provider` | Provider | `ollama` |
+| `model` | Model name | `qwen2.5:7b` |
+| `apiKey` | API key | empty |
+| `baseUrl` | Base URL | empty |
+| `temperature` | Temperature | `0.1` |
+| `maxRetries` | Max retries | `10` |
+| `chunkSize` | Split chunk size | `1000` |
+## Quick Start
+### Run via npx / pnpx
 ```bash
 npx @thor123141245r/ai-translate --help
 pnpx @thor123141245r/ai-translate --help
 ```
-也可以本仓库本地开发：
+### Choose a provider (required for real translations)
+This tool needs access to an LLM provider. If no provider is configured, translation calls will fail.
+Pick ONE of the options below:
+#### Option A: OpenAI (cloud)
+Set env vars:
+```bash
+export OPENAI_API_KEY="YOUR_KEY"
+```
+Then set provider (writes `.ai-translate.json`):
+```bash
+npx @thor123141245r/ai-translate set provider openai
+```
+#### Option B: Anthropic (cloud)
+```bash
+export ANTHROPIC_API_KEY="YOUR_KEY"
+npx @thor123141245r/ai-translate set provider anthropic
+```
+#### Option C: Mistral (cloud)
+```bash
+export MISTRAL_API_KEY="YOUR_KEY"
+npx @thor123141245r/ai-translate set provider mistral
+```
+#### Option D: DeepSeek (cloud)
+```bash
+export DEEPSEEK_API_KEY="YOUR_KEY"
+npx @thor123141245r/ai-translate set provider deepseek
+```
+#### Option E: Ollama (local)
+Start Ollama and make sure `OLLAMA_BASE_URL` works (default is `http://127.0.0.1:11434`).
+```bash
+export OLLAMA_BASE_URL="http://127.0.0.1:11434"
+npx @thor123141245r/ai-translate set provider ollama
+```
+Notes:
+- `AI_TRANSLATE_API_KEY` overrides provider-specific API keys.
+- `AI_TRANSLATE_BASE_URL` overrides provider-specific base URLs.
+### Local development
 ```bash
 npm install
 npm run build
 ```
-### CLI 用法
+## Usage
+### General file translation
 ```bash
-# 直接翻译文件
+# Translate a file
 node dist/bin/ai-translate.js -f Spanish -t English -i input.md -o output.md
-# 使用配置文件并从 stdin 读取
+# Read from stdin using config in current folder
 echo "translate" | node dist/bin/ai-translate.js -f en -t en -c .
 ```
-#### 通用文件翻译的工作方式
-1. 根据 `--format` 或输入文件扩展名推断格式
-2. 使用 LangChain 的 text splitter 按格式分块（默认 chunkSize=1000）
-3. 每个分块通过统一 Prompt 交给模型翻译
-4. 输出会尽量保留原始空白与结构
+How it works:
+1. Infer `--format` from the flag or file extension
+2. Split input into chunks (default chunkSize=1000)
+3. Translate each chunk using a single consistent prompt
+4. Preserve original whitespace as much as possible
-### i18n JSON 用法（en.json 作为标准）
-直接把 `en.json` 当纯文本翻译会破坏 JSON 结构与 key。本仓库提供 `i18n` 子命令：以源语言 JSON 为标准，按 key 路径逐条翻译字符串 value，并把结果写回目标语言文件。
+### i18n JSON translation (use en.json as source of truth)
+Do NOT translate `en.json` as plain text. It will likely break JSON syntax or translate keys.
+Use `i18n` subcommand to translate leaf string values only.
 ```bash
-# 也可以用 npx 直接运行
+# Run via npx
 npx @thor123141245r/ai-translate i18n --base ./src/i18n/pages/sora-watermask-remover --source en --targets ru
-# 目录内：存在 en.json / ru.json / de.json ...
-# 默认 mode=fill：保留已有翻译，只补齐缺失项
+# Default mode=fill: keep existing translations, only fill missing values
 node dist/bin/ai-translate.js i18n --base ./src/i18n/pages/sora-watermask-remover --source en
-# 指定目标语言（若目录里还没有目标文件，也会生成）
+# Specify targets (also creates target files when missing)
 node dist/bin/ai-translate.js i18n --base ./src/i18n/pages/sora-watermask-remover --source en --targets ru,de
-# 覆盖重翻（慎用）
+# Overwrite all values (use with care)
 node dist/bin/ai-translate.js i18n --base ./src/i18n/pages/sora-watermask-remover --source en --targets ru --mode overwrite
-# 仅预览统计（不写文件）
+# Dry run (no file writes)
 node dist/bin/ai-translate.js i18n --base ./src/i18n/pages/sora-watermask-remover --source en --dry
 ```
-#### i18n JSON 翻译的工作方式
-- 读取 `--base` 目录下的源文件（默认 `{source}.json`，例如 `en.json`）
-- 目标文件默认按 `{lang}.json` 命名（例如 `ru.json`）
-- 本地解析 JSON，并提取所有“叶子字符串 value”作为待翻译单元
-- 以批处理的方式调用模型：模型一次只处理一组短文本，不会拿到整份 JSON
-- 翻译结果按原 key 路径写回，严格不改动 key
-- 默认会在目录下写入缓存文件 `.ai-translate.cache.json`，避免重复翻译
-#### i18n 模式的常用参数
-- `--mode fill`：只补齐缺失项（推荐默认）
-- `--mode overwrite`：强制重翻全部字符串 value
-- `--mode prune`：对齐结构并清理目标文件中多余 key
-- `--batchMaxItems` / `--batchMaxChars`：控制每次调用模型的批处理大小
-- `--cache`：自定义缓存文件名（相对于 `--base` 目录）
-### 开发态直接运行
-```bash
-npm run dev:cli -- -f en -t zh-CN -i input.md -o output.md
-```
+How it works:
+- Reads source JSON from `--base` (default `{source}.json`, e.g. `en.json`)
+- Target files are `{lang}.json` (e.g. `ru.json`)
+- Extracts all leaf string values from the source JSON
+- Calls the model in batches (model never sees the whole JSON)
+- Writes translated values back by key path (keys/structure are preserved)
+- Writes a cache file `.ai-translate.cache.json` under the base directory by default
+Common i18n flags:
+- `--mode fill` (default): fill missing values only
+- `--mode overwrite`: translate all string values
+- `--mode prune`: align to source and remove extra keys
+- `--batchMaxItems` / `--batchMaxChars`: control batch size per model call
+- `--cache`: cache file name under `--base`
+## Configuration
+Config file: `.ai-translate.json`. You can write it via CLI:
-## 配置说明
-配置文件名为 `.ai-translate.json`，可通过命令行写入：
 ```bash
 node dist/bin/ai-translate.js set provider ollama
 node dist/bin/ai-translate.js set apiKey YOUR_API_KEY
@@ -126,44 +172,39 @@ node dist/bin/ai-translate.js set model qwen2.5:7b
 node dist/bin/ai-translate.js set chunkSize 1000
 ```
-支持的配置项：
-- provider
-- model
-- apiKey
-- baseUrl
-- temperature
-- maxRetries
-- chunkSize
+## Environment Variable Priority
+Priority: env vars > config file > defaults.
-## 环境变量优先级
-运行时读取优先级：环境变量 > 配置文件 > 默认值。
-优先读取的通用环境变量：
+Common env vars:
 - `AI_TRANSLATE_API_KEY`
 - `AI_TRANSLATE_BASE_URL`
-按提供方支持的环境变量：
+Provider-specific env vars:
 - `OPENAI_API_KEY` / `OPENAI_BASE_URL`
 - `ANTHROPIC_API_KEY` / `ANTHROPIC_BASE_URL`
 - `MISTRAL_API_KEY` / `MISTRAL_BASE_URL`
 - `DEEPSEEK_API_KEY` / `DEEPSEEK_BASE_URL`
 - `OLLAMA_BASE_URL`
-说明：
-- 通用变量存在时会覆盖配置文件对应字段
-- 未设置 apiKey 时，将由各 SDK 自行读取其默认环境变量
-## 复用说明
-本实现依赖 LangChain 的官方 SDK 与 `@commenthol/ai-translate` 的设计模式：
-- 文本分块使用 `@langchain/textsplitters`
-- 模型调用使用 `@langchain/*` 系列 ChatModel
-- 配置管理使用 `@commenthol/app-config`
+## Notes
+- For i18n, always use `ai-translate i18n` instead of translating JSON as plain text.
+- Avoid verbose logs and sensitive data in production environments.
-## 注意事项
-- i18n 场景请优先使用 `ai-translate i18n`，不要直接把 `en.json` 当纯文本翻译
-- 生产环境注意避免输出冗长日志与敏感信息
-## 最小自测
+## Minimal Validation
 ```bash
 npm run validate
 ```
+# About the Author
+I build **AI SaaS for global markets**—from **idea validation & vibe coding** to **engineering, infra, SEO/backlinks, and growth experiments**.
+Everything here comes from **real projects, real traffic, and real revenue attempts**.
+- **Knowledge Base**: [Thor’s AI Going-Global Content Planning](https://my.feishu.cn/wiki/DUzewBOq2iy1rPkSYJecMRXYnFh)
+- **Blog**: [Thor-AI Blog](https://www.notion.so/Thor-AI-2eaf0388ab4680d0a98bedc8d290e1be?pvs=21)
+- **Open Source (High Star)**: Smart Campus System — [GitHub](https://github.com/214140846/TOGO_School_Miniprograme) | [Gitee](https://gitee.com/zengyunengineer/TOGO_School_Miniprograme) | [Skillhub-MCP](https://github.com/214140846/skillhub-mcp)
+- **Social**: [Jike](https://web.okjike.com/u/159D450D-2193-4739-8825-AA8EBEC2E9B4)
+- **Products**: [sora2.cloud](https://sora2.cloud/) | [ricebowl.ai](https://ricebowl.ai/)
+- **Notes**: [AI Video & Image Collection](https://www.notion.so/Ricebowl-AI-2eef0388ab468155b14cd0ac0dd14fa9?pvs=21)
+- **PyPI**: [skillhub-mcp](https://pypi.org/project/skillhub-mcp/)

package/README.zh-CN.md ADDED Viewed

@@ -0,0 +1,194 @@
+# ai-translate：可复用的 AI 翻译 CLI 与 i18n JSON 批量翻译
+本仓库是 npm 包 `@thor123141245r/ai-translate` 的源码。
+它提供两类能力：
+- 通用文件翻译：把任意文本文件分块后交给大模型翻译（适合 Markdown、技术文档、代码注释等）
+- i18n JSON 翻译：以 `en.json` 为标准，批量生成/补齐其他语言 JSON（严格保留 key 与结构，只翻译字符串 value）
+核心设计原则是：结构在本地处理，模型只做翻译。避免把大体量结构化文件整段塞进模型上下文导致不稳定。
+## 功能概览
+- CLI：
+  - `ai-translate` 通用文件翻译
+  - `ai-translate i18n` i18n JSON 批量翻译
+- 可复用模块：`AiTranslateTransform`、`TextSplitterStream`、`translateI18nDir`
+- 配置：`.ai-translate.json`（支持环境变量覆盖）
+- 兼容多模型提供方：ollama / openai / anthropic / mistral / deepseek（通过 LangChain 官方 SDK）
+- i18n 专用能力：
+  - 只翻译 value，不改 key 与结构
+  - 批处理调用，避免上下文混乱
+  - 占位符保护（例如 `{{name}}`、`{name}`、`%s`）
+  - 本地缓存，减少重复翻译
+## CLI
+### 通用翻译参数
+| 参数 | 作用 | 备注 |
+| --- | --- | --- |
+| `-h`, `--help` | 输出帮助信息 |  |
+| `-v`, `--version` | 输出版本号 |  |
+| `-c`, `--config DIR` | 指定配置目录或配置文件路径 | 读取 `.ai-translate.json` |
+| `-f`, `--from LANG` | 源语言 | 可用英文名或 BCP47 代码 |
+| `-t`, `--to LANG` | 目标语言 | 可用英文名或 BCP47 代码 |
+| `-i`, `--input FILE` | 输入文件路径 |  |
+| `-o`, `--output FILE` | 输出文件路径 |  |
+| `--format FORMAT` | 指定输入格式 | cpp/go/java/js/php/proto/python/rst/ruby/rust/scala/swift/markdown/latex/html |
+| `set KEY VALUE` | 写入配置项 | 见配置说明 |
+| `i18n` | i18n JSON 批量翻译 | 只翻译 value |
+### 配置项
+| 参数 | 作用 | 默认值 |
+| --- | --- | --- |
+| `provider` | 模型提供方 | `ollama` |
+| `model` | 模型名称 | `qwen2.5:7b` |
+| `apiKey` | 模型 API Key | 空 |
+| `baseUrl` | 模型 Base URL | 空 |
+| `temperature` | 模型温度 | `0.1` |
+| `maxRetries` | 最大重试次数 | `10` |
+| `chunkSize` | 文本分块大小 | `1000` |
+## 快速开始
+### npx / pnpx 运行
+```bash
+npx @thor123141245r/ai-translate --help
+pnpx @thor123141245r/ai-translate --help
+```
+### 选择模型提供方（要真正翻译必须配置）
+本工具需要能访问某个大模型提供方；如果未配置 provider 或未提供 key，翻译调用会失败。
+下面任选一种方式：
+#### 方式 A：OpenAI（云）
+先配置环境变量：
+```bash
+export OPENAI_API_KEY="你的key"
+```
+再设置 provider（会写入 `.ai-translate.json`）：
+```bash
+npx @thor123141245r/ai-translate set provider openai
+```
+#### 方式 B：Anthropic（云）
+```bash
+export ANTHROPIC_API_KEY="你的key"
+npx @thor123141245r/ai-translate set provider anthropic
+```
+#### 方式 C：Mistral（云）
+```bash
+export MISTRAL_API_KEY="你的key"
+npx @thor123141245r/ai-translate set provider mistral
+```
+#### 方式 D：DeepSeek（云）
+```bash
+export DEEPSEEK_API_KEY="你的key"
+npx @thor123141245r/ai-translate set provider deepseek
+```
+#### 方式 E：Ollama（本地）
+启动 Ollama，并确保 `OLLAMA_BASE_URL` 可访问（默认 `http://127.0.0.1:11434`）。
+```bash
+export OLLAMA_BASE_URL="http://127.0.0.1:11434"
+npx @thor123141245r/ai-translate set provider ollama
+```
+补充说明：
+- `AI_TRANSLATE_API_KEY` 会覆盖各 provider 的 `*_API_KEY`
+- `AI_TRANSLATE_BASE_URL` 会覆盖各 provider 的 `*_BASE_URL` 或 `OLLAMA_BASE_URL`
+### 本地开发
+```bash
+npm install
+npm run build
+```
+## 用法
+### 通用文件翻译
+```bash
+# 翻译文件
+node dist/bin/ai-translate.js -f Spanish -t English -i input.md -o output.md
+# 从 stdin 读取，并使用当前目录的配置文件
+echo "translate" | node dist/bin/ai-translate.js -f en -t en -c .
+```
+工作方式：
+1. 通过 `--format` 或文件扩展名推断格式
+2. 将输入按 chunkSize 分块（默认 1000）
+3. 对每个分块使用统一 Prompt 调用模型翻译
+4. 尽量保留原始空白与结构
+### i18n JSON 翻译（以 en.json 为标准）
+不要把 `en.json` 当纯文本翻译，这很容易破坏 JSON 语法或把 key 翻译掉。
+请使用 `i18n` 子命令：只翻译叶子字符串 value。
+```bash
+# 用 npx 直接运行
+npx @thor123141245r/ai-translate i18n --base ./src/i18n/pages/sora-watermask-remover --source en --targets ru
+# 默认 mode=fill：保留已有翻译，只补齐缺失项
+node dist/bin/ai-translate.js i18n --base ./src/i18n/pages/sora-watermask-remover --source en
+# 指定目标语言（即使目标文件不存在也会生成）
+node dist/bin/ai-translate.js i18n --base ./src/i18n/pages/sora-watermask-remover --source en --targets ru,de
+# 覆盖重翻（慎用）
+node dist/bin/ai-translate.js i18n --base ./src/i18n/pages/sora-watermask-remover --source en --targets ru --mode overwrite
+# 仅预览统计（不写文件）
+node dist/bin/ai-translate.js i18n --base ./src/i18n/pages/sora-watermask-remover --source en --dry
+```
+工作方式：
+- 从 `--base` 目录读取源文件（默认 `{source}.json`，例如 `en.json`）
+- 目标文件默认 `{lang}.json`（例如 `ru.json`）
+- 本地解析 JSON，提取所有“叶子字符串 value”作为待翻译单元
+- 通过批处理调用模型（模型不会拿到整份 JSON）
+- 按原 key 路径写回翻译结果，严格不改 key
+- 默认在目录下写入缓存 `.ai-translate.cache.json`，减少重复翻译
+i18n 常用参数：
+- `--mode fill`：只补齐缺失项（推荐默认）
+- `--mode overwrite`：重翻全部字符串 value
+- `--mode prune`：对齐结构并清理多余 key
+- `--batchMaxItems` / `--batchMaxChars`：控制批处理大小
+- `--cache`：自定义缓存文件名（相对于 `--base`）
+## 配置说明
+配置文件名为 `.ai-translate.json`，可通过命令行写入：
+```bash
+node dist/bin/ai-translate.js set provider ollama
+node dist/bin/ai-translate.js set apiKey YOUR_API_KEY
+node dist/bin/ai-translate.js set model qwen2.5:7b
+node dist/bin/ai-translate.js set chunkSize 1000
+```
+## 环境变量优先级
+优先级：环境变量 > 配置文件 > 默认值。
+通用环境变量：
+- `AI_TRANSLATE_API_KEY`
+- `AI_TRANSLATE_BASE_URL`
+提供方环境变量：
+- `OPENAI_API_KEY` / `OPENAI_BASE_URL`
+- `ANTHROPIC_API_KEY` / `ANTHROPIC_BASE_URL`
+- `MISTRAL_API_KEY` / `MISTRAL_BASE_URL`
+- `DEEPSEEK_API_KEY` / `DEEPSEEK_BASE_URL`
+- `OLLAMA_BASE_URL`
+## 注意事项
+- i18n 场景请优先使用 `ai-translate i18n`，不要直接把 `en.json` 当纯文本翻译
+- 生产环境注意避免输出冗长日志与敏感信息
+## 最小自测
+```bash
+npm run validate
+```

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@thor123141245r/ai-translate",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "publishConfig": {
     "access": "public"
   },
@@ -19,7 +19,8 @@
   },
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "README.zh-CN.md"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",