@cutticat/libretranslate 1.0.3

package/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Maksim Victorovich Fomin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,81 @@
+# @cutticat/libretranslate
+
+Library for working with the LibreTranslate API.
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [API](#api)
+- [Documentation](#documentation)
+- [Requirements](#requirements)
+
+## Overview
+
+The library provides the `translate` function for translating text via the LibreTranslate API. Supports language auto-detection, alternative translations, custom baseUrl and API key. Uses Zod for response validation and types from `@cutticat/types`.
+
+## Installation
+
+```bash
+pnpm i @cutticat/libretranslate
+```
+
+## Quick Start
+
+```typescript
+import { translate } from "@cutticat/libretranslate"
+
+const result = await translate({
+  text: "Hello, world!",
+  source: "en",
+  target: "ru",
+})
+console.log(result.translatedText) // "Привет, мир!"
+```
+
+With language auto-detection:
+
+```typescript
+const result = await translate({
+  text: "Bonjour",
+  source: "auto",
+  target: "en",
+})
+console.log(result.translatedText) // "Hello"
+console.log(result.detectedLanguage) // { code: "fr", confidence: 0.95 }
+```
+
+## API
+
+### Functions
+
+- `translate(options)` — translates text via the LibreTranslate API; returns `Promise<TranslateResponse>`; throws `Error` on request failure
+
+### Types
+
+- `TranslationOptions` — translation parameters (`text`, `source`, `target`, `format?`, `alternatives?`, `baseUrl?`, `apiKey?`, `fetch?`)
+- `TranslationFormat` — `"text"` | `"html"`
+- `TranslateResponse` — response (`translatedText`, `detectedLanguage?`, `alternatives?`)
+- `DetectedLanguage` — detected language info (`code`, `confidence`)
+
+### Constants
+
+- `defaultBaseUrl` — default URL (`https://libretranslate.com`)
+
+## Documentation
+
+Detailed documentation:
+
+- [Project structure](documents/STRUCTURE.md)
+- [Scripts](documents/SCRIPTS.md)
+- [Style guide](documents/STYLE_GUIDE.md)
+- [Contributing](documents/CONTRIBUTING.md)
+
+Full API documentation is available in JSDoc comments. Use IDE autocomplete to browse it.
+
+## Requirements
+
+- Node.js >= 22.0.0
+- pnpm >= 10.17.0
+- TypeScript >= 5.9.0

package/dist/index.d.ts

@@ -0,0 +1,133 @@
+import { z } from "zod";
+import { DeepReadonly, FullyUndefinable } from "@cutticat/types";
+
+//#region lib/schemas/DetectedLanguage.d.ts
+/** Detected language info schema. */
+declare const DetectedLanguageSchema: z.ZodObject<{
+  code: z.ZodString;
+  confidence: z.ZodNumber;
+}, z.core.$strip>;
+/** Detected language info (when using auto-detection). */
+type DetectedLanguage = z.infer<typeof DetectedLanguageSchema>;
+//#endregion
+//#region lib/schemas/TranslateResponse.d.ts
+/** Translation response schema. */
+declare const TranslateResponseSchema: z.ZodObject<{
+  translatedText: z.ZodString;
+  detectedLanguage: z.ZodOptional<z.ZodObject<{
+    code: z.ZodString;
+    confidence: z.ZodNumber;
+  }, z.core.$strip>>;
+  alternatives: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+/** Translation response from the LibreTranslate API. */
+type TranslateResponse = z.infer<typeof TranslateResponseSchema>;
+//#endregion
+//#region lib/types/TranslationFormat.d.ts
+/** Text format: "text" or "html" for markup. */
+type TranslationFormat = "text" | "html";
+//#endregion
+//#region lib/types/TranslationOptions.d.ts
+/** Translation request parameters. */
+type TranslationOptions = {
+  /** Text to translate. */
+  text: string;
+  /** Source language code (e.g. "en", "ru") or "auto" for auto-detection. */
+  source: string;
+  /** Target language code (e.g. "en", "ru"). */
+  target: string;
+} & FullyUndefinable<{
+  /** Text format: "text" (default) or "html" for markup. */
+  format: TranslationFormat;
+  /** Number of alternative translations. */
+  alternatives: number;
+  /** Base URL of the LibreTranslate API instance. */
+  baseUrl: string;
+  /** API key (required for libretranslate.com; optional for self-hosted). */
+  apiKey: string;
+  /** fetch function for HTTP requests (defaults to globalThis.fetch; pass a mock for tests). */
+  fetch: typeof globalThis.fetch;
+}>;
+//#endregion
+//#region lib/constants.d.ts
+/** Default URL for the LibreTranslate API. */
+declare const defaultBaseUrl = "https://libretranslate.com";
+//#endregion
+//#region lib/functions.d.ts
+/**
+ * Translates text via the LibreTranslate API.
+ *
+ * @param options — translation parameters
+ * @returns Promise with translation response
+ * @throws {Error} On request failure (HTTP status included in message)
+ *
+ * @example
+ * ```typescript
+ * const result = await translate({
+ *   text: "Hello, world!",
+ *   source: "en",
+ *   target: "ru"
+ * })
+ * console.log(result.translatedText) // "Привет, мир!"
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With language auto-detection
+ * const result = await translate({
+ *   text: "Bonjour",
+ *   source: "auto",
+ *   target: "en"
+ * })
+ * console.log(result.translatedText) // "Hello"
+ * console.log(result.detectedLanguage) // { code: "fr", confidence: 0.95 }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With custom API and key
+ * const result = await translate({
+ *   text: "Hello",
+ *   source: "en",
+ *   target: "es",
+ *   baseUrl: "https://translate.example.com",
+ *   apiKey: "your-api-key"
+ * })
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With custom fetch (e.g. for tests or proxy)
+ * const result = await translate({
+ *   text: "Hello",
+ *   source: "en",
+ *   target: "ru",
+ *   fetch: myCustomFetch
+ * })
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With alternative translations
+ * const result = await translate({
+ *   text: "Hello",
+ *   source: "en",
+ *   target: "ru",
+ *   alternatives: 2
+ * })
+ * console.log(result.alternatives) // ["Здравствуй", "Приветствую"]
+ * ```
+ */
+declare function translate({
+  text,
+  source,
+  target,
+  format,
+  alternatives,
+  apiKey,
+  baseUrl,
+  fetch
+}: DeepReadonly<TranslationOptions>): Promise<TranslateResponse>;
+//#endregion
+export { DetectedLanguage, DetectedLanguageSchema, TranslateResponse, TranslateResponseSchema, TranslationFormat, TranslationOptions, defaultBaseUrl, translate };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../lib/schemas/DetectedLanguage.ts","../lib/schemas/TranslateResponse.ts","../lib/types/TranslationFormat.ts","../lib/types/TranslationOptions.ts","../lib/constants.ts","../lib/functions.ts"],"sourcesContent":[],"mappings":";;;;;cAGa,wBAAsB,CAAA,CAAA;;EAAtB,UAAA,aAAA;;;KAMD,gBAAA,GAAmB,CAAA,CAAE,aAAa;;;;cCLjC,yBAAuB,CAAA,CAAA;;EDDvB,gBAAA,eAGX,YAAA,CAAA;;;;EAHiC,YAAA,eAAA,WAAA,YAAA,CAAA,CAAA;CAAA,eAAA,CAAA;AAMnC;KCEY,iBAAA,GAAoB,CAAA,CAAE,aAAa;;;;KCVnC,iBAAA;;;;KCGA,kBAAA;EHDC;;;;EAAsB;EAAA,MAAA,EAAA,MAAA;AAMnC,CAAA,GGEI,gBHFQ,CAAA;;UGIF;;EFTG,YAAA,EAAA,MAAA;;;;;;gBEiBG,UAAA,CAAW;;;;;cCpBd,cAAA;;;;AJEb;;;;;;AAMA;;;;ACLA;;;;;;;;;;;;;AAOA;;;;ACVA;;;;ACGA;;;;;;;;ACHA;;;;ACoEA;;;;;;;;;;;;;;;;;;;;iBAAsB,SAAA;;;;;;;;;GASnB,aAAa,sBAAsB,QAAQ"}

package/dist/index.js

@@ -0,0 +1,113 @@
+import { z } from "zod";
+
+//#region lib/schemas/DetectedLanguage.ts
+/** Detected language info schema. */
+const DetectedLanguageSchema = z.object({
+	code: z.string(),
+	confidence: z.number()
+});
+
+//#endregion
+//#region lib/schemas/TranslateResponse.ts
+/** Translation response schema. */
+const TranslateResponseSchema = z.object({
+	translatedText: z.string(),
+	detectedLanguage: DetectedLanguageSchema.optional(),
+	alternatives: z.array(z.string()).optional()
+});
+
+//#endregion
+//#region lib/constants.ts
+/** Default URL for the LibreTranslate API. */
+const defaultBaseUrl = "https://libretranslate.com";
+
+//#endregion
+//#region lib/functions.ts
+/**
+* Translates text via the LibreTranslate API.
+*
+* @param options — translation parameters
+* @returns Promise with translation response
+* @throws {Error} On request failure (HTTP status included in message)
+*
+* @example
+* ```typescript
+* const result = await translate({
+*   text: "Hello, world!",
+*   source: "en",
+*   target: "ru"
+* })
+* console.log(result.translatedText) // "Привет, мир!"
+* ```
+*
+* @example
+* ```typescript
+* // With language auto-detection
+* const result = await translate({
+*   text: "Bonjour",
+*   source: "auto",
+*   target: "en"
+* })
+* console.log(result.translatedText) // "Hello"
+* console.log(result.detectedLanguage) // { code: "fr", confidence: 0.95 }
+* ```
+*
+* @example
+* ```typescript
+* // With custom API and key
+* const result = await translate({
+*   text: "Hello",
+*   source: "en",
+*   target: "es",
+*   baseUrl: "https://translate.example.com",
+*   apiKey: "your-api-key"
+* })
+* ```
+*
+* @example
+* ```typescript
+* // With custom fetch (e.g. for tests or proxy)
+* const result = await translate({
+*   text: "Hello",
+*   source: "en",
+*   target: "ru",
+*   fetch: myCustomFetch
+* })
+* ```
+*
+* @example
+* ```typescript
+* // With alternative translations
+* const result = await translate({
+*   text: "Hello",
+*   source: "en",
+*   target: "ru",
+*   alternatives: 2
+* })
+* console.log(result.alternatives) // ["Здравствуй", "Приветствую"]
+* ```
+*/
+async function translate({ text, source, target, format = "text", alternatives = 0, apiKey, baseUrl = defaultBaseUrl, fetch = globalThis.fetch }) {
+	if (alternatives < 0) throw new Error("Number of alternatives must be zero or positive");
+	if (!Number.isInteger(alternatives)) throw new Error("Number of alternatives must be an integer");
+	const body = {
+		q: text,
+		source,
+		target
+	};
+	if (format != null) body.format = format;
+	if (alternatives > 0) body.alternatives = alternatives;
+	if (apiKey != null) body.api_key = apiKey;
+	const response = await fetch(new URL("/translate", baseUrl), {
+		method: "POST",
+		headers: { "Content-Type": "application/json" },
+		body: JSON.stringify(body)
+	});
+	if (!response.ok) throw new Error(`Failed to translate text: ${response.status} ${response.statusText}`);
+	const json = await response.json();
+	return TranslateResponseSchema.parse(json);
+}
+
+//#endregion
+export { DetectedLanguageSchema, TranslateResponseSchema, defaultBaseUrl, translate };
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../lib/schemas/DetectedLanguage.ts","../lib/schemas/TranslateResponse.ts","../lib/constants.ts","../lib/functions.ts"],"sourcesContent":["import { z } from \"zod\"\n\n/** Detected language info schema. */\nexport const DetectedLanguageSchema = z.object({\n  code: z.string(),\n  confidence: z.number(),\n})\n\n/** Detected language info (when using auto-detection). */\nexport type DetectedLanguage = z.infer<typeof DetectedLanguageSchema>\n","import { z } from \"zod\"\nimport { DetectedLanguageSchema } from \"./DetectedLanguage.js\"\n\n/** Translation response schema. */\nexport const TranslateResponseSchema = z.object({\n  translatedText: z.string(),\n  detectedLanguage: DetectedLanguageSchema.optional(),\n  alternatives: z.array(z.string()).optional(),\n})\n\n/** Translation response from the LibreTranslate API. */\nexport type TranslateResponse = z.infer<typeof TranslateResponseSchema>\n","/** Default URL for the LibreTranslate API. */\nexport const defaultBaseUrl = \"https://libretranslate.com\"\n","import type { DeepReadonly } from \"@cutticat/types\"\nimport type { TranslationOptions } from \"./types/TranslationOptions.js\"\nimport { TranslateResponseSchema, type TranslateResponse } from \"./schemas/TranslateResponse.js\"\nimport { defaultBaseUrl } from \"./constants.js\"\n\n/**\n * Translates text via the LibreTranslate API.\n *\n * @param options — translation parameters\n * @returns Promise with translation response\n * @throws {Error} On request failure (HTTP status included in message)\n *\n * @example\n * ```typescript\n * const result = await translate({\n *   text: \"Hello, world!\",\n *   source: \"en\",\n *   target: \"ru\"\n * })\n * console.log(result.translatedText) // \"Привет, мир!\"\n * ```\n *\n * @example\n * ```typescript\n * // With language auto-detection\n * const result = await translate({\n *   text: \"Bonjour\",\n *   source: \"auto\",\n *   target: \"en\"\n * })\n * console.log(result.translatedText) // \"Hello\"\n * console.log(result.detectedLanguage) // { code: \"fr\", confidence: 0.95 }\n * ```\n *\n * @example\n * ```typescript\n * // With custom API and key\n * const result = await translate({\n *   text: \"Hello\",\n *   source: \"en\",\n *   target: \"es\",\n *   baseUrl: \"https://translate.example.com\",\n *   apiKey: \"your-api-key\"\n * })\n * ```\n *\n * @example\n * ```typescript\n * // With custom fetch (e.g. for tests or proxy)\n * const result = await translate({\n *   text: \"Hello\",\n *   source: \"en\",\n *   target: \"ru\",\n *   fetch: myCustomFetch\n * })\n * ```\n *\n * @example\n * ```typescript\n * // With alternative translations\n * const result = await translate({\n *   text: \"Hello\",\n *   source: \"en\",\n *   target: \"ru\",\n *   alternatives: 2\n * })\n * console.log(result.alternatives) // [\"Здравствуй\", \"Приветствую\"]\n * ```\n */\nexport async function translate({\n  text,\n  source,\n  target,\n  format = \"text\",\n  alternatives = 0,\n  apiKey,\n  baseUrl = defaultBaseUrl,\n  fetch = globalThis.fetch,\n}: DeepReadonly<TranslationOptions>): Promise<TranslateResponse> {\n  // Validation\n\n  if (alternatives < 0) throw new Error(\"Number of alternatives must be zero or positive\")\n  if (!Number.isInteger(alternatives)) throw new Error(\"Number of alternatives must be an integer\")\n\n  // Body creation\n\n  const body: Record<string, unknown> = {\n    q: text,\n    source: source,\n    target: target,\n  }\n\n  if (format != null) body.format = format\n  if (alternatives > 0) body.alternatives = alternatives\n  if (apiKey != null) body.api_key = apiKey\n\n  // Request sending\n\n  const url = new URL(\"/translate\", baseUrl)\n  const response = await fetch(url, {\n    method: \"POST\",\n    headers: { \"Content-Type\": \"application/json\" },\n    body: JSON.stringify(body),\n  })\n\n  // Response processing\n\n  if (!response.ok)\n    throw new Error(`Failed to translate text: ${response.status} ${response.statusText}`)\n\n  const json = await response.json()\n  const data = TranslateResponseSchema.parse(json)\n\n  return data\n}\n"],"mappings":";;;;AAGA,MAAa,yBAAyB,EAAE,OAAO;CAC7C,MAAM,EAAE,QAAQ;CAChB,YAAY,EAAE,QAAQ;CACvB,CAAC;;;;;ACFF,MAAa,0BAA0B,EAAE,OAAO;CAC9C,gBAAgB,EAAE,QAAQ;CAC1B,kBAAkB,uBAAuB,UAAU;CACnD,cAAc,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC,UAAU;CAC7C,CAAC;;;;;ACPF,MAAa,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;ACoE9B,eAAsB,UAAU,EAC9B,MACA,QACA,QACA,SAAS,QACT,eAAe,GACf,QACA,UAAU,gBACV,QAAQ,WAAW,SAC4C;AAG/D,KAAI,eAAe,EAAG,OAAM,IAAI,MAAM,kDAAkD;AACxF,KAAI,CAAC,OAAO,UAAU,aAAa,CAAE,OAAM,IAAI,MAAM,4CAA4C;CAIjG,MAAM,OAAgC;EACpC,GAAG;EACK;EACA;EACT;AAED,KAAI,UAAU,KAAM,MAAK,SAAS;AAClC,KAAI,eAAe,EAAG,MAAK,eAAe;AAC1C,KAAI,UAAU,KAAM,MAAK,UAAU;CAKnC,MAAM,WAAW,MAAM,MADX,IAAI,IAAI,cAAc,QAAQ,EACR;EAChC,QAAQ;EACR,SAAS,EAAE,gBAAgB,oBAAoB;EAC/C,MAAM,KAAK,UAAU,KAAK;EAC3B,CAAC;AAIF,KAAI,CAAC,SAAS,GACZ,OAAM,IAAI,MAAM,6BAA6B,SAAS,OAAO,GAAG,SAAS,aAAa;CAExF,MAAM,OAAO,MAAM,SAAS,MAAM;AAGlC,QAFa,wBAAwB,MAAM,KAAK"}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@cutticat/libretranslate",
+  "publishConfig": {
+    "access": "public"
+  },
+  "version": "1.0.3",
+  "description": "CuttiCat library for working with LibreTranslate",
+  "author": "Maksim Victorovich Fomin",
+  "repository": {
+    "type": "git",
+    "url": "https://gitflic.ru/project/cutticat-npm/libretranslate"
+  },
+  "homepage": "https://cutticat.com",
+  "keywords": [
+    "libretranslate",
+    "translation",
+    "i18n",
+    "localization",
+    "api-client",
+    "cutticat"
+  ],
+  "type": "module",
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "dependencies": {
+    "@cutticat/types": "^1.7.2",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.16",
+    "@types/node": "^25.9.1",
+    "rimraf": "^6.1.3",
+    "tsdown": "0.19.0-beta.2",
+    "tsx": "^4.22.4",
+    "typescript": "^5.9.3"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist/**/*"
+  ],
+  "license": "MIT",
+  "scripts": {
+    "lint": "biome check .",
+    "lint:fix": "biome check --write .",
+    "lint:fix:unsafe": "biome check --write --unsafe .",
+    "format": "biome format --write .",
+    "format:check": "biome format .",
+    "clean": "rimraf ./dist",
+    "build": "tsc --noEmit -p ./tsconfig.build.json && tsdown",
+    "test": "tsx --test \"./tests/**/*.test.ts\"",
+    "test:watch": "tsx --test --watch \"./tests/**/*.test.ts\"",
+    "test:coverage": "tsx --test --experimental-test-coverage \"./tests/**/*.test.ts\""
+  }
+}