Skip to content

README.md

Latest commit

 

History

History
224 lines (166 loc) · 7.4 KB

README.md

File metadata and controls

224 lines (166 loc) · 7.4 KB
Raw

Polyglotus

CLI tool for automatic AI-powered translation of JSON and Markdown files.

Point it at your source files, list target languages, and it handles the rest — chunking large JSON, merging missing keys into existing translations, and creating markdown translations.

Installation

The package is published on npm: polyglotus.

You can skip installation and run it directly with npx:

npx polyglotus init

Quick start

npx polyglotus init
npx polyglotus translate

Environment variables

Variable Description
OPENAI_API_KEY OpenAI API key (for openai provider)

API keys can also be set in the config file via provider.apiKey, but env vars take priority.

Dotenv support: Polyglotus automatically loads variables from a .env file in your project root, so you don't need to pass them inline:

# .env
OPENAI_API_KEY=your_key

Configuration

Create an polyglotus.config.mjs in your project root (or run npx polyglotus init):

export default {
  sourceLang: "en",
  targetLangs: ["de", "fr", "es", "ru"],

  provider: {
    model: "openai/gpt-5.6-luna",
  },

  files: [
    {
      pattern: "messages/en.json",
      type: "json",
    },
    {
      pattern: "docs/readme.md",
      type: "markdown",
    },
  ],

  prompts: {
    json: "Custom context prompt for JSON translation…",
    markdown: "Custom context prompt for Markdown translation…",
  },
};

Provider configuration

The provider block talks to any endpoint implementing the OpenAI-compatible Chat Completions API — OpenAI, Ollama, LM Studio, OpenRouter, self-hosted, etc. By default it targets the official OpenAI API; set baseUrl to point anywhere else.

provider: {
  model: "model-id",
  baseUrl: "optional-custom-url", // defaults to https://api.openai.com/v1
  apiKey: "optional-key-here",
  apiKeyEnv: "OPENAI_API_KEY", // optional: env var name to read the key from
}
Field Default Description
model — Model identifier
baseUrl https://api.openai.com/v1 API endpoint base URL
apiKey — API key (env var is preferred, this is a fallback)
apiKeyEnv OPENAI_API_KEY Name of the env var to read the API key from

A missing API key only raises an error when baseUrl is the default OpenAI endpoint. For any other endpoint (local Ollama, self-hosted servers, etc.) a missing key is assumed to be intentional — set apiKeyEnv or apiKey if your endpoint requires one.

OpenAI (default)

"provider": {
  "model": "openai/gpt-5.6-luna"
}

Env var: OPENAI_API_KEY.

Ollama (local)

Use a local Ollama instance — free, no API key needed.

"provider": {
  "model": "llama3.1",
  "baseUrl": "http://localhost:11434/v1"
}

Local servers often handle only a few requests at a time (see OLLAMA_NUM_PARALLEL) and queue the rest. If requests start timing out, lower concurrency.

Any other OpenAI-compatible endpoint

"provider": {
  "model": "model-id",
  "baseUrl": "https://your-endpoint/v1",
  "apiKey": "optional-key-here",
  "apiKeyEnv": "MY_CUSTOM_API_KEY"
}

Other config fields

Field Required Description
sourceLang yes Source language code (e.g. "en")
targetLangs yes Array of target language codes
requestDelay no Minimum delay between starting AI requests, in milliseconds, also when they run in parallel (default: 1000)
concurrency no Max number of AI requests running in parallel (default: 4)
files yes Array of file entries to translate
files[].pattern yes Glob pattern for source files (resolved relative to config)
files[].type yes "json" or "markdown"
files[].prompt no Override the default prompt for this specific file pattern
prompts.json no Default context prompt prepended to all JSON translation requests
prompts.markdown no Default context prompt prepended to all Markdown translation requests

Parallel translation and progress

Polyglotus runs several AI requests at the same time: files, target languages, and the chunks of a large JSON file are all translated in parallel. concurrency caps how many requests are in flight at once, and requestDelay still spaces out when new ones start.

In an interactive terminal you get a live view of every request in flight, plus a progress bar with an estimate of the time left. In CI or when the output is piped, a line is printed as each file (and each chunk of a large JSON file) finishes.

If some chunks of a JSON file fail, the ones that succeeded are still saved, so running the command again only retries the missing keys. If your provider responds with 429 Too Many Requests, lower concurrency or raise requestDelay.

How file naming works

JSON files: The source language code in the filename is replaced with the target code.

  • messages/en.json → messages/de.json, messages/fr.json, …

Markdown files: The target language code is appended before the extension.

  • docs/readme.md → docs/readme-de.md, docs/readme-fr.md, …

CLI usage

polyglotus translate [options]
polyglotus init

translate options

Flag Description
-c, --config <path> Path to config file (default: auto-detect)
-l, --lang <codes> Override target languages (comma-separated)
-m, --model <model> Override model identifier
--base-url <url> Override API base URL
--api-key-env <name> Override the env var name to read the API key from
--chunk-size <n> Max JSON keys per AI request (default: 100)
--request-delay <ms> Minimum delay between starting AI requests, in milliseconds (overrides config, default: 1000)
-j, --concurrency <n> Max number of AI requests running in parallel (overrides config, default: 4)
-d, --dry-run Preview what would be translated
-v, --verbose Detailed progress output

Examples

# Translate everything using OpenAI (default config)
OPENAI_API_KEY=sk-xxx npx polyglotus translate

# Only translate to Russian and German
npx polyglotus translate --lang ru,de

# Use a specific OpenAI model
OPENAI_API_KEY=sk-xxx npx polyglotus translate --model openai/gpt-5.6-luna

# Use local Ollama
npx polyglotus translate --model llama3.1 --base-url http://localhost:11434/v1

# Dry run — see what's missing without writing anything
npx polyglotus translate --dry-run

# Smaller chunks for large files
npx polyglotus translate --chunk-size 50 --verbose

# Wait 2 seconds between AI requests (e.g. to stay under a rate limit)
npx polyglotus translate --request-delay 2000

# Run up to 8 AI requests in parallel
npx polyglotus translate --concurrency 8

Features

  • OpenAI-compatible - works with OpenAI, local Ollama, or any other endpoint implementing the Chat Completions API
  • Incremental - only translates missing keys/files; existing translations are preserved
  • Chunked - large JSON files are split into manageable pieces for reliable AI output
  • Parallel - several files, languages, and chunks are translated at once, with a live progress display
  • Glob patterns - match multiple source files with a single pattern
  • Per-file prompts - give the AI specific context for different parts of your project
  • Config-driven - model, endpoint, and API key all configurable in one file

License

MIT