@kiritan/deepl 0.0.0-reserved → 0.1.1

package/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.

package/README.ja.md

@@ -0,0 +1,82 @@
+<div align=center>
+
+![kiritan-logo](../../assets/kiritan-logo.png)
+
+# @kiritan/deepl
+
+[English](README.md) | **日本語**
+
+</div>
+
+> [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) [![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/otnc/kiritan/ci.yml?branch=main)](https://github.com/otnc/kiritan/actions) [![GitHub](https://img.shields.io/github/license/otnc/kiritan)](https://github.com/otnc/kiritan/blob/main/LICENSE) [![Node](https://img.shields.io/node/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: {
+    auto: true,
+    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: {
+    auto: true,
+    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" }`。                                    |
+| `retry` | 失敗したリクエスト(ネットワークエラー、408/409/425/429/5xx)を再試行する回数。既定: 2。 |
+| `retryDelay` | 再試行までの待ち時間(ms)。既定: 500。 |
+| `timeout` | リクエストごとのタイムアウト(ms)。既定: 30000。 |
+| `fetch`           | テストやプロキシ用の独自の `fetch`。                                                                                |
+
+### 挙動
+
+- そのまま保つべきものはすべて変更されずに戻る: コードブロック、インラインコード、URL、リンク先、HTML、front matter、`:::kiritan{...}` の行、`%{name}`。これらはテキストが手元を離れる前にトークンに置き換えられ、DeepLが触らないよう無視するよう指示したタグ(`tag_handling: xml`)で包まれ、後で元に戻される。DeepLがそのどれかを落とした場合は、リンクやコードが欠けた翻訳を書き込むのではなく実行が失敗する。([`@kiritan/middleware`](https://www.npmjs.com/package/@kiritan/middleware) の上に作られているため、`concurrency`・`minInterval`・`cache`・`protect`・`onError`・`onSkip` の各オプションも受け付ける。)
+- DeepLの128 KiBを超えるテキスト(たとえば `sidecar` 翻訳で送るREADME全体)は、段落の境界で分割し、元の間隔のまま結合し直す。保護した部分の周りの文言はDeepL任せなので、公開前に機械翻訳をレビューすること — この方法で書き込まれた `catalog` のエントリは、レビューするまで `kiritan check` が `machine` として報告する。
+- 失敗したリクエストは再試行(`retry` 参照)され、それでも失敗すれば例外を投げ、`kiritan translate` はDeepL自身のメッセージ(無効なキー、使い切ったクォータ等)とともに停止する。
+
+## 動作環境
+
+- Node.js >= 22.7(HTTP通信は [ofetch](https://github.com/unjs/ofetch) 経由)
+
+## コントリビュート
+
+コントリビューションを歓迎します。詳細は [CONTRIBUTING.md](https://github.com/otnc/kiritan/blob/main/CONTRIBUTING.md) を参照してください。
+
+## ライセンス
+
+[WTFPL License](https://github.com/otnc/kiritan/blob/main/LICENSE) の下で配布されています。

package/README.md

@@ -0,0 +1,82 @@
+<div align=center>
+
+![kiritan-logo](../../assets/kiritan-logo.png)
+
+# @kiritan/deepl
+
+**English** | [日本語](README.ja.md)
+
+</div>
+
+> 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) [![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/otnc/kiritan/ci.yml?branch=main)](https://github.com/otnc/kiritan/actions) [![GitHub](https://img.shields.io/github/license/otnc/kiritan)](https://github.com/otnc/kiritan/blob/main/LICENSE) [![Node](https://img.shields.io/node/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: {
+    auto: true,
+    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: {
+    auto: true,
+    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" }`.                                   |
+| `retry` | How many times to retry a failed request (network errors, 408/409/425/429/5xx). Default: 2. |
+| `retryDelay` | Delay between retries, in ms. Default: 500. |
+| `timeout` | Per-request timeout, in ms. Default: 30000. |
+| `fetch`           | A custom `fetch`, for testing or a proxy.                                                                         |
+
+### Behavior
+
+- Everything that must stay verbatim comes back untouched: code blocks, inline code, URLs, link destinations, HTML, front matter, `:::kiritan{...}` lines and `%{name}`. They are swapped for tokens before the text leaves your machine, wrapped in a tag DeepL is told to ignore (`tag_handling: xml`) so DeepL leaves them alone, and put back afterwards — and if DeepL drops one, the run fails instead of writing a translation that lost a link or a code span. (Built on [`@kiritan/middleware`](https://www.npmjs.com/package/@kiritan/middleware), so it also accepts its `concurrency`, `minInterval`, `cache`, `protect`, `onError` and `onSkip` options.)
+- A text over DeepL's 128 KiB (say a whole README for a `sidecar` translation) is split at paragraph boundaries and joined back with the original spacing. The wording around protected spans is up to DeepL, so review machine translations before publishing them — `kiritan check` flags `catalog` entries written this way as `machine` until you do.
+- A failed request is retried (see `retry`) and then throws, and `kiritan translate` stops with DeepL's own message (an invalid key, an exhausted quota, ...).
+
+## Requirements
+
+- Node.js >= 22.7 (HTTP goes through [ofetch](https://github.com/unjs/ofetch), its only dependency of note)
+
+## 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).

package/dist/index.cjs

@@ -0,0 +1,138 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let _kiritan_middleware = require("@kiritan/middleware");
+let node_crypto = require("node:crypto");
+let html_entities = require("html-entities");
+let ofetch = require("ofetch");
+//#region src/index.ts
+const FREE_URL = "https://api-free.deepl.com";
+const PRO_URL = "https://api.deepl.com";
+/** DeepL accepts at most 50 texts per request, in a body of at most 128 KiB. */
+const MAX_TEXTS_PER_REQUEST = 50;
+/** One text and one request's texts, in bytes of the JSON that is actually sent; headroom under 128 KiB for the other fields. */
+const MAX_TEXT_BYTES = 102400;
+const MAX_BATCH_BYTES = 122880;
+/**
+* The DeepL `target_lang` for a Kiritan locale, parsed with `Intl.Locale` so any BCP 47 tag works (`ja`, `en-US`, `zh-Hant-TW`, `pt_BR`).
+* DeepL has no bare `EN`/`PT` as a target, only a regional variant (British English if the locale says GB, else American; European Portuguese if PT, else Brazilian); Chinese is `ZH-HANS`/`ZH-HANT` by script; Norwegian is always `NB`; anything else is the upper-cased language. `overrides` (matched on the exact locale) win.
+*/
+function toDeepLTarget(locale, overrides = {}) {
+	if (Object.hasOwn(overrides, locale)) return overrides[locale];
+	const { language, region } = (0, _kiritan_middleware.parseLocale)(locale);
+	switch (language) {
+		case "en": return region === "GB" ? "EN-GB" : "EN-US";
+		case "pt": return region === "PT" ? "PT-PT" : "PT-BR";
+		case "zh": return (0, _kiritan_middleware.chineseScript)(locale) === "Hant" ? "ZH-HANT" : "ZH-HANS";
+		case "no":
+		case "nb":
+		case "nn": return "NB";
+		default: return language.toUpperCase();
+	}
+}
+/** DeepL's `source_lang` takes no regional variant or script: `en-GB` -> `EN`, `zh-Hant` -> `ZH`, `no` -> `NB`. */
+function toDeepLSource(locale) {
+	const { language } = (0, _kiritan_middleware.parseLocale)(locale);
+	return (language === "no" || language === "nn" ? "nb" : language).toUpperCase();
+}
+const KEEP_TAG = "x";
+/** Escapes the text as XML and wraps every `[[N]]` token in the ignored tag. */
+function encode(text) {
+	return (0, html_entities.encode)(text, { mode: "specialChars" }).replace(/\[\[(\d+)\]\]/g, `<${KEEP_TAG}>[[$1]]</${KEEP_TAG}>`);
+}
+/** The inverse of `encode`. */
+function decode(text) {
+	return (0, html_entities.decode)(text.replace(new RegExp(`</?${KEEP_TAG}>`, "gi"), ""), { level: "xml" });
+}
+/** A failure the layer's retry logic can read, and that says what DeepL said. */
+var DeepLError = class extends Error {
+	status;
+	retryAfter;
+	constructor(message, status, retryAfter, options) {
+		super(message, options);
+		this.status = status;
+		this.retryAfter = retryAfter;
+		this.name = "DeepLError";
+	}
+};
+function describeError(error) {
+	if (error instanceof ofetch.FetchError && error.status !== void 0) {
+		const data = error.data;
+		const detail = typeof data === "string" ? data : data ? JSON.stringify(data) : "";
+		return new DeepLError(`@kiritan/deepl: DeepL responded ${error.status}${detail ? `: ${detail}` : ""}`, error.status, (0, _kiritan_middleware.parseRetryAfter)(error.response?.headers.get("retry-after")), { cause: error });
+	}
+	return new DeepLError(`@kiritan/deepl: request to DeepL failed: ${error instanceof Error ? error.message : String(error)}`, void 0, void 0, { cause: error });
+}
+async function requestTranslations(options, texts, from, to) {
+	const baseUrl = options.baseUrl ?? (options.apiKey.endsWith(":fx") ? FREE_URL : PRO_URL);
+	const request = (0, ofetch.createFetch)({ fetch: options.fetch ?? globalThis.fetch });
+	let body;
+	try {
+		body = await request(`${baseUrl}/v2/translate`, {
+			method: "POST",
+			headers: { Authorization: `DeepL-Auth-Key ${options.apiKey}` },
+			retry: 0,
+			timeout: options.timeout ?? 3e4,
+			body: {
+				...options.extraParams,
+				text: texts,
+				source_lang: toDeepLSource(from),
+				target_lang: toDeepLTarget(to, options.targetLanguages),
+				tag_handling: "xml",
+				ignore_tags: [KEEP_TAG]
+			}
+		});
+	} catch (error) {
+		throw describeError(error);
+	}
+	if (body.translations?.length !== texts.length) throw new DeepLError(`@kiritan/deepl: expected ${texts.length} translation(s), got ${body.translations?.length ?? 0}`);
+	return body.translations.map((entry) => entry.text);
+}
+/** The size of a text as it will actually be sent: XML-wrapped and JSON-encoded, in UTF-8 bytes. */
+const wireBytes = (text) => Buffer.byteLength(JSON.stringify(encode(text)), "utf8");
+function create(options, batched) {
+	const common = {
+		name: `deepl:${(0, node_crypto.createHash)("sha1").update(JSON.stringify([options.extraParams ?? {}, options.targetLanguages ?? {}])).digest("hex").slice(0, 12)}`,
+		wire: {
+			encode,
+			decode
+		},
+		measure: wireBytes,
+		maxChars: MAX_TEXT_BYTES,
+		maxBatchChars: MAX_BATCH_BYTES,
+		maxBatchSize: batched ? MAX_TEXTS_PER_REQUEST : 1,
+		retry: {
+			retries: options.retry ?? 2,
+			delay: options.retryDelay ?? 500
+		},
+		concurrency: options.concurrency,
+		minInterval: options.minInterval,
+		cache: options.cache,
+		protect: options.protect,
+		onError: options.onError,
+		onSkip: options.onSkip,
+		async translateBatch(texts, { from, to }) {
+			return requestTranslations(options, texts, from, to);
+		}
+	};
+	for (const key of Object.keys(common)) if (common[key] === void 0) delete common[key];
+	return (0, _kiritan_middleware.createTranslator)(common);
+}
+/**
+* A `translate.middlewares` entry that translates through DeepL, one request per text.
+* Built on `@kiritan/middleware`, so code blocks, inline code, URLs, link destinations, HTML, front matter, `:::kiritan` lines and `%{name}` come back untouched (and a result that lost one is refused), a text over DeepL's size limit is split at paragraph boundaries and rejoined, and requests are retried on 429/5xx.
+*/
+function deepl(options) {
+	return create(options, false);
+}
+/**
+* The same, but texts sharing a language pair go out together — up to DeepL's 50 texts / 128 KiB per request. Prefer this for a catalog with many segments.
+*/
+function deeplBatch(options) {
+	return create(options, true);
+}
+//#endregion
+exports.decode = decode;
+exports.deepl = deepl;
+exports.deeplBatch = deeplBatch;
+exports.encode = encode;
+exports.toDeepLSource = toDeepLSource;
+exports.toDeepLTarget = toDeepLTarget;

package/dist/index.d.cts

@@ -0,0 +1,45 @@
+import { TranslatorMiddleware, TranslatorOptions } from "@kiritan/middleware";
+//#region src/index.d.ts
+type DeepLMiddleware = TranslatorMiddleware;
+/** Tuning shared with every `@kiritan/middleware`-based provider. */
+type Tuning = Pick<TranslatorOptions, "concurrency" | "minInterval" | "cache" | "protect" | "onError" | "onSkip">;
+interface DeepLOptions extends Tuning {
+  /** 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<string, string>;
+  /** Extra fields merged into the request body, e.g. `{ formality: "prefer_less" }`. They can add fields but never override the ones this middleware depends on. */
+  extraParams?: Record<string, unknown>;
+  /** How many times to retry a failed request (network errors, 408/409/425/429/5xx) before giving up. Default: 2. */
+  retry?: number;
+  /** Delay before the first retry, in ms (doubled each time). Default: 500. */
+  retryDelay?: number;
+  /** Per-request timeout, in ms. Default: 30000. */
+  timeout?: number;
+  /** For testing or a custom transport. Default: the global `fetch`. */
+  fetch?: typeof fetch;
+}
+/**
+ * The DeepL `target_lang` for a Kiritan locale, parsed with `Intl.Locale` so any BCP 47 tag works (`ja`, `en-US`, `zh-Hant-TW`, `pt_BR`).
+ * DeepL has no bare `EN`/`PT` as a target, only a regional variant (British English if the locale says GB, else American; European Portuguese if PT, else Brazilian); Chinese is `ZH-HANS`/`ZH-HANT` by script; Norwegian is always `NB`; anything else is the upper-cased language. `overrides` (matched on the exact locale) win.
+ */
+declare function toDeepLTarget(locale: string, overrides?: Record<string, string>): string;
+/** DeepL's `source_lang` takes no regional variant or script: `en-GB` -> `EN`, `zh-Hant` -> `ZH`, `no` -> `NB`. */
+declare function toDeepLSource(locale: string): string;
+/** Escapes the text as XML and wraps every `[[N]]` token in the ignored tag. */
+declare function encode(text: string): string;
+/** The inverse of `encode`. */
+declare function decode(text: string): string;
+/**
+ * A `translate.middlewares` entry that translates through DeepL, one request per text.
+ * Built on `@kiritan/middleware`, so code blocks, inline code, URLs, link destinations, HTML, front matter, `:::kiritan` lines and `%{name}` come back untouched (and a result that lost one is refused), a text over DeepL's size limit is split at paragraph boundaries and rejoined, and requests are retried on 429/5xx.
+ */
+declare function deepl(options: DeepLOptions): DeepLMiddleware;
+/**
+ * The same, but texts sharing a language pair go out together — up to DeepL's 50 texts / 128 KiB per request. Prefer this for a catalog with many segments.
+ */
+declare function deeplBatch(options: DeepLOptions): DeepLMiddleware;
+//#endregion
+export { DeepLMiddleware, DeepLOptions, decode, deepl, deeplBatch, encode, toDeepLSource, toDeepLTarget };

package/dist/index.d.mts

@@ -0,0 +1,45 @@
+import { TranslatorMiddleware, TranslatorOptions } from "@kiritan/middleware";
+//#region src/index.d.ts
+type DeepLMiddleware = TranslatorMiddleware;
+/** Tuning shared with every `@kiritan/middleware`-based provider. */
+type Tuning = Pick<TranslatorOptions, "concurrency" | "minInterval" | "cache" | "protect" | "onError" | "onSkip">;
+interface DeepLOptions extends Tuning {
+  /** 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<string, string>;
+  /** Extra fields merged into the request body, e.g. `{ formality: "prefer_less" }`. They can add fields but never override the ones this middleware depends on. */
+  extraParams?: Record<string, unknown>;
+  /** How many times to retry a failed request (network errors, 408/409/425/429/5xx) before giving up. Default: 2. */
+  retry?: number;
+  /** Delay before the first retry, in ms (doubled each time). Default: 500. */
+  retryDelay?: number;
+  /** Per-request timeout, in ms. Default: 30000. */
+  timeout?: number;
+  /** For testing or a custom transport. Default: the global `fetch`. */
+  fetch?: typeof fetch;
+}
+/**
+ * The DeepL `target_lang` for a Kiritan locale, parsed with `Intl.Locale` so any BCP 47 tag works (`ja`, `en-US`, `zh-Hant-TW`, `pt_BR`).
+ * DeepL has no bare `EN`/`PT` as a target, only a regional variant (British English if the locale says GB, else American; European Portuguese if PT, else Brazilian); Chinese is `ZH-HANS`/`ZH-HANT` by script; Norwegian is always `NB`; anything else is the upper-cased language. `overrides` (matched on the exact locale) win.
+ */
+declare function toDeepLTarget(locale: string, overrides?: Record<string, string>): string;
+/** DeepL's `source_lang` takes no regional variant or script: `en-GB` -> `EN`, `zh-Hant` -> `ZH`, `no` -> `NB`. */
+declare function toDeepLSource(locale: string): string;
+/** Escapes the text as XML and wraps every `[[N]]` token in the ignored tag. */
+declare function encode(text: string): string;
+/** The inverse of `encode`. */
+declare function decode(text: string): string;
+/**
+ * A `translate.middlewares` entry that translates through DeepL, one request per text.
+ * Built on `@kiritan/middleware`, so code blocks, inline code, URLs, link destinations, HTML, front matter, `:::kiritan` lines and `%{name}` come back untouched (and a result that lost one is refused), a text over DeepL's size limit is split at paragraph boundaries and rejoined, and requests are retried on 429/5xx.
+ */
+declare function deepl(options: DeepLOptions): DeepLMiddleware;
+/**
+ * The same, but texts sharing a language pair go out together — up to DeepL's 50 texts / 128 KiB per request. Prefer this for a catalog with many segments.
+ */
+declare function deeplBatch(options: DeepLOptions): DeepLMiddleware;
+//#endregion
+export { DeepLMiddleware, DeepLOptions, decode, deepl, deeplBatch, encode, toDeepLSource, toDeepLTarget };

package/dist/index.mjs

@@ -0,0 +1,132 @@
+import { chineseScript, createTranslator, parseLocale, parseRetryAfter } from "@kiritan/middleware";
+import { createHash } from "node:crypto";
+import { decode as decode$1, encode as encode$1 } from "html-entities";
+import { FetchError, createFetch } from "ofetch";
+//#region src/index.ts
+const FREE_URL = "https://api-free.deepl.com";
+const PRO_URL = "https://api.deepl.com";
+/** DeepL accepts at most 50 texts per request, in a body of at most 128 KiB. */
+const MAX_TEXTS_PER_REQUEST = 50;
+/** One text and one request's texts, in bytes of the JSON that is actually sent; headroom under 128 KiB for the other fields. */
+const MAX_TEXT_BYTES = 102400;
+const MAX_BATCH_BYTES = 122880;
+/**
+* The DeepL `target_lang` for a Kiritan locale, parsed with `Intl.Locale` so any BCP 47 tag works (`ja`, `en-US`, `zh-Hant-TW`, `pt_BR`).
+* DeepL has no bare `EN`/`PT` as a target, only a regional variant (British English if the locale says GB, else American; European Portuguese if PT, else Brazilian); Chinese is `ZH-HANS`/`ZH-HANT` by script; Norwegian is always `NB`; anything else is the upper-cased language. `overrides` (matched on the exact locale) win.
+*/
+function toDeepLTarget(locale, overrides = {}) {
+	if (Object.hasOwn(overrides, locale)) return overrides[locale];
+	const { language, region } = parseLocale(locale);
+	switch (language) {
+		case "en": return region === "GB" ? "EN-GB" : "EN-US";
+		case "pt": return region === "PT" ? "PT-PT" : "PT-BR";
+		case "zh": return chineseScript(locale) === "Hant" ? "ZH-HANT" : "ZH-HANS";
+		case "no":
+		case "nb":
+		case "nn": return "NB";
+		default: return language.toUpperCase();
+	}
+}
+/** DeepL's `source_lang` takes no regional variant or script: `en-GB` -> `EN`, `zh-Hant` -> `ZH`, `no` -> `NB`. */
+function toDeepLSource(locale) {
+	const { language } = parseLocale(locale);
+	return (language === "no" || language === "nn" ? "nb" : language).toUpperCase();
+}
+const KEEP_TAG = "x";
+/** Escapes the text as XML and wraps every `[[N]]` token in the ignored tag. */
+function encode(text) {
+	return encode$1(text, { mode: "specialChars" }).replace(/\[\[(\d+)\]\]/g, `<${KEEP_TAG}>[[$1]]</${KEEP_TAG}>`);
+}
+/** The inverse of `encode`. */
+function decode(text) {
+	return decode$1(text.replace(new RegExp(`</?${KEEP_TAG}>`, "gi"), ""), { level: "xml" });
+}
+/** A failure the layer's retry logic can read, and that says what DeepL said. */
+var DeepLError = class extends Error {
+	status;
+	retryAfter;
+	constructor(message, status, retryAfter, options) {
+		super(message, options);
+		this.status = status;
+		this.retryAfter = retryAfter;
+		this.name = "DeepLError";
+	}
+};
+function describeError(error) {
+	if (error instanceof FetchError && error.status !== void 0) {
+		const data = error.data;
+		const detail = typeof data === "string" ? data : data ? JSON.stringify(data) : "";
+		return new DeepLError(`@kiritan/deepl: DeepL responded ${error.status}${detail ? `: ${detail}` : ""}`, error.status, parseRetryAfter(error.response?.headers.get("retry-after")), { cause: error });
+	}
+	return new DeepLError(`@kiritan/deepl: request to DeepL failed: ${error instanceof Error ? error.message : String(error)}`, void 0, void 0, { cause: error });
+}
+async function requestTranslations(options, texts, from, to) {
+	const baseUrl = options.baseUrl ?? (options.apiKey.endsWith(":fx") ? FREE_URL : PRO_URL);
+	const request = createFetch({ fetch: options.fetch ?? globalThis.fetch });
+	let body;
+	try {
+		body = await request(`${baseUrl}/v2/translate`, {
+			method: "POST",
+			headers: { Authorization: `DeepL-Auth-Key ${options.apiKey}` },
+			retry: 0,
+			timeout: options.timeout ?? 3e4,
+			body: {
+				...options.extraParams,
+				text: texts,
+				source_lang: toDeepLSource(from),
+				target_lang: toDeepLTarget(to, options.targetLanguages),
+				tag_handling: "xml",
+				ignore_tags: [KEEP_TAG]
+			}
+		});
+	} catch (error) {
+		throw describeError(error);
+	}
+	if (body.translations?.length !== texts.length) throw new DeepLError(`@kiritan/deepl: expected ${texts.length} translation(s), got ${body.translations?.length ?? 0}`);
+	return body.translations.map((entry) => entry.text);
+}
+/** The size of a text as it will actually be sent: XML-wrapped and JSON-encoded, in UTF-8 bytes. */
+const wireBytes = (text) => Buffer.byteLength(JSON.stringify(encode(text)), "utf8");
+function create(options, batched) {
+	const common = {
+		name: `deepl:${createHash("sha1").update(JSON.stringify([options.extraParams ?? {}, options.targetLanguages ?? {}])).digest("hex").slice(0, 12)}`,
+		wire: {
+			encode,
+			decode
+		},
+		measure: wireBytes,
+		maxChars: MAX_TEXT_BYTES,
+		maxBatchChars: MAX_BATCH_BYTES,
+		maxBatchSize: batched ? MAX_TEXTS_PER_REQUEST : 1,
+		retry: {
+			retries: options.retry ?? 2,
+			delay: options.retryDelay ?? 500
+		},
+		concurrency: options.concurrency,
+		minInterval: options.minInterval,
+		cache: options.cache,
+		protect: options.protect,
+		onError: options.onError,
+		onSkip: options.onSkip,
+		async translateBatch(texts, { from, to }) {
+			return requestTranslations(options, texts, from, to);
+		}
+	};
+	for (const key of Object.keys(common)) if (common[key] === void 0) delete common[key];
+	return createTranslator(common);
+}
+/**
+* A `translate.middlewares` entry that translates through DeepL, one request per text.
+* Built on `@kiritan/middleware`, so code blocks, inline code, URLs, link destinations, HTML, front matter, `:::kiritan` lines and `%{name}` come back untouched (and a result that lost one is refused), a text over DeepL's size limit is split at paragraph boundaries and rejoined, and requests are retried on 429/5xx.
+*/
+function deepl(options) {
+	return create(options, false);
+}
+/**
+* The same, but texts sharing a language pair go out together — up to DeepL's 50 texts / 128 KiB per request. Prefer this for a catalog with many segments.
+*/
+function deeplBatch(options) {
+	return create(options, true);
+}
+//#endregion
+export { decode, deepl, deeplBatch, encode, toDeepLSource, toDeepLTarget };

package/package.json

@@ -1,19 +1,55 @@
 {
   "name": "@kiritan/deepl",
-  "version": "0.0.0-reserved",
-  "main": "index.js",
-  "scripts": {
-    "help": "node scripts/main.js --help",
-    "reserve": "node scripts/main.js"
+  "version": "0.1.1",
+  "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": [
-    "index.js"
+    "dist",
+    "README.ja.md"
   ],
-  "keywords": [],
-  "author": "otoneko.",
-  "description": "[Reserved]",
-  "devDependencies": {
-    "consola": "^3.4.2",
-    "dotenv": "^17.3.1"
+  "engines": {
+    "node": ">=22.7.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@kiritan/middleware": "^0.1.0",
+    "html-entities": "^2.6.0",
+    "ofetch": "^1.5.1"
   }
-}
+}

package/index.js

@@ -1 +0,0 @@
-module.exports = console.log("@kiritan/deepl is reserved for otoneko.");