diff --git a/.github/workflows/release-deepl.yml b/.github/workflows/release-deepl.yml new file mode 100644 index 0000000..c194769 --- /dev/null +++ b/.github/workflows/release-deepl.yml @@ -0,0 +1,25 @@ +name: release-deepl + +on: + workflow_dispatch: + inputs: + version: + description: 'Version bump for @kiritan/deepl: patch/minor/major/prerelease, or an explicit version (e.g. 0.2.0)' + required: true + default: patch + dist_tag: + description: 'npm dist-tag to publish under. Leave empty to auto-detect: the prerelease identifier (e.g. "beta" from 0.2.0-beta.0), or "latest" for a stable version.' + required: false + default: '' + +jobs: + release: + uses: ./.github/workflows/_release-package.yml + with: + package_dir: packages/deepl + npm_package_name: '@kiritan/deepl' + version: ${{ inputs.version }} + dist_tag: ${{ inputs.dist_tag }} + permissions: + contents: write + id-token: write diff --git a/.kiritanconfig b/.kiritanconfig index 17fd2ea..b150279 100644 --- a/.kiritanconfig +++ b/.kiritanconfig @@ -20,6 +20,11 @@ export default { strategy: "inline", naming: { template: "packages/runtime/{base}.{locale}.{ext}" }, }, + { + glob: "packages/deepl/base/README.base.md", + strategy: "inline", + naming: { template: "packages/deepl/{base}.{locale}.{ext}" }, + }, { glob: "extensions/vscode/base/README.base.md", strategy: "inline", diff --git a/CONTRIBUTING.ja.md b/CONTRIBUTING.ja.md index 99aea50..9f18d9d 100644 --- a/CONTRIBUTING.ja.md +++ b/CONTRIBUTING.ja.md @@ -25,6 +25,7 @@ npm install | --- | --- | --- | | `kiritan` | `packages/kiritan` | CLI とビルドパイプライン(設定・翻訳ストア・レンダラー・翻訳ミドルウェア) | | `@kiritan/runtime` | `packages/runtime` | ビルド時依存を持たない、最小限の `t(key, params)` ランタイム | +| `@kiritan/deepl` | `packages/deepl` | `translate.middlewares` 用のDeepL翻訳ミドルウェア | | `otoneko1102.kiritan` | `extensions/vscode` | VS Code拡張機能(`:::kiritan{...}` ブロックのシンタックスハイライト)。npm workspaceのメンバーではない — 詳細は後述の「リリース」を参照。 | | — | `extensions/vim` | Vim/Neovimプラグイン(同じディレクティブハイライトに加え、`*.kiritanconfig` のfiletype判定)。どこにも公開せず、プラグインマネージャーの`rtp`オプションでこのリポジトリから直接インストールする。 | @@ -78,9 +79,9 @@ npm run ci && npm run typecheck && npm run test && npm run build ## リリース(メンテナー向け) -`kiritan` と `@kiritan/runtime` はそれぞれ専用の `workflow_dispatch` ワークフロー(`release.yml` / `release-runtime.yml`)を持っており、片方をリリースしてももう片方に誤って影響することはありません。どちらも実際の処理を行う共通の再利用可能ワークフロー(`_release-package.yml`。単体では実行不可)への薄いラッパーです。 +npmパッケージ(`kiritan`・`@kiritan/runtime`・`@kiritan/deepl`)はそれぞれ専用の `workflow_dispatch` ワークフロー(`release.yml` / `release-runtime.yml` / `release-deepl.yml`)を持っており、1つをリリースしても他のパッケージに誤って影響することはありません。いずれも実際の処理を行う共通の再利用可能ワークフロー(`_release-package.yml`。単体では実行不可)への薄いラッパーです。 -Actions タブから `release` または `release-runtime` を、2つの入力で実行してください: +Actions タブから対象パッケージのワークフロー(例: `release-runtime`)を、2つの入力で実行してください: - `version`: semverのbump種別(`patch` / `minor` / `major` / `prerelease`)、または明示的なバージョン(例: `0.2.0`)。そのまま `npm version` に渡されます。 - `dist_tag`: 公開先のnpm dist-tag。空なら自動判定(プレリリースならそのタグ、例えば `0.2.0-beta.0` なら `beta`。安定版なら `latest`)。 @@ -88,7 +89,7 @@ Actions タブから `release` または `release-runtime` を、2つの入力 ワークフローは対象パッケージの `package.json` を更新し(changelogファイルは無く、代わりにマージ済みPRから生成されるGitHubの自動リリースノートを使用)、`base/*.base.md` から生成される全ドキュメントを再生成し(`kiritan build`。バージョンアップと同じコミットにまとめられます)、**trusted publishing**(OIDC。`NPM_TOKEN` 不要)で npm に provenance 付きで公開し、バージョンコミットと `@` タグを push した上で、GitHub Release を作成します。 trusted publishing は npmjs.com 上でパッケージごとに一度だけ設定が必要です。 -パッケージの **Settings → Publishing access → Trusted publishers → GitHub** から、そのパッケージ自身のワークフローファイル(`release.yml` または `release-runtime.yml`)を指定してください。 +パッケージの **Settings → Publishing access → Trusted publishers → GitHub** から、そのパッケージ自身のワークフローファイル(例: `kiritan` なら `release.yml`、`@kiritan/deepl` なら `release-deepl.yml`)を指定してください。 `kiritan` は `@kiritan/runtime` に依存している(現在 `^0.1.0`)ため、runtimeのminor/majorバージョンを上げても Kiritan 側の依存範囲は自動更新されません。これは意図的な仕様で、runtime単体のリリースが Kiritan の `package.json` に触れることが無いようにするためです。該当する場合は別途手動でPRを出してください。 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ca17578..df38589 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -25,6 +25,7 @@ This is an npm workspaces monorepo (see [docs/DESIGN.md](./docs/DESIGN.md) chapt | --- | --- | --- | | `kiritan` | `packages/kiritan` | The CLI + build pipeline (config, stores, renderers, translate middlewares) | | `@kiritan/runtime` | `packages/runtime` | The minimal `t(key, params)` runtime, with no build-time dependencies | +| `@kiritan/deepl` | `packages/deepl` | A DeepL translate middleware for `translate.middlewares` | | `otoneko1102.kiritan` | `extensions/vscode` | VS Code extension (syntax highlighting for `:::kiritan{...}` blocks). Not an npm workspace member — see "Releasing" below. | | — | `extensions/vim` | Vim/Neovim plugin (the same directive highlighting, plus `*.kiritanconfig` filetype detection). Not published anywhere — installed directly from this repo via a plugin manager's `rtp` option. | @@ -81,9 +82,9 @@ Keep each change focused and add tests for any new behaviour. There's no changes ## Releasing (maintainers) -`kiritan` and `@kiritan/runtime` each have their own `workflow_dispatch` GitHub Actions workflow — `release.yml` and `release-runtime.yml` — so releasing one package can never accidentally touch the other. Both are thin wrappers around a shared reusable workflow (`_release-package.yml`, not runnable on its own) that does the actual work. +Every npm package (`kiritan`, `@kiritan/runtime`, `@kiritan/deepl`) has its own `workflow_dispatch` GitHub Actions workflow — `release.yml`, `release-runtime.yml`, `release-deepl.yml` — so releasing one package can never accidentally touch another. Each is a thin wrapper around a shared reusable workflow (`_release-package.yml`, not runnable on its own) that does the actual work. -From the Actions tab, run `release` or `release-runtime` with two inputs: +From the Actions tab, run the package's workflow (e.g. `release-runtime`) with two inputs: - `version`: a semver bump (`patch` / `minor` / `major` / `prerelease`) or an explicit version (e.g. `0.2.0`), passed straight to `npm version`. - `dist_tag`: the npm dist-tag to publish under. Leave empty to auto-detect — the prerelease identifier (e.g. `beta` from `0.2.0-beta.0`), or `latest` for a stable version. @@ -91,7 +92,7 @@ From the Actions tab, run `release` or `release-runtime` with two inputs: The workflow bumps that package's `package.json` (no changelog file — GitHub's auto-generated release notes, from merged PRs, are used instead), regenerates every `base/*.base.md`-derived doc (`kiritan build`, folded into the same commit), publishes to npm with provenance via **trusted publishing** (OIDC — no `NPM_TOKEN` needed), pushes the version commit and a `@` tag, and creates a GitHub Release. Trusted publishing must be configured once per package on npmjs.com: -package **Settings → Publishing access → Trusted publishers → GitHub**, pointing at that package's own workflow file (`release.yml` or `release-runtime.yml`). +package **Settings → Publishing access → Trusted publishers → GitHub**, pointing at that package's own workflow file (e.g. `release.yml` for `kiritan`, `release-deepl.yml` for `@kiritan/deepl`). Since `kiritan` depends on `@kiritan/runtime` (currently `^0.1.0`), bumping runtime's minor or major version doesn't automatically update Kiritan's dependency range — that's a manual follow-up PR when it happens, on purpose, so releasing runtime alone never touches Kiritan's `package.json`. diff --git a/README.ja.md b/README.ja.md index cbe2f62..7b501c8 100644 --- a/README.ja.md +++ b/README.ja.md @@ -20,6 +20,7 @@ | --- | --- | --- | | [`kiritan`](./packages/kiritan) | `packages/kiritan` | CLI とビルドパイプライン(設定・翻訳ストア・レンダラー・翻訳ミドルウェア) | | [`@kiritan/runtime`](./packages/runtime) | `packages/runtime` | ビルド時依存を持たない、最小限の `t(key, params)` ランタイム | +| [`@kiritan/deepl`](./packages/deepl) | `packages/deepl` | `translate.middlewares` 用の [DeepL](https://www.deepl.com/) 翻訳ミドルウェア | ## 関連ツール diff --git a/README.md b/README.md index 513b567..e359493 100644 --- a/README.md +++ b/README.md @@ -20,6 +20,7 @@ This is an npm workspaces monorepo. The full design lives in [docs/DESIGN.md](./ | --- | --- | --- | | [`kiritan`](./packages/kiritan) | `packages/kiritan` | The CLI + build pipeline: config, translation stores, renderers, translate middlewares | | [`@kiritan/runtime`](./packages/runtime) | `packages/runtime` | The minimal `t(key, params)` runtime, with no build-time dependencies | +| [`@kiritan/deepl`](./packages/deepl) | `packages/deepl` | A [DeepL](https://www.deepl.com/) translate middleware for `translate.middlewares` | ## Related tooling diff --git a/base/CONTRIBUTING.base.md b/base/CONTRIBUTING.base.md index 70b9b69..df8ff80 100644 --- a/base/CONTRIBUTING.base.md +++ b/base/CONTRIBUTING.base.md @@ -52,6 +52,7 @@ This is an npm workspaces monorepo (see [docs/DESIGN.md](./docs/DESIGN.md) chapt | --- | --- | --- | | `kiritan` | `packages/kiritan` | The CLI + build pipeline (config, stores, renderers, translate middlewares) | | `@kiritan/runtime` | `packages/runtime` | The minimal `t(key, params)` runtime, with no build-time dependencies | +| `@kiritan/deepl` | `packages/deepl` | A DeepL translate middleware for `translate.middlewares` | | `otoneko1102.kiritan` | `extensions/vscode` | VS Code extension (syntax highlighting for `:::kiritan{...}` blocks). Not an npm workspace member — see "Releasing" below. | | — | `extensions/vim` | Vim/Neovim plugin (the same directive highlighting, plus `*.kiritanconfig` filetype detection). Not published anywhere — installed directly from this repo via a plugin manager's `rtp` option. | @@ -64,6 +65,7 @@ The design and rationale for everything above live in [docs/DESIGN.md](./docs/DE | --- | --- | --- | | `kiritan` | `packages/kiritan` | CLI とビルドパイプライン(設定・翻訳ストア・レンダラー・翻訳ミドルウェア) | | `@kiritan/runtime` | `packages/runtime` | ビルド時依存を持たない、最小限の `t(key, params)` ランタイム | +| `@kiritan/deepl` | `packages/deepl` | `translate.middlewares` 用のDeepL翻訳ミドルウェア | | `otoneko1102.kiritan` | `extensions/vscode` | VS Code拡張機能(`:::kiritan{...}` ブロックのシンタックスハイライト)。npm workspaceのメンバーではない — 詳細は後述の「リリース」を参照。 | | — | `extensions/vim` | Vim/Neovimプラグイン(同じディレクティブハイライトに加え、`*.kiritanconfig` のfiletype判定)。どこにも公開せず、プラグインマネージャーの`rtp`オプションでこのリポジトリから直接インストールする。 | @@ -181,16 +183,16 @@ Keep each change focused and add tests for any new behaviour. There's no changes :::kiritan{locale=en} ## Releasing (maintainers) -`kiritan` and `@kiritan/runtime` each have their own `workflow_dispatch` GitHub Actions workflow — `release.yml` and `release-runtime.yml` — so releasing one package can never accidentally touch the other. Both are thin wrappers around a shared reusable workflow (`_release-package.yml`, not runnable on its own) that does the actual work. +Every npm package (`kiritan`, `@kiritan/runtime`, `@kiritan/deepl`) has its own `workflow_dispatch` GitHub Actions workflow — `release.yml`, `release-runtime.yml`, `release-deepl.yml` — so releasing one package can never accidentally touch another. Each is a thin wrapper around a shared reusable workflow (`_release-package.yml`, not runnable on its own) that does the actual work. -From the Actions tab, run `release` or `release-runtime` with two inputs: +From the Actions tab, run the package's workflow (e.g. `release-runtime`) with two inputs: - `version`: a semver bump (`patch` / `minor` / `major` / `prerelease`) or an explicit version (e.g. `0.2.0`), passed straight to `npm version`. - `dist_tag`: the npm dist-tag to publish under. Leave empty to auto-detect — the prerelease identifier (e.g. `beta` from `0.2.0-beta.0`), or `latest` for a stable version. The workflow bumps that package's `package.json` (no changelog file — GitHub's auto-generated release notes, from merged PRs, are used instead), regenerates every `base/*.base.md`-derived doc (`kiritan build`, folded into the same commit), publishes to npm with provenance via **trusted publishing** (OIDC — no `NPM_TOKEN` needed), pushes the version commit and a `@` tag, and creates a GitHub Release. Trusted publishing must be configured once per package on npmjs.com: -package **Settings → Publishing access → Trusted publishers → GitHub**, pointing at that package's own workflow file (`release.yml` or `release-runtime.yml`). +package **Settings → Publishing access → Trusted publishers → GitHub**, pointing at that package's own workflow file (e.g. `release.yml` for `kiritan`, `release-deepl.yml` for `@kiritan/deepl`). Since `kiritan` depends on `@kiritan/runtime` (currently `^0.1.0`), bumping runtime's minor or major version doesn't automatically update Kiritan's dependency range — that's a manual follow-up PR when it happens, on purpose, so releasing runtime alone never touches Kiritan's `package.json`. @@ -203,16 +205,16 @@ The Vim/Neovim plugin (`extensions/vim`) has nothing to build or publish — use :::kiritan{locale=ja} ## リリース(メンテナー向け) -`kiritan` と `@kiritan/runtime` はそれぞれ専用の `workflow_dispatch` ワークフロー(`release.yml` / `release-runtime.yml`)を持っており、片方をリリースしてももう片方に誤って影響することはありません。どちらも実際の処理を行う共通の再利用可能ワークフロー(`_release-package.yml`。単体では実行不可)への薄いラッパーです。 +npmパッケージ(`kiritan`・`@kiritan/runtime`・`@kiritan/deepl`)はそれぞれ専用の `workflow_dispatch` ワークフロー(`release.yml` / `release-runtime.yml` / `release-deepl.yml`)を持っており、1つをリリースしても他のパッケージに誤って影響することはありません。いずれも実際の処理を行う共通の再利用可能ワークフロー(`_release-package.yml`。単体では実行不可)への薄いラッパーです。 -Actions タブから `release` または `release-runtime` を、2つの入力で実行してください: +Actions タブから対象パッケージのワークフロー(例: `release-runtime`)を、2つの入力で実行してください: - `version`: semverのbump種別(`patch` / `minor` / `major` / `prerelease`)、または明示的なバージョン(例: `0.2.0`)。そのまま `npm version` に渡されます。 - `dist_tag`: 公開先のnpm dist-tag。空なら自動判定(プレリリースならそのタグ、例えば `0.2.0-beta.0` なら `beta`。安定版なら `latest`)。 ワークフローは対象パッケージの `package.json` を更新し(changelogファイルは無く、代わりにマージ済みPRから生成されるGitHubの自動リリースノートを使用)、`base/*.base.md` から生成される全ドキュメントを再生成し(`kiritan build`。バージョンアップと同じコミットにまとめられます)、**trusted publishing**(OIDC。`NPM_TOKEN` 不要)で npm に provenance 付きで公開し、バージョンコミットと `@` タグを push した上で、GitHub Release を作成します。 trusted publishing は npmjs.com 上でパッケージごとに一度だけ設定が必要です。 -パッケージの **Settings → Publishing access → Trusted publishers → GitHub** から、そのパッケージ自身のワークフローファイル(`release.yml` または `release-runtime.yml`)を指定してください。 +パッケージの **Settings → Publishing access → Trusted publishers → GitHub** から、そのパッケージ自身のワークフローファイル(例: `kiritan` なら `release.yml`、`@kiritan/deepl` なら `release-deepl.yml`)を指定してください。 `kiritan` は `@kiritan/runtime` に依存している(現在 `^0.1.0`)ため、runtimeのminor/majorバージョンを上げても Kiritan 側の依存範囲は自動更新されません。これは意図的な仕様で、runtime単体のリリースが Kiritan の `package.json` に触れることが無いようにするためです。該当する場合は別途手動でPRを出してください。 diff --git a/base/DESIGN.base.md b/base/DESIGN.base.md index a12202b..3cd1cb4 100644 --- a/base/DESIGN.base.md +++ b/base/DESIGN.base.md @@ -132,10 +132,10 @@ packages/runtime/src/ - Rather than re-exporting `kiritan/runtime` from `kiritan`, `@kiritan/runtime` is its own independent package (`kiritan` may depend on `@kiritan/runtime`, but never the reverse). This lets a project that only wants the runtime avoid pulling in `kiritan` core (remark and other build-time dependencies) at all. - Everything except the CLI (`src/cli.ts`) keeps full CJS/ESM dual-format support. The remark/unified/micromark ecosystem only ships ESM-only packages (going back to a CJS release would mean "using an older version," which is avoided), so `tsdown.config.ts`'s `deps.alwaysBundle` bundles them directly into `dist/index.{cjs,mjs}`, eliminating any scenario where a CJS consumer would need to `require` an ESM-only package. `citty`, which is CLI-only, stays an external dependency and isn't bundled. -- Reference implementations of translate middlewares to be added later (e.g. `@kiritan/google-translate`, chapter 13) are also expected to be added to the same workspace under `packages/*`. +- Reference implementations of translate middlewares (`@kiritan/deepl`, chapter 13) live in the same workspace under `packages/*`. Each is standalone — it doesn't depend on `kiritan`, since a middleware is just a function whose shape is structurally compatible with `translate.middlewares`. - `extensions/vscode` (the VS Code extension, chapter 13) lives outside `packages/` and so is never picked up by the root `"workspaces": ["packages/*"]` glob — its `package.json` `"name"` is `"kiritan"`, which would otherwise collide with the CLI package's own name (an npm workspace can't have two packages sharing a name). Its build/test tooling is a root-level `devDependency` instead of a package-local one. - The existing `tsdown` / `vitest` / `eslint` / CI (`ci.yml` and the release workflows) setups need updating for workspace support (per-package build/test/publish). This is treated as an implementation task once the design is finalized. -- Versioning is **independent per package** (no lockstep, no shared changelog-generation tool). Each package has its own `workflow_dispatch` GitHub Actions workflow (`release.yml`, `release-runtime.yml`) — thin wrappers around a shared reusable workflow (`_release-package.yml`) that does the actual work — so releasing one package can never touch the other by accident: +- Versioning is **independent per package** (no lockstep, no shared changelog-generation tool). Each package has its own `workflow_dispatch` GitHub Actions workflow (`release.yml`, `release-runtime.yml`, `release-deepl.yml`) — thin wrappers around a shared reusable workflow (`_release-package.yml`) that does the actual work — so releasing one package can never touch the other by accident: 1. Trigger `release-` from the Actions tab with two inputs: `version` (a semver bump — `patch`/`minor`/`major`/`prerelease` — or an explicit version, passed straight to `npm version`) and `dist_tag` (npm dist-tag; empty auto-detects). 2. The workflow bumps that package's `package.json` (no changeset file, no per-package CHANGELOG.md — GitHub's auto-generated release notes from merged PRs are used instead), regenerates every `base/*.base.md`-derived doc, and runs `npm publish` with **trusted publishing** (OIDC — no `NPM_TOKEN` needed, configured per-package on npmjs.com pointing at that package's own workflow file). @@ -184,10 +184,10 @@ packages/runtime/src/ - `kiritan` から `kiritan/runtime` を re-export する形は取らず、`@kiritan/runtime` を独立パッケージにする(`kiritan` は `@kiritan/runtime` に依存しても、逆はない)。ランタイムだけを使いたいプロジェクトが `kiritan` 本体(remark 等のビルド時依存)を一切引き込まずに済む。 - CLI(`src/cli.ts`)以外はすべて CJS/ESM 両対応を維持する。remark/unified/micromark 系の依存は ESM 専用パッケージしか無い(CJS版へ戻すことは「古いバージョンを使う」ことになるため避ける)ため、`tsdown.config.ts` の `deps.alwaysBundle` でこれらを `dist/index.{cjs,mjs}` に直接バンドルし、CJS 利用者が ESM 専用パッケージを `require` する場面自体を無くす。CLI 専用の `citty` はバンドルせず外部依存のままでよい。 -- 将来追加する翻訳ミドルウェアの参考実装(`@kiritan/google-translate` など、13章)も同じワークスペースの `packages/*` に追加していく想定。 +- 翻訳ミドルウェアの参考実装(`@kiritan/deepl`、13章)は同じワークスペースの `packages/*` に置く。それぞれ単体で完結し、`kiritan` には依存しない — ミドルウェアは `translate.middlewares` と構造的に互換な形の単なる関数であるため。 - `extensions/vscode`(VS Code拡張機能、13章)は `packages/` の外に置くため、ルートの `"workspaces": ["packages/*"]` には拾われない — `package.json` の `"name"` が `"kiritan"` で、CLIパッケージ自身の名前と衝突してしまう(npm workspaceは同名パッケージを2つ持てない)ため。ビルド・テストに必要なツールはパッケージ側ではなく、ルートの `devDependency` として持たせる。 - 既存の `tsdown` / `vitest` / `eslint` / CI(`ci.yml` およびリリース用ワークフロー)はワークスペース対応に更新が必要(各パッケージごとのビルド・テスト・公開)。これは設計確定後の実装タスクとして扱う。 -- バージョニングは **パッケージごとに独立**させる(lockstep にしない。共有のchangelog生成ツールも使わない)。パッケージごとに専用の `workflow_dispatch` ワークフロー(`release.yml` / `release-runtime.yml`)を持ち、どちらも実際の処理を行う共通の再利用可能ワークフロー(`_release-package.yml`)への薄いラッパーにすることで、片方のリリースがもう片方に誤って影響することを防ぐ: +- バージョニングは **パッケージごとに独立**させる(lockstep にしない。共有のchangelog生成ツールも使わない)。パッケージごとに専用の `workflow_dispatch` ワークフロー(`release.yml` / `release-runtime.yml` / `release-deepl.yml`)を持ち、どちらも実際の処理を行う共通の再利用可能ワークフロー(`_release-package.yml`)への薄いラッパーにすることで、片方のリリースがもう片方に誤って影響することを防ぐ: 1. Actions タブから `release-` を、`version`(semverのbump種別 `patch`/`minor`/`major`/`prerelease`、または明示的なバージョン。そのまま `npm version` に渡す)と `dist_tag`(npm dist-tag。空なら自動判定)の2つの入力で実行する。 2. ワークフローは対象パッケージの `package.json` を更新し(changesetファイルもパッケージごとのCHANGELOG.mdも無く、代わりにマージ済みPRから生成されるGitHubの自動リリースノートを使用)、`base/*.base.md` から生成される全ドキュメントを再生成し、**trusted publishing**(OIDC。`NPM_TOKEN` 不要。パッケージごとに npmjs.com 側でそのパッケージ自身のワークフローファイルを指定して設定)で `npm publish` する。 @@ -803,7 +803,7 @@ translate: { - The calling convention (once per paragraph, or all at once as a batch) isn't decided by the core — **middleware authors are free to implement it either way**. Two forms are allowed for this reason: - Single form: `(ctx: TranslateContext, next) => Promise` — the simplest form, called once per item. - Batch form: `(ctxs: TranslateContext[]) => Promise<(string | null)[]>` — for when multiple items should be processed together in one call. The core looks at a middleware's shape (its function signature/flag) and passes items one at a time for a single-form middleware, or all missing items together for a batch-form one. - - Kiritan itself doesn't bundle concrete official middlewares like `google`/`deepl` (to avoid adding dependencies). Reference implementation examples are provided in the docs (`docs/`). + - Kiritan itself doesn't bundle concrete provider middlewares (to avoid adding dependencies). They ship as separate packages instead, starting with `@kiritan/deepl` (chapter 13). - Anywhere auto-translation fills a gap, it's always marked `machine: true` (a field for `catalog`, a comment marker for `sidecar`/`inline`), so `kiritan check` can detect it as awaiting review. - The whole chain can be wholesale-overridden per source (`sources[i].translate`). ::: @@ -812,16 +812,16 @@ translate: { - 呼び出し方(段落ごとに1回 or まとめてバッチ)はコアが決め打ちにせず、**ミドルウェア作成者が自由に実装できる**ようにする。そのため2つの形を許容する: - 単発形: `(ctx: TranslateContext, next) => Promise` — 1件ずつ呼ばれる、最も単純な形。 - バッチ形: `(ctxs: TranslateContext[]) => Promise<(string | null)[]>` — 1回の呼び出しで複数件まとめて処理したい場合用。コアはミドルウェアの形(関数のシグネチャ/フラグ)を見て、単発なら1件ずつ、バッチなら missing 分をまとめて渡す。 - - Kiritan 自体は `google`/`deepl` 等の具体的な公式ミドルウェアを内蔵しない(依存を増やさない)。ドキュメント(`docs/`)にリファレンス実装例を載せる。 + - Kiritan 自体は具体的なプロバイダのミドルウェアを内蔵しない(依存を増やさない)。代わりに別パッケージとして提供し、まず `@kiritan/deepl` から始める(13章)。 - 自動翻訳で埋まった箇所は必ず `machine: true` としてマーキングし(`catalog` はフィールド、`sidecar`/`inline` はコメントマーカー)、`kiritan check` でレビュー待ちとして検出できるようにする。 - ソース単位(`sources[i].translate`)でチェーン自体を丸ごと上書きできる。 ::: :::kiritan{locale=en} -> Splitting out official reference implementations as separate packages, such as `@kiritan/google-translate` `@kiritan/deepl`, is also under future consideration (see chapter 13). +> Official reference implementations are split out as separate packages, such as `@kiritan/deepl` (see chapter 13). ::: :::kiritan{locale=ja} -> 将来的に、公式のリファレンス実装を `@kiritan/google-translate` `@kiritan/deepl` のような別パッケージとして切り出すことも検討する(13章参照)。 +> 公式のリファレンス実装は、`@kiritan/deepl` のように別パッケージとして切り出している(13章参照)。 ::: :::kiritan{locale=en} @@ -1241,7 +1241,7 @@ None at this time. Anything that comes up during implementation will be appended ::: :::kiritan{locale=en} -- **Official translate-middleware packages**: adding reference implementations like Google Translate / DeepL as separate packages (`@kiritan/google-translate`, `@kiritan/deepl`) under `packages/*`. Not added in v1 — only implementation examples are provided in the docs. +- **Official translate-middleware packages**: [`@kiritan/deepl`](../packages/deepl) is done — `deepl()` (one request per item) and `deeplBatch()` (one request per language pair, up to DeepL's 50 texts). `%{name}` placeholders are wrapped in a tag DeepL is told to ignore (`tag_handling: xml` with `ignore_tags`), which is also why the rest of the text is XML-escaped on the way in and un-escaped on the way out. The request shape is unit-tested against DeepL's documented API with a fake `fetch`, but has not been run against the live service. `@kiritan/google-translate` is still open. - **AI Agent Skill**: [`skills/kiritan`](../skills/kiritan) — done. A single self-contained `SKILL.md` (no npm package, no build step) teaching a coding agent the directive syntax, which CLI command to reach for, and common mistakes to avoid. See [skills/README.md](../skills/README.md) for installation. - **`kiritan init`**: done. Scaffolds `.kiritanconfig`, `base/README.base.md`, and a `.gitignore` entry for `local.kiritanconfig` in a fresh project — the generated config points `sources` at `base/README.base.md` with `naming.template` overridden to strip `{dir}` (so `README.md`/`README.ja.md` land at the project root rather than inside `base/`, matching the convention this repo's own `.kiritanconfig` uses) and a `runtime.sources` entry recommending the `colocated` strategy (chapter 9.1). Every file is left alone if it already exists unless `--force` is passed, so running it again in a partially-set-up project is safe. - **A per-command `--locale` flag**: done, for `build`/`check`/`translate`/`extract` — each accepts `--locale ` to restrict a run to one locale instead of every locale in `locales.list`, via a shared `resolveTargetLocales` helper that also rejects a locale not in `locales.list` with a clear error. `build`'s switcher links still cover every configured locale regardless of `--locale`, since the other locales' files already exist on disk and the switcher isn't only describing the current run. `kiritan typegen` doesn't support it — it always aggregates every locale into one runtime module, so there's no meaningful way to restrict it to one. @@ -1252,7 +1252,7 @@ None at this time. Anything that comes up during implementation will be appended - **`text`/`mdx` renderers and front-matter protection**: v1 only implements the `markdown` renderer; `.txt`/`.mdx` support and `translateFrontmatter` (chapter 6) are design-stage only. ::: :::kiritan{locale=ja} -- **翻訳ミドルウェアの公式パッケージ化**: Google 翻訳 / DeepL などの参考実装を `@kiritan/google-translate` `@kiritan/deepl` のような別パッケージとして `packages/*` に追加する。v1 では追加せず、ドキュメントに実装例を載せるだけに留める。 +- **翻訳ミドルウェアの公式パッケージ化**: [`@kiritan/deepl`](../packages/deepl) は対応済み — `deepl()`(1件ごとに1リクエスト)と `deeplBatch()`(言語ペアごとに1リクエスト、DeepLの上限である50件まで)。`%{name}` のプレースホルダーはDeepLに無視させるタグ(`tag_handling: xml` と `ignore_tags`)で包んでおり、残りのテキストを送信時にXMLエスケープ、受信時にアンエスケープするのもそのため。リクエストの形はDeepL公式のAPI仕様に照らして偽の `fetch` でユニットテストしているが、実際のサービスに対しては実行していない。`@kiritan/google-translate` は未着手のまま。 - **AI Agent Skill**: [`skills/kiritan`](../skills/kiritan) —対応済み。npmパッケージでもビルドも不要な、単一の自己完結した `SKILL.md` として、ディレクティブ記法・どのCLIコマンドを使うべきか・よくある間違いをコーディングエージェントに教える。導入方法は [skills/README.md](../skills/README.md) を参照。 - **`kiritan init`**: 対応済み。新規プロジェクトで `.kiritanconfig`・`base/README.base.md`・`local.kiritanconfig` の `.gitignore` への追記を生成する — 生成される設定は `sources` を `base/README.base.md` に向け、`naming.template` を `{dir}` を除いた形に上書きする(このリポジトリ自身の `.kiritanconfig` と同じ規約で、`README.md`/`README.ja.md` が `base/` 内ではなくプロジェクトルートに出力されるようにするため)。あわせて `colocated` 戦略(9.1章)を推奨する `runtime.sources` エントリも含める。書き込み先のファイルが既に存在する場合は `--force` を付けない限りそのまま残すため、一部だけ既に用意されているプロジェクトで再実行しても安全。 - **コマンド共通の `--locale` フラグ**: 対応済み。`build`/`check`/`translate`/`extract` がそれぞれ `--locale ` を受け付け、実行対象を `locales.list` 全体ではなく1ロケールに絞れる。共通のヘルパー `resolveTargetLocales` を介しており、`locales.list` に無いロケールを指定した場合は分かりやすいエラーで弾く。`build` のswitcherリンクは `--locale` の指定に関わらず設定済みの全ロケールを表示し続ける — 他のロケールのファイルは既にディスク上に存在しており、switcherは今回の実行だけを説明するものではないため。`kiritan typegen` だけは対応しない — 常に全ロケールを1つのランタイムモジュールに集約するコマンドのため、1ロケールに絞る意味のある方法が無い。 diff --git a/base/README.base.md b/base/README.base.md index 1b63bde..405d3a6 100644 --- a/base/README.base.md +++ b/base/README.base.md @@ -25,6 +25,7 @@ This is an npm workspaces monorepo. The full design lives in [docs/DESIGN.md](./ | --- | --- | --- | | [`kiritan`](./packages/kiritan) | `packages/kiritan` | The CLI + build pipeline: config, translation stores, renderers, translate middlewares | | [`@kiritan/runtime`](./packages/runtime) | `packages/runtime` | The minimal `t(key, params)` runtime, with no build-time dependencies | +| [`@kiritan/deepl`](./packages/deepl) | `packages/deepl` | A [DeepL](https://www.deepl.com/) translate middleware for `translate.middlewares` | ## Related tooling @@ -42,6 +43,7 @@ This is an npm workspaces monorepo. The full design lives in [docs/DESIGN.md](./ | --- | --- | --- | | [`kiritan`](./packages/kiritan) | `packages/kiritan` | CLI とビルドパイプライン(設定・翻訳ストア・レンダラー・翻訳ミドルウェア) | | [`@kiritan/runtime`](./packages/runtime) | `packages/runtime` | ビルド時依存を持たない、最小限の `t(key, params)` ランタイム | +| [`@kiritan/deepl`](./packages/deepl) | `packages/deepl` | `translate.middlewares` 用の [DeepL](https://www.deepl.com/) 翻訳ミドルウェア | ## 関連ツール diff --git a/docs/DESIGN.ja.md b/docs/DESIGN.ja.md index 800a208..7594187 100644 --- a/docs/DESIGN.ja.md +++ b/docs/DESIGN.ja.md @@ -79,10 +79,10 @@ packages/runtime/src/ - `kiritan` から `kiritan/runtime` を re-export する形は取らず、`@kiritan/runtime` を独立パッケージにする(`kiritan` は `@kiritan/runtime` に依存しても、逆はない)。ランタイムだけを使いたいプロジェクトが `kiritan` 本体(remark 等のビルド時依存)を一切引き込まずに済む。 - CLI(`src/cli.ts`)以外はすべて CJS/ESM 両対応を維持する。remark/unified/micromark 系の依存は ESM 専用パッケージしか無い(CJS版へ戻すことは「古いバージョンを使う」ことになるため避ける)ため、`tsdown.config.ts` の `deps.alwaysBundle` でこれらを `dist/index.{cjs,mjs}` に直接バンドルし、CJS 利用者が ESM 専用パッケージを `require` する場面自体を無くす。CLI 専用の `citty` はバンドルせず外部依存のままでよい。 -- 将来追加する翻訳ミドルウェアの参考実装(`@kiritan/google-translate` など、13章)も同じワークスペースの `packages/*` に追加していく想定。 +- 翻訳ミドルウェアの参考実装(`@kiritan/deepl`、13章)は同じワークスペースの `packages/*` に置く。それぞれ単体で完結し、`kiritan` には依存しない — ミドルウェアは `translate.middlewares` と構造的に互換な形の単なる関数であるため。 - `extensions/vscode`(VS Code拡張機能、13章)は `packages/` の外に置くため、ルートの `"workspaces": ["packages/*"]` には拾われない — `package.json` の `"name"` が `"kiritan"` で、CLIパッケージ自身の名前と衝突してしまう(npm workspaceは同名パッケージを2つ持てない)ため。ビルド・テストに必要なツールはパッケージ側ではなく、ルートの `devDependency` として持たせる。 - 既存の `tsdown` / `vitest` / `eslint` / CI(`ci.yml` およびリリース用ワークフロー)はワークスペース対応に更新が必要(各パッケージごとのビルド・テスト・公開)。これは設計確定後の実装タスクとして扱う。 -- バージョニングは **パッケージごとに独立**させる(lockstep にしない。共有のchangelog生成ツールも使わない)。パッケージごとに専用の `workflow_dispatch` ワークフロー(`release.yml` / `release-runtime.yml`)を持ち、どちらも実際の処理を行う共通の再利用可能ワークフロー(`_release-package.yml`)への薄いラッパーにすることで、片方のリリースがもう片方に誤って影響することを防ぐ: +- バージョニングは **パッケージごとに独立**させる(lockstep にしない。共有のchangelog生成ツールも使わない)。パッケージごとに専用の `workflow_dispatch` ワークフロー(`release.yml` / `release-runtime.yml` / `release-deepl.yml`)を持ち、どちらも実際の処理を行う共通の再利用可能ワークフロー(`_release-package.yml`)への薄いラッパーにすることで、片方のリリースがもう片方に誤って影響することを防ぐ: 1. Actions タブから `release-` を、`version`(semverのbump種別 `patch`/`minor`/`major`/`prerelease`、または明示的なバージョン。そのまま `npm version` に渡す)と `dist_tag`(npm dist-tag。空なら自動判定)の2つの入力で実行する。 2. ワークフローは対象パッケージの `package.json` を更新し(changesetファイルもパッケージごとのCHANGELOG.mdも無く、代わりにマージ済みPRから生成されるGitHubの自動リリースノートを使用)、`base/*.base.md` から生成される全ドキュメントを再生成し、**trusted publishing**(OIDC。`NPM_TOKEN` 不要。パッケージごとに npmjs.com 側でそのパッケージ自身のワークフローファイルを指定して設定)で `npm publish` する。 @@ -430,11 +430,11 @@ translate: { - 呼び出し方(段落ごとに1回 or まとめてバッチ)はコアが決め打ちにせず、**ミドルウェア作成者が自由に実装できる**ようにする。そのため2つの形を許容する: - 単発形: `(ctx: TranslateContext, next) => Promise` — 1件ずつ呼ばれる、最も単純な形。 - バッチ形: `(ctxs: TranslateContext[]) => Promise<(string | null)[]>` — 1回の呼び出しで複数件まとめて処理したい場合用。コアはミドルウェアの形(関数のシグネチャ/フラグ)を見て、単発なら1件ずつ、バッチなら missing 分をまとめて渡す。 - - Kiritan 自体は `google`/`deepl` 等の具体的な公式ミドルウェアを内蔵しない(依存を増やさない)。ドキュメント(`docs/`)にリファレンス実装例を載せる。 + - Kiritan 自体は具体的なプロバイダのミドルウェアを内蔵しない(依存を増やさない)。代わりに別パッケージとして提供し、まず `@kiritan/deepl` から始める(13章)。 - 自動翻訳で埋まった箇所は必ず `machine: true` としてマーキングし(`catalog` はフィールド、`sidecar`/`inline` はコメントマーカー)、`kiritan check` でレビュー待ちとして検出できるようにする。 - ソース単位(`sources[i].translate`)でチェーン自体を丸ごと上書きできる。 -> 将来的に、公式のリファレンス実装を `@kiritan/google-translate` `@kiritan/deepl` のような別パッケージとして切り出すことも検討する(13章参照)。 +> 公式のリファレンス実装は、`@kiritan/deepl` のように別パッケージとして切り出している(13章参照)。 ### 7.1 単発形とバッチ形の混在 @@ -644,7 +644,7 @@ export type { CreateTOptions } from '@kiritan/runtime'; ## 13. ロードマップ / 将来検討 -- **翻訳ミドルウェアの公式パッケージ化**: Google 翻訳 / DeepL などの参考実装を `@kiritan/google-translate` `@kiritan/deepl` のような別パッケージとして `packages/*` に追加する。v1 では追加せず、ドキュメントに実装例を載せるだけに留める。 +- **翻訳ミドルウェアの公式パッケージ化**: [`@kiritan/deepl`](../packages/deepl) は対応済み — `deepl()`(1件ごとに1リクエスト)と `deeplBatch()`(言語ペアごとに1リクエスト、DeepLの上限である50件まで)。`%{name}` のプレースホルダーはDeepLに無視させるタグ(`tag_handling: xml` と `ignore_tags`)で包んでおり、残りのテキストを送信時にXMLエスケープ、受信時にアンエスケープするのもそのため。リクエストの形はDeepL公式のAPI仕様に照らして偽の `fetch` でユニットテストしているが、実際のサービスに対しては実行していない。`@kiritan/google-translate` は未着手のまま。 - **AI Agent Skill**: [`skills/kiritan`](../skills/kiritan) —対応済み。npmパッケージでもビルドも不要な、単一の自己完結した `SKILL.md` として、ディレクティブ記法・どのCLIコマンドを使うべきか・よくある間違いをコーディングエージェントに教える。導入方法は [skills/README.md](../skills/README.md) を参照。 - **`kiritan init`**: 対応済み。新規プロジェクトで `.kiritanconfig`・`base/README.base.md`・`local.kiritanconfig` の `.gitignore` への追記を生成する — 生成される設定は `sources` を `base/README.base.md` に向け、`naming.template` を `{dir}` を除いた形に上書きする(このリポジトリ自身の `.kiritanconfig` と同じ規約で、`README.md`/`README.ja.md` が `base/` 内ではなくプロジェクトルートに出力されるようにするため)。あわせて `colocated` 戦略(9.1章)を推奨する `runtime.sources` エントリも含める。書き込み先のファイルが既に存在する場合は `--force` を付けない限りそのまま残すため、一部だけ既に用意されているプロジェクトで再実行しても安全。 - **コマンド共通の `--locale` フラグ**: 対応済み。`build`/`check`/`translate`/`extract` がそれぞれ `--locale ` を受け付け、実行対象を `locales.list` 全体ではなく1ロケールに絞れる。共通のヘルパー `resolveTargetLocales` を介しており、`locales.list` に無いロケールを指定した場合は分かりやすいエラーで弾く。`build` のswitcherリンクは `--locale` の指定に関わらず設定済みの全ロケールを表示し続ける — 他のロケールのファイルは既にディスク上に存在しており、switcherは今回の実行だけを説明するものではないため。`kiritan typegen` だけは対応しない — 常に全ロケールを1つのランタイムモジュールに集約するコマンドのため、1ロケールに絞る意味のある方法が無い。 diff --git a/docs/DESIGN.md b/docs/DESIGN.md index aa7016f..b072653 100644 --- a/docs/DESIGN.md +++ b/docs/DESIGN.md @@ -79,10 +79,10 @@ packages/runtime/src/ - Rather than re-exporting `kiritan/runtime` from `kiritan`, `@kiritan/runtime` is its own independent package (`kiritan` may depend on `@kiritan/runtime`, but never the reverse). This lets a project that only wants the runtime avoid pulling in `kiritan` core (remark and other build-time dependencies) at all. - Everything except the CLI (`src/cli.ts`) keeps full CJS/ESM dual-format support. The remark/unified/micromark ecosystem only ships ESM-only packages (going back to a CJS release would mean "using an older version," which is avoided), so `tsdown.config.ts`'s `deps.alwaysBundle` bundles them directly into `dist/index.{cjs,mjs}`, eliminating any scenario where a CJS consumer would need to `require` an ESM-only package. `citty`, which is CLI-only, stays an external dependency and isn't bundled. -- Reference implementations of translate middlewares to be added later (e.g. `@kiritan/google-translate`, chapter 13) are also expected to be added to the same workspace under `packages/*`. +- Reference implementations of translate middlewares (`@kiritan/deepl`, chapter 13) live in the same workspace under `packages/*`. Each is standalone — it doesn't depend on `kiritan`, since a middleware is just a function whose shape is structurally compatible with `translate.middlewares`. - `extensions/vscode` (the VS Code extension, chapter 13) lives outside `packages/` and so is never picked up by the root `"workspaces": ["packages/*"]` glob — its `package.json` `"name"` is `"kiritan"`, which would otherwise collide with the CLI package's own name (an npm workspace can't have two packages sharing a name). Its build/test tooling is a root-level `devDependency` instead of a package-local one. - The existing `tsdown` / `vitest` / `eslint` / CI (`ci.yml` and the release workflows) setups need updating for workspace support (per-package build/test/publish). This is treated as an implementation task once the design is finalized. -- Versioning is **independent per package** (no lockstep, no shared changelog-generation tool). Each package has its own `workflow_dispatch` GitHub Actions workflow (`release.yml`, `release-runtime.yml`) — thin wrappers around a shared reusable workflow (`_release-package.yml`) that does the actual work — so releasing one package can never touch the other by accident: +- Versioning is **independent per package** (no lockstep, no shared changelog-generation tool). Each package has its own `workflow_dispatch` GitHub Actions workflow (`release.yml`, `release-runtime.yml`, `release-deepl.yml`) — thin wrappers around a shared reusable workflow (`_release-package.yml`) that does the actual work — so releasing one package can never touch the other by accident: 1. Trigger `release-` from the Actions tab with two inputs: `version` (a semver bump — `patch`/`minor`/`major`/`prerelease` — or an explicit version, passed straight to `npm version`) and `dist_tag` (npm dist-tag; empty auto-detects). 2. The workflow bumps that package's `package.json` (no changeset file, no per-package CHANGELOG.md — GitHub's auto-generated release notes from merged PRs are used instead), regenerates every `base/*.base.md`-derived doc, and runs `npm publish` with **trusted publishing** (OIDC — no `NPM_TOKEN` needed, configured per-package on npmjs.com pointing at that package's own workflow file). @@ -430,11 +430,11 @@ translate: { - The calling convention (once per paragraph, or all at once as a batch) isn't decided by the core — **middleware authors are free to implement it either way**. Two forms are allowed for this reason: - Single form: `(ctx: TranslateContext, next) => Promise` — the simplest form, called once per item. - Batch form: `(ctxs: TranslateContext[]) => Promise<(string | null)[]>` — for when multiple items should be processed together in one call. The core looks at a middleware's shape (its function signature/flag) and passes items one at a time for a single-form middleware, or all missing items together for a batch-form one. - - Kiritan itself doesn't bundle concrete official middlewares like `google`/`deepl` (to avoid adding dependencies). Reference implementation examples are provided in the docs (`docs/`). + - Kiritan itself doesn't bundle concrete provider middlewares (to avoid adding dependencies). They ship as separate packages instead, starting with `@kiritan/deepl` (chapter 13). - Anywhere auto-translation fills a gap, it's always marked `machine: true` (a field for `catalog`, a comment marker for `sidecar`/`inline`), so `kiritan check` can detect it as awaiting review. - The whole chain can be wholesale-overridden per source (`sources[i].translate`). -> Splitting out official reference implementations as separate packages, such as `@kiritan/google-translate` `@kiritan/deepl`, is also under future consideration (see chapter 13). +> Official reference implementations are split out as separate packages, such as `@kiritan/deepl` (see chapter 13). ### 7.1 Mixing single-form and batch-form middlewares @@ -644,7 +644,7 @@ None at this time. Anything that comes up during implementation will be appended ## 13. Roadmap / future considerations -- **Official translate-middleware packages**: adding reference implementations like Google Translate / DeepL as separate packages (`@kiritan/google-translate`, `@kiritan/deepl`) under `packages/*`. Not added in v1 — only implementation examples are provided in the docs. +- **Official translate-middleware packages**: [`@kiritan/deepl`](../packages/deepl) is done — `deepl()` (one request per item) and `deeplBatch()` (one request per language pair, up to DeepL's 50 texts). `%{name}` placeholders are wrapped in a tag DeepL is told to ignore (`tag_handling: xml` with `ignore_tags`), which is also why the rest of the text is XML-escaped on the way in and un-escaped on the way out. The request shape is unit-tested against DeepL's documented API with a fake `fetch`, but has not been run against the live service. `@kiritan/google-translate` is still open. - **AI Agent Skill**: [`skills/kiritan`](../skills/kiritan) — done. A single self-contained `SKILL.md` (no npm package, no build step) teaching a coding agent the directive syntax, which CLI command to reach for, and common mistakes to avoid. See [skills/README.md](../skills/README.md) for installation. - **`kiritan init`**: done. Scaffolds `.kiritanconfig`, `base/README.base.md`, and a `.gitignore` entry for `local.kiritanconfig` in a fresh project — the generated config points `sources` at `base/README.base.md` with `naming.template` overridden to strip `{dir}` (so `README.md`/`README.ja.md` land at the project root rather than inside `base/`, matching the convention this repo's own `.kiritanconfig` uses) and a `runtime.sources` entry recommending the `colocated` strategy (chapter 9.1). Every file is left alone if it already exists unless `--force` is passed, so running it again in a partially-set-up project is safe. - **A per-command `--locale` flag**: done, for `build`/`check`/`translate`/`extract` — each accepts `--locale ` to restrict a run to one locale instead of every locale in `locales.list`, via a shared `resolveTargetLocales` helper that also rejects a locale not in `locales.list` with a clear error. `build`'s switcher links still cover every configured locale regardless of `--locale`, since the other locales' files already exist on disk and the switcher isn't only describing the current run. `kiritan typegen` doesn't support it — it always aggregates every locale into one runtime module, so there's no meaningful way to restrict it to one. diff --git a/package-lock.json b/package-lock.json index 7139f9c..4964fd8 100644 --- a/package-lock.json +++ b/package-lock.json @@ -589,6 +589,10 @@ "dev": true, "license": "MIT" }, + "node_modules/@kiritan/deepl": { + "resolved": "packages/deepl", + "link": true + }, "node_modules/@kiritan/runtime": { "resolved": "packages/runtime", "link": true @@ -8299,6 +8303,14 @@ "url": "https://github.com/sponsors/wooorm" } }, + "packages/deepl": { + "name": "@kiritan/deepl", + "version": "0.0.0", + "license": "WTFPL", + "engines": { + "node": ">=22.7.0" + } + }, "packages/kiritan": { "version": "0.4.0", "license": "WTFPL", diff --git a/packages/deepl/LICENSE b/packages/deepl/LICENSE new file mode 100644 index 0000000..6c1b992 --- /dev/null +++ b/packages/deepl/LICENSE @@ -0,0 +1,13 @@ + DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE + Version 2, December 2004 + + Copyright (C) 2026 otoneko. + + Everyone is permitted to copy and distribute verbatim or modified + copies of this license document, and changing it is allowed as long + as the name is changed. + + DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE + TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION + + 0. You just DO WHAT THE FUCK YOU WANT TO. diff --git a/packages/deepl/README.ja.md b/packages/deepl/README.ja.md new file mode 100644 index 0000000..850b932 --- /dev/null +++ b/packages/deepl/README.ja.md @@ -0,0 +1,77 @@ +
+ +![kiritan-logo](../../assets/kiritan-logo.png) + +# @kiritan/deepl + +[English](README.md) | **日本語** + +
+ +> [Kiritan](https://www.npmjs.com/package/kiritan) 用の [DeepL](https://www.deepl.com/) 翻訳ミドルウェア。`translate.middlewares` に差し込むと、`kiritan translate` が未翻訳・staleな翻訳を埋める。 + +[![npm](https://img.shields.io/npm/v/%40kiritan%2Fdeepl)](https://www.npmjs.com/package/@kiritan/deepl) + +## インストール + +```sh +npm install --save-dev @kiritan/deepl +``` + +## 使い方 + +```js +// .kiritanconfig +import { deepl } from "@kiritan/deepl"; + +export default { + locales: { default: "en", list: ["en", "ja"] }, + sources: [{ glob: "base/README.base.md", strategy: "sidecar" }], + translate: { + middlewares: [deepl({ apiKey: process.env.DEEPL_API_KEY })], + }, +}; +``` + +`sidecar` では、ドキュメント全体が1つのテキストとしてDeepLに送られ、翻訳結果がsidecarファイルになる。`catalog` では、ベースファイル内の `:::kiritan{#id}` ブロックごとに個別に翻訳される — ベースファイルにこのブロックが無ければ、翻訳するものが何も無い。 + +`catalog` のidが多い場合は、`deepl` の代わりに `deeplBatch` を使うと、1リクエストに多数のセグメント(DeepLの上限である50件・128 KiBまで)をまとめて送れるため、ずっと速い: + +```js +import { deeplBatch } from "@kiritan/deepl"; + +export default { + // ... + translate: { + middlewares: [deeplBatch({ apiKey: process.env.DEEPL_API_KEY })], + }, +}; +``` + +### オプション + +| オプション | 説明 | +| ----------------- | ------------------------------------------------------------------------------------------------------------------- | +| `apiKey` | DeepLのAPIキー(必須)。`:fx` で終わるキーは無料API、それ以外はPro APIを使う。 | +| `baseUrl` | エンドポイントを上書きする。 | +| `targetLanguages` | DeepLの `target_lang` をロケールごとに上書きする。例: `{ en: "EN-GB" }`。既定では `en` は `EN-US`、`pt` は `PT-BR`。 | +| `extraParams` | リクエストボディにマージする追加フィールド。例: `{ formality: "prefer_less" }`。 | +| `fetch` | テストやプロキシ用の独自の `fetch`。 | + +### 挙動 + +- `%{name}` のプレースホルダーは変更されずに戻る: DeepLが無視するよう指示したタグ(`tag_handling: xml`)で包み、残りのテキストは送信時にXMLエスケープ、受信時にアンエスケープする。 +- それ以外のテキストはそのまま送られるため、セグメント内のMarkdown構文(リンク・強調・コード)の扱いはDeepL自身に任される。公開前に機械翻訳をレビューすること — この方法で書き込まれた `catalog` のエントリは、レビューするまで `kiritan check` が `machine` として報告する。 +- 応答がOKでない場合は例外を投げ、`kiritan translate` はDeepL自身のメッセージ(無効なキー、使い切ったクォータ等)とともに停止する。 + +## 動作環境 + +- Node.js >= 22.7(グローバルの `fetch` を使用) + +## コントリビュート + +コントリビューションを歓迎します。詳細は [CONTRIBUTING.md](https://github.com/otnc/kiritan/blob/main/CONTRIBUTING.md) を参照してください。 + +## ライセンス + +[WTFPL License](https://github.com/otnc/kiritan/blob/main/LICENSE) の下で配布されています。 diff --git a/packages/deepl/README.md b/packages/deepl/README.md new file mode 100644 index 0000000..fc6de1b --- /dev/null +++ b/packages/deepl/README.md @@ -0,0 +1,77 @@ +
+ +![kiritan-logo](../../assets/kiritan-logo.png) + +# @kiritan/deepl + +**English** | [日本語](README.ja.md) + +
+ +> A [DeepL](https://www.deepl.com/) translate middleware for [Kiritan](https://www.npmjs.com/package/kiritan). Plug it into `translate.middlewares` to have `kiritan translate` fill in missing and stale translations. + +[![npm](https://img.shields.io/npm/v/%40kiritan%2Fdeepl)](https://www.npmjs.com/package/@kiritan/deepl) + +## Install + +```sh +npm install --save-dev @kiritan/deepl +``` + +## Usage + +```js +// .kiritanconfig +import { deepl } from "@kiritan/deepl"; + +export default { + locales: { default: "en", list: ["en", "ja"] }, + sources: [{ glob: "base/README.base.md", strategy: "sidecar" }], + translate: { + middlewares: [deepl({ apiKey: process.env.DEEPL_API_KEY })], + }, +}; +``` + +With `sidecar`, the whole document goes to DeepL as one text and comes back as the translated sidecar file. With `catalog`, each `:::kiritan{#id}` block in the base file is translated separately — the base file needs those blocks, or there is nothing to translate. + +Use `deeplBatch` instead of `deepl` to send many segments per request (up to DeepL's limits of 50 texts / 128 KiB), which is much faster for a `catalog` source with lots of ids: + +```js +import { deeplBatch } from "@kiritan/deepl"; + +export default { + // ... + translate: { + middlewares: [deeplBatch({ apiKey: process.env.DEEPL_API_KEY })], + }, +}; +``` + +### Options + +| Option | Description | +| ----------------- | ----------------------------------------------------------------------------------------------------------------- | +| `apiKey` | Your DeepL API key (required). A key ending in `:fx` uses the free API, any other the Pro API. | +| `baseUrl` | Overrides the endpoint. | +| `targetLanguages` | Per-locale overrides of the DeepL `target_lang`, e.g. `{ en: "EN-GB" }`. `en` defaults to `EN-US`, `pt` to `PT-BR`. | +| `extraParams` | Extra fields merged into the request body, e.g. `{ formality: "prefer_less" }`. | +| `fetch` | A custom `fetch`, for testing or a proxy. | + +### Behavior + +- `%{name}` placeholders come back unchanged: they're wrapped in a tag DeepL is told to ignore (`tag_handling: xml`), and the rest of the text is XML-escaped on the way in and un-escaped on the way out. +- Text is sent as-is otherwise, so Markdown syntax in a segment (links, emphasis, code) is left to DeepL's own handling. Review machine translations before publishing them — `kiritan check` flags `catalog` entries written this way as `machine` until you do. +- A non-OK response throws, and `kiritan translate` stops with DeepL's own message (an invalid key, an exhausted quota, ...). + +## Requirements + +- Node.js >= 22.7 (uses the global `fetch`) + +## Contributing + +Contributions are welcome! See [CONTRIBUTING.md](https://github.com/otnc/kiritan/blob/main/CONTRIBUTING.md) for details. + +## License + +Distributed under the [WTFPL License](https://github.com/otnc/kiritan/blob/main/LICENSE). diff --git a/packages/deepl/base/README.base.md b/packages/deepl/base/README.base.md new file mode 100644 index 0000000..2fb8a78 --- /dev/null +++ b/packages/deepl/base/README.base.md @@ -0,0 +1,134 @@ +
+ +![kiritan-logo](../../assets/kiritan-logo.png) + +# @kiritan/deepl + +
+ +:::kiritan{locale=en} +> A [DeepL](https://www.deepl.com/) translate middleware for [Kiritan](https://www.npmjs.com/package/kiritan). Plug it into `translate.middlewares` to have `kiritan translate` fill in missing and stale translations. +::: +:::kiritan{locale=ja} +> [Kiritan](https://www.npmjs.com/package/kiritan) 用の [DeepL](https://www.deepl.com/) 翻訳ミドルウェア。`translate.middlewares` に差し込むと、`kiritan translate` が未翻訳・staleな翻訳を埋める。 +::: + +[![npm](https://img.shields.io/npm/v/%40kiritan%2Fdeepl)](https://www.npmjs.com/package/@kiritan/deepl) + +:::kiritan{locale=en} +## Install +::: +:::kiritan{locale=ja} +## インストール +::: + +```sh +npm install --save-dev @kiritan/deepl +``` + +:::kiritan{locale=en} +## Usage +::: +:::kiritan{locale=ja} +## 使い方 +::: + +```js +// .kiritanconfig +import { deepl } from "@kiritan/deepl"; + +export default { + locales: { default: "en", list: ["en", "ja"] }, + sources: [{ glob: "base/README.base.md", strategy: "sidecar" }], + translate: { + middlewares: [deepl({ apiKey: process.env.DEEPL_API_KEY })], + }, +}; +``` + +:::kiritan{locale=en} +With `sidecar`, the whole document goes to DeepL as one text and comes back as the translated sidecar file. With `catalog`, each `:::kiritan{#id}` block in the base file is translated separately — the base file needs those blocks, or there is nothing to translate. +::: +:::kiritan{locale=ja} +`sidecar` では、ドキュメント全体が1つのテキストとしてDeepLに送られ、翻訳結果がsidecarファイルになる。`catalog` では、ベースファイル内の `:::kiritan{#id}` ブロックごとに個別に翻訳される — ベースファイルにこのブロックが無ければ、翻訳するものが何も無い。 +::: + +:::kiritan{locale=en} +Use `deeplBatch` instead of `deepl` to send many segments per request (up to DeepL's limits of 50 texts / 128 KiB), which is much faster for a `catalog` source with lots of ids: +::: +:::kiritan{locale=ja} +`catalog` のidが多い場合は、`deepl` の代わりに `deeplBatch` を使うと、1リクエストに多数のセグメント(DeepLの上限である50件・128 KiBまで)をまとめて送れるため、ずっと速い: +::: + +```js +import { deeplBatch } from "@kiritan/deepl"; + +export default { + // ... + translate: { + middlewares: [deeplBatch({ apiKey: process.env.DEEPL_API_KEY })], + }, +}; +``` + +:::kiritan{locale=en} +### Options + +| Option | Description | +| ----------------- | ----------------------------------------------------------------------------------------------------------------- | +| `apiKey` | Your DeepL API key (required). A key ending in `:fx` uses the free API, any other the Pro API. | +| `baseUrl` | Overrides the endpoint. | +| `targetLanguages` | Per-locale overrides of the DeepL `target_lang`, e.g. `{ en: "EN-GB" }`. `en` defaults to `EN-US`, `pt` to `PT-BR`. | +| `extraParams` | Extra fields merged into the request body, e.g. `{ formality: "prefer_less" }`. | +| `fetch` | A custom `fetch`, for testing or a proxy. | + +### Behavior + +- `%{name}` placeholders come back unchanged: they're wrapped in a tag DeepL is told to ignore (`tag_handling: xml`), and the rest of the text is XML-escaped on the way in and un-escaped on the way out. +- Text is sent as-is otherwise, so Markdown syntax in a segment (links, emphasis, code) is left to DeepL's own handling. Review machine translations before publishing them — `kiritan check` flags `catalog` entries written this way as `machine` until you do. +- A non-OK response throws, and `kiritan translate` stops with DeepL's own message (an invalid key, an exhausted quota, ...). +::: +:::kiritan{locale=ja} +### オプション + +| オプション | 説明 | +| ----------------- | ------------------------------------------------------------------------------------------------------------------- | +| `apiKey` | DeepLのAPIキー(必須)。`:fx` で終わるキーは無料API、それ以外はPro APIを使う。 | +| `baseUrl` | エンドポイントを上書きする。 | +| `targetLanguages` | DeepLの `target_lang` をロケールごとに上書きする。例: `{ en: "EN-GB" }`。既定では `en` は `EN-US`、`pt` は `PT-BR`。 | +| `extraParams` | リクエストボディにマージする追加フィールド。例: `{ formality: "prefer_less" }`。 | +| `fetch` | テストやプロキシ用の独自の `fetch`。 | + +### 挙動 + +- `%{name}` のプレースホルダーは変更されずに戻る: DeepLが無視するよう指示したタグ(`tag_handling: xml`)で包み、残りのテキストは送信時にXMLエスケープ、受信時にアンエスケープする。 +- それ以外のテキストはそのまま送られるため、セグメント内のMarkdown構文(リンク・強調・コード)の扱いはDeepL自身に任される。公開前に機械翻訳をレビューすること — この方法で書き込まれた `catalog` のエントリは、レビューするまで `kiritan check` が `machine` として報告する。 +- 応答がOKでない場合は例外を投げ、`kiritan translate` はDeepL自身のメッセージ(無効なキー、使い切ったクォータ等)とともに停止する。 +::: + +:::kiritan{locale=en} +## Requirements + +- Node.js >= 22.7 (uses the global `fetch`) + +## Contributing + +Contributions are welcome! See [CONTRIBUTING.md](https://github.com/otnc/kiritan/blob/main/CONTRIBUTING.md) for details. + +## License + +Distributed under the [WTFPL License](https://github.com/otnc/kiritan/blob/main/LICENSE). +::: +:::kiritan{locale=ja} +## 動作環境 + +- Node.js >= 22.7(グローバルの `fetch` を使用) + +## コントリビュート + +コントリビューションを歓迎します。詳細は [CONTRIBUTING.md](https://github.com/otnc/kiritan/blob/main/CONTRIBUTING.md) を参照してください。 + +## ライセンス + +[WTFPL License](https://github.com/otnc/kiritan/blob/main/LICENSE) の下で配布されています。 +::: diff --git a/packages/deepl/package.json b/packages/deepl/package.json new file mode 100644 index 0000000..3afc839 --- /dev/null +++ b/packages/deepl/package.json @@ -0,0 +1,50 @@ +{ + "name": "@kiritan/deepl", + "version": "0.0.0", + "description": "A DeepL translate middleware for Kiritan / KiritanのDeepL翻訳ミドルウェア", + "keywords": [ + "deepl", + "translate", + "translation", + "machine-translation", + "middleware", + "i18n", + "kiritan" + ], + "homepage": "https://github.com/otnc/kiritan#readme", + "bugs": { + "url": "https://github.com/otnc/kiritan/issues" + }, + "repository": { + "type": "git", + "url": "git+https://github.com/otnc/kiritan.git", + "directory": "packages/deepl" + }, + "license": "WTFPL", + "author": "otoneko.", + "type": "module", + "main": "dist/index.cjs", + "module": "dist/index.mjs", + "types": "dist/index.d.mts", + "exports": { + ".": { + "types": { + "import": "./dist/index.d.mts", + "require": "./dist/index.d.cts" + }, + "import": "./dist/index.mjs", + "require": "./dist/index.cjs" + } + }, + "files": [ + "dist", + "README.ja.md" + ], + "engines": { + "node": ">=22.7.0" + }, + "scripts": { + "build": "tsdown", + "typecheck": "tsc --noEmit" + } +} diff --git a/packages/deepl/src/index.test.ts b/packages/deepl/src/index.test.ts new file mode 100644 index 0000000..56da454 --- /dev/null +++ b/packages/deepl/src/index.test.ts @@ -0,0 +1,237 @@ +import { describe, expect, it, vi } from "vitest"; +import { + deepl, + deeplBatch, + protect, + restore, + toDeepLSource, + toDeepLTarget, +} from "./index.js"; + +interface Captured { + url: string; + init: RequestInit; + body: Record; +} + +/** A fake `fetch` that records each request and answers with `respond(texts)`. */ +function fakeFetch( + respond: (texts: string[]) => string[] = (texts) => + texts.map((text) => `T(${text})`), + status = 200 +) { + const calls: Captured[] = []; + const impl = vi.fn( + async (url: string | URL | Request, init?: RequestInit) => { + const body = JSON.parse(String(init?.body)) as Record; + calls.push({ url: String(url), init: init ?? {}, body }); + if (status !== 200) { + return new Response("quota exceeded", { status }); + } + return Response.json({ + translations: respond(body.text as string[]).map((text) => ({ text })), + }); + } + ); + return { calls, fetch: impl as unknown as typeof fetch }; +} + +const ctx = (text: string, from = "en", to = "ja") => ({ text, from, to }); +const next = async () => null; + +describe("language codes", () => { + it("uppercases a target and gives EN/PT their required regional variant", () => { + expect(toDeepLTarget("ja")).toBe("JA"); + expect(toDeepLTarget("zh-Hans")).toBe("ZH-HANS"); + expect(toDeepLTarget("en")).toBe("EN-US"); + expect(toDeepLTarget("pt")).toBe("PT-BR"); + }); + + it("lets a per-locale override win", () => { + expect(toDeepLTarget("en", { en: "EN-GB" })).toBe("EN-GB"); + }); + + it("strips the region from a source", () => { + expect(toDeepLSource("en-GB")).toBe("EN"); + expect(toDeepLSource("ja")).toBe("JA"); + }); +}); + +describe("placeholder protection", () => { + it("wraps %{...} in an ignored tag and escapes everything else", () => { + expect(protect("a < b & c: %{name} > 1")).toBe( + "a < b & c: %{name} > 1" + ); + }); + + it("round-trips through restore", () => { + const text = "Hi %{name}, 1 < 2 & 3 > 2 %{a}%{b}"; + expect(restore(protect(text))).toBe(text); + }); + + it("leaves text without placeholders as plain escaped text", () => { + expect(protect("plain")).toBe("plain"); + }); +}); + +describe("deepl()", () => { + it("posts one authenticated request in DeepL's documented shape", async () => { + const { calls, fetch } = fakeFetch(); + const middleware = deepl({ apiKey: "secret", fetch }); + + const result = await middleware(ctx("Hello %{name}"), next); + + expect(result).toBe("T(Hello %{name})"); + expect(calls).toHaveLength(1); + expect(calls[0].url).toBe("https://api.deepl.com/v2/translate"); + expect(calls[0].init.method).toBe("POST"); + expect(calls[0].init.headers).toMatchObject({ + Authorization: "DeepL-Auth-Key secret", + "Content-Type": "application/json", + }); + expect(calls[0].body).toEqual({ + text: ["Hello %{name}"], + source_lang: "EN", + target_lang: "JA", + tag_handling: "xml", + ignore_tags: ["x"], + }); + }); + + it("uses the free endpoint for a key ending in :fx", async () => { + const { calls, fetch } = fakeFetch(); + await deepl({ apiKey: "abc:fx", fetch })(ctx("Hi"), next); + expect(calls[0].url).toBe("https://api-free.deepl.com/v2/translate"); + }); + + it("honors baseUrl, targetLanguages, and extraParams", async () => { + const { calls, fetch } = fakeFetch(); + await deepl({ + apiKey: "k", + baseUrl: "https://proxy.example", + targetLanguages: { en: "EN-GB" }, + extraParams: { formality: "prefer_less" }, + fetch, + })(ctx("Bonjour", "fr", "en"), next); + + expect(calls[0].url).toBe("https://proxy.example/v2/translate"); + expect(calls[0].body).toMatchObject({ + source_lang: "FR", + target_lang: "EN-GB", + formality: "prefer_less", + }); + }); + + it("never lets extraParams override the fields the middleware depends on", async () => { + const { calls, fetch } = fakeFetch(); + await deepl({ + apiKey: "k", + extraParams: { tag_handling: "html", ignore_tags: [], text: ["x"] }, + fetch, + })(ctx("Hi %{a}"), next); + + expect(calls[0].body).toMatchObject({ + text: ["Hi %{a}"], + tag_handling: "xml", + ignore_tags: ["x"], + }); + }); + + it("un-escapes and un-wraps what DeepL returns", async () => { + const { fetch } = fakeFetch(() => ["%{name} <3 & more"]); + const result = await deepl({ apiKey: "k", fetch })(ctx("x"), next); + expect(result).toBe("%{name} <3 & more"); + }); + + it("throws a readable error on a non-OK response", async () => { + const { fetch } = fakeFetch(undefined, 456); + await expect( + deepl({ apiKey: "k", fetch })(ctx("Hi"), next) + ).rejects.toThrow("DeepL responded 456: quota exceeded"); + }); + + it("throws if the number of translations doesn't match", async () => { + const { fetch } = fakeFetch(() => []); + await expect( + deepl({ apiKey: "k", fetch })(ctx("Hi"), next) + ).rejects.toThrow("expected 1 translation(s), got 0"); + }); +}); + +describe("deeplBatch()", () => { + const run = ( + options: Parameters[0], + ctxs: ReturnType[] + ) => deeplBatch(options).handle(ctxs, async () => ctxs.map(() => null)); + + it("is a batch-form middleware", () => { + expect(deeplBatch({ apiKey: "k" }).batch).toBe(true); + }); + + it("sends contexts sharing a language pair in one request, keeping order", async () => { + const { calls, fetch } = fakeFetch(); + const results = await run({ apiKey: "k", fetch }, [ + ctx("one"), + ctx("two"), + ctx("three"), + ]); + expect(calls).toHaveLength(1); + expect(calls[0].body.text).toEqual(["one", "two", "three"]); + expect(results).toEqual(["T(one)", "T(two)", "T(three)"]); + }); + + it("splits different language pairs into separate requests, keeping each result in place", async () => { + const { calls, fetch } = fakeFetch(); + const results = await run({ apiKey: "k", fetch }, [ + ctx("a", "en", "ja"), + ctx("b", "en", "fr"), + ctx("c", "en", "ja"), + ]); + expect(calls.map((call) => call.body.target_lang)).toEqual(["JA", "FR"]); + expect(calls[0].body.text).toEqual(["a", "c"]); + expect(results).toEqual(["T(a)", "T(b)", "T(c)"]); + }); + + it("chunks at DeepL's 50 texts per request", async () => { + const { calls, fetch } = fakeFetch(); + const many = Array.from({ length: 120 }, (_, i) => ctx(`t${i}`)); + const results = await run({ apiKey: "k", fetch }, many); + + expect(calls.map((call) => (call.body.text as string[]).length)).toEqual([ + 50, 50, 20, + ]); + expect(results[0]).toBe("T(t0)"); + expect(results[119]).toBe("T(t119)"); + }); + + it("chunks at 120 KiB of request body as well as at 50 texts", async () => { + const { calls, fetch } = fakeFetch(); + const big = "x".repeat(70 * 1024); + const results = await run({ apiKey: "k", fetch }, [ + ctx(big), + ctx(big), + ctx("small"), + ]); + + expect(calls.map((call) => (call.body.text as string[]).length)).toEqual([ + 1, 2, + ]); + expect(results).toEqual([`T(${big})`, `T(${big})`, "T(small)"]); + }); + + it("counts bytes, not characters, and the XML escaping", async () => { + const { calls, fetch } = fakeFetch(); + // 30k "&" -> 150k bytes once escaped to "&"; 30k CJK characters -> 90k bytes. + await run({ apiKey: "k", fetch }, [ + ctx("&".repeat(30_000)), + ctx("あ".repeat(30_000)), + ]); + expect(calls).toHaveLength(2); + }); + + it("makes no request for no contexts", async () => { + const { calls, fetch } = fakeFetch(); + expect(await run({ apiKey: "k", fetch }, [])).toEqual([]); + expect(calls).toHaveLength(0); + }); +}); diff --git a/packages/deepl/src/index.ts b/packages/deepl/src/index.ts new file mode 100644 index 0000000..5f0dad2 --- /dev/null +++ b/packages/deepl/src/index.ts @@ -0,0 +1,218 @@ +/** + * The slice of Kiritan's `TranslateContext` this package reads. Declared here instead of imported from `kiritan` so the package has no dependency on it at all — a middleware is just a function, and these shapes are structurally compatible with `translate.middlewares`. + */ +export interface TranslateContextLike { + text: string; + from: string; + to: string; +} + +export type DeepLMiddleware = ( + ctx: TranslateContextLike, + next: () => Promise +) => Promise; + +export interface DeepLBatchMiddleware { + batch: true; + handle: ( + ctxs: TranslateContextLike[], + next: () => Promise<(string | null)[]> + ) => Promise<(string | null)[]>; +} + +export interface DeepLOptions { + /** Your DeepL API authentication key. */ + apiKey: string; + /** Overrides the endpoint. Default: the free API for a key ending in `:fx`, otherwise the Pro API. */ + baseUrl?: string; + /** Per-locale overrides of the DeepL language code sent as `target_lang`, e.g. `{ en: "EN-GB" }`. */ + targetLanguages?: Record; + /** Extra fields merged into the request body, e.g. `{ formality: "prefer_less" }`. */ + extraParams?: Record; + /** For testing or a custom transport. Default: the global `fetch`. */ + fetch?: typeof fetch; +} + +const FREE_URL = "https://api-free.deepl.com"; +const PRO_URL = "https://api.deepl.com"; +/** DeepL accepts at most 50 texts per request. */ +const MAX_TEXTS_PER_REQUEST = 50; +/** ...and a request body of at most 128 KiB; this leaves headroom for the other fields. */ +const MAX_BODY_BYTES = 120 * 1024; + +// DeepL's `target_lang` has no bare EN/PT — it wants the regional variant. Everything else is just the uppercased Kiritan locale. +const DEFAULT_TARGET_OVERRIDES: Record = { + EN: "EN-US", + PT: "PT-BR", +}; + +/** `ja` -> `JA`, `zh-Hans` -> `ZH-HANS`; `en`/`pt` get the regional variant DeepL requires for a target. */ +export function toDeepLTarget( + locale: string, + overrides: Record = {} +): string { + if (Object.hasOwn(overrides, locale)) return overrides[locale]; + const upper = locale.toUpperCase(); + return DEFAULT_TARGET_OVERRIDES[upper] ?? upper; +} + +/** DeepL's `source_lang` doesn't take a regional variant: `en-GB` -> `EN`. */ +export function toDeepLSource(locale: string): string { + return locale.split("-")[0].toUpperCase(); +} + +// `%{name}` placeholders must come back untouched, so each is wrapped in a tag DeepL is told to leave alone (`tag_handling: xml` + `ignore_tags`). That means the rest of the text has to be valid XML going in, and be un-escaped coming out. +const PLACEHOLDER = /%\{[^}]*\}/g; +const KEEP_TAG = "x"; + +function escapeXml(text: string): string { + return text + .replaceAll("&", "&") + .replaceAll("<", "<") + .replaceAll(">", ">"); +} + +function unescapeXml(text: string): string { + return text + .replaceAll("<", "<") + .replaceAll(">", ">") + .replaceAll("&", "&"); +} + +/** Wraps every `%{...}` in `...` and XML-escapes everything else. */ +export function protect(text: string): string { + let result = ""; + let last = 0; + for (const match of text.matchAll(PLACEHOLDER)) { + result += escapeXml(text.slice(last, match.index)); + result += `<${KEEP_TAG}>${escapeXml(match[0])}`; + last = match.index + match[0].length; + } + return result + escapeXml(text.slice(last)); +} + +/** The inverse of `protect`. */ +export function restore(text: string): string { + return unescapeXml( + text.replaceAll(`<${KEEP_TAG}>`, "").replaceAll(``, "") + ); +} + +interface DeepLResponse { + translations?: Array<{ text: string }>; +} + +async function requestTranslations( + options: DeepLOptions, + texts: string[], + from: string, + to: string +): Promise { + const baseUrl = + options.baseUrl ?? (options.apiKey.endsWith(":fx") ? FREE_URL : PRO_URL); + const doFetch = options.fetch ?? fetch; + const response = await doFetch(`${baseUrl}/v2/translate`, { + method: "POST", + headers: { + Authorization: `DeepL-Auth-Key ${options.apiKey}`, + "Content-Type": "application/json", + }, + // `extraParams` goes first so it can add fields but never override the ones placeholder protection and response ordering depend on. + body: JSON.stringify({ + ...options.extraParams, + text: texts.map(protect), + source_lang: toDeepLSource(from), + target_lang: toDeepLTarget(to, options.targetLanguages), + tag_handling: "xml", + ignore_tags: [KEEP_TAG], + }), + }); + + if (!response.ok) { + const detail = await response.text().catch(() => ""); + throw new Error( + `@kiritan/deepl: DeepL responded ${response.status}${detail ? `: ${detail}` : ""}` + ); + } + const body = (await response.json()) as DeepLResponse; + if (body.translations?.length !== texts.length) { + throw new Error( + `@kiritan/deepl: expected ${texts.length} translation(s), got ${body.translations?.length ?? 0}` + ); + } + return body.translations.map((entry) => restore(entry.text)); +} + +/** + * A single-form `translate.middlewares` entry that translates every context it sees through DeepL, one request each. + * `%{name}` placeholders come back unchanged. + */ +export function deepl(options: DeepLOptions): DeepLMiddleware { + return async (ctx) => { + const [translated] = await requestTranslations( + options, + [ctx.text], + ctx.from, + ctx.to + ); + return translated; + }; +} + +/** Splits `indexes` into runs within DeepL's per-request text count and body size (measured on the escaped, JSON-encoded text, which is what actually goes out). A single text over the size limit still goes out alone, for DeepL to reject with its own error. */ +function chunkIndexes( + indexes: number[], + ctxs: TranslateContextLike[] +): number[][] { + const chunks: number[][] = []; + let current: number[] = []; + let bytes = 0; + for (const index of indexes) { + const size = Buffer.byteLength(JSON.stringify(protect(ctxs[index].text))); + if ( + current.length > 0 && + (current.length >= MAX_TEXTS_PER_REQUEST || bytes + size > MAX_BODY_BYTES) + ) { + chunks.push(current); + current = []; + bytes = 0; + } + current.push(index); + bytes += size; + } + if (current.length > 0) chunks.push(current); + return chunks; +} + +/** + * A batch-form `translate.middlewares` entry: contexts sharing a language pair go out together, up to DeepL's 50 texts / 128 KiB per request, instead of one request each. Prefer this for a catalog with many segments. + */ +export function deeplBatch(options: DeepLOptions): DeepLBatchMiddleware { + return { + batch: true, + handle: async (ctxs) => { + const results: (string | null)[] = new Array(ctxs.length).fill(null); + const groups = new Map(); + ctxs.forEach((ctx, index) => { + const key = `${ctx.from}\u0000${ctx.to}`; + groups.set(key, [...(groups.get(key) ?? []), index]); + }); + + for (const indexes of groups.values()) { + for (const chunk of chunkIndexes(indexes, ctxs)) { + const { from, to } = ctxs[chunk[0]]; + const translated = await requestTranslations( + options, + chunk.map((index) => ctxs[index].text), + from, + to + ); + chunk.forEach((index, position) => { + results[index] = translated[position]; + }); + } + } + return results; + }, + }; +} diff --git a/packages/deepl/tsconfig.json b/packages/deepl/tsconfig.json new file mode 100644 index 0000000..1ee3610 --- /dev/null +++ b/packages/deepl/tsconfig.json @@ -0,0 +1,4 @@ +{ + "extends": "../../tsconfig.base.json", + "include": ["src", "tsdown.config.ts"] +} diff --git a/packages/deepl/tsdown.config.ts b/packages/deepl/tsdown.config.ts new file mode 100644 index 0000000..f40cc1e --- /dev/null +++ b/packages/deepl/tsdown.config.ts @@ -0,0 +1,11 @@ +import { defineConfig } from "tsdown"; + +export default defineConfig({ + entry: ["src/index.ts"], + format: ["esm", "cjs"], + dts: true, + clean: true, + // Node >= 22 supports ES2024 + target: "node22", + platform: "node", +});