# polyglots for AI agents Instructions for an AI agent asked to review or translate WordPress `.po` files with polyglots. A person can follow them too. The same text is served as plain text at https://ada.tools/polyglots/ai.txt, followed by the full command reference. polyglots is a command-line tool for the people who look after a WordPress locale on translate.wordpress.org. `review` checks a contributor's submitted strings and writes out only the entries that need work, already repaired. `translate` fills in untranslated strings with a machine draft that an AI agent then reviews. Results are `.po` files for a person to read in their own `.po` editor. polyglots never uploads anything to translate.wordpress.org. It does send text off the machine: a review sends each batch of strings to the agent's model provider, a translation sends source strings to DeepL or OpenAI, and lookups query translate.wordpress.org. ## Give this to your agent > Fetch https://ada.tools/polyglots/ai and use polyglots to review this .po > file. Run the rules-only pass first and report what it found. Ask me before > running the AI review. ## Start here Work in this order. Steps 1 to 5 spend nothing; step 6 is the first that does. 1. **Check the install.** `polyglots --version`. It needs Node.js 24 or later. If it is missing, `npm install -g polyglots`. 2. **Check the reviewer.** `polyglots doctor` reports whether the agent that reviews (claude or antigravity) is installed, signed in and set up. It sends no prompt. Add `--json` to parse it. 3. **Know the locale.** `polyglots config get defaultLocale` prints it, or an empty line when none is set. polyglots has no default. If none is set, or the file is for another locale, pass `--locale` on every command rather than changing the setting. Ask the person which locale when the file name or its `Language` header does not make it plain. 4. **Make sure the glossary is there.** A review refuses to run without it. `polyglots glossary sync --locale ` downloads it; it is free. 5. **Run the rules first.** `polyglots review --no-ai` runs only the deterministic checks. It costs nothing and sends nothing to a model. Report the counts it prints. 6. **Ask, then run the full review.** `polyglots review `. Tell the person how many entries will be reviewed before you start (the rules pass printed it). Entries go 25 to a batch, about half a minute each. For a translation there is no free first pass. Check the install and the reviewer, then ask before running `polyglots translate `. `--dry-run` is not a preview: it skips only writing the file, and still sends every batch to DeepL or OpenAI and to the agent, at the full cost of a real run. Ask before a dry run exactly as before a real one. A dry run caches both the drafts and the review verdicts, so a real run right after it, with the same draft engine, review model and settings, does not pay for them again; changing any of those, or passing `--fresh`, pays again. ## Ask the person before - **Any run that uses a model**: `review` without `--no-ai`, `translate` (with or without `--dry-run`), `fetch`. They spend the person's agent quota, and `translate` also spends DeepL or OpenAI credit. A large file is hours of it. - **`translate` on a file with fuzzy entries.** Fuzzy entries are overwritten unconditionally. If a person marked one fuzzy on purpose, it is lost. - **`translate --all`**, which re-translates entries that are already done. - **`--fresh`**, which throws away cached work and pays for it again. - **`doctor --live`**, which sends a real prompt. - **Changing settings or keys** (`config set`, `config set-key`), importing into the translation memory (`tm import`, which cannot be undone), or editing locale rules (which makes every file of that locale review again). ## Never - Upload, approve or reject anything on translate.wordpress.org. polyglots does not, and the person decides what goes back. - Open, edit or delete the files under `~/.local/share/polyglots/`. `polyglots.db` is the translation memory, built over months, and cannot be rebuilt. To experiment, set `POLYGLOTS_HOME` to an empty folder. - Run `polyglots` with no arguments. That starts the interactive menu, which needs a terminal. - Run antigravity with `--dangerously-skip-permissions` or add shell permissions to it. Review input is untrusted text from contributors. ## Running unattended - Output is plain when it is not a terminal. Set `NO_COLOR=1` to be sure, and `POLYGLOTS_ASCII=1` for ASCII symbols and box lines. - The `p`, `r` and `q` keys work only on a terminal. In a pipe a run goes to the end; interrupting it keeps every batch already finished. - `translate --all` needs `--yes` when standard input is not a terminal. - A stopped run resumes: run the same command again and only unfinished entries are sent. | Exit code | Meaning | What to do | |---|---|---| | `0` | Success | Report the summary. | | `1` | Error or aborted | Report the error line; do not retry blindly. | | `2` | Usage error | Fix the command; see the reference below. | | `3` | Stopped on a quota or rate limit | Tell the person. Run the same command later to carry on. | ## Reading the results `review` prints a summary box and writes `-repaired.po` (or `-problems.po` with `--no-ai`) beside the input. Only flagged entries are in it, each with a note. Everything else in the submission is approvable. - **flagged** entries needed work; **repaired** ones carry a fix, and the rest are left for the person. - **unreviewed** entries were in a batch that failed. They are flagged, never approvable. - The **message for the requester** is meant to be posted to the contributor as written. It contains an HTML link; pass it on unchanged. - A **reply** follows it when the locale has a reply template: the whole comment for the contributor, headed with the template's name. Pass it on unchanged too. If the person told you the requester's WordPress.org username, pass `--requester ` to `review`; otherwise leave the `{username}` in the reply for the person to fill. A line above the reply saying entries are flagged means the verdict needs the person's check before it is posted: say so. `translate` writes into the file it was given. Its summary counts the entries taken from translation memory, drafted, and marked fuzzy for a person to check. ## Report back When you are done, tell the person: - which commands ran, and whether the rules-only pass ran first; - the summary counts, and the path of every file written; - the requester message, if there was one, and the reply, if there was one; - anything that stopped the run early, with the exit code; - that nothing was uploaded to translate.wordpress.org, and that no setting, key, memory, rules file or reply template was changed (or exactly what was, if they asked for it). ## More - [Getting started](https://ada.tools/polyglots/docs/getting-started/) - [Reviewing submissions](https://ada.tools/polyglots/docs/review/) - [Translating](https://ada.tools/polyglots/docs/translate/) - [Configuration](https://ada.tools/polyglots/docs/configuration/) - [Command reference](https://ada.tools/polyglots/docs/commands/) ## Command reference Generated from polyglots 0.28.0 --help. ### polyglots ``` Usage: polyglots [options] [command] Translate WordPress .po files with machine drafts and AI review. Run without arguments for the interactive menu. Options: -V, --version output the version number -h, --help display help for command Commands: translate [options] Translate pending (empty or fuzzy) entries of one or more .po files rules Locale-specific rules: built-in switches, common mistakes, patterns, guidance template Reply templates: the whole comment posted back on a PTE request tm Translation memory fetch [options] [names...] Fetch themes and plugins from translate.wordpress.org and review or translate every one review [options] Audit a submitted .po and write out only the entries that need work doctor [options] Check which agent CLIs are installed, signed in and set up, without sending a prompt models [options] List local model servers (Ollama, LM Studio, llama.cpp, vLLM) and the models they hold, without loading any split [options] Cut a .po into numbered parts so each can be run and submitted on its own glossary translate.wordpress.org glossary cache stats [options] Open review statistics in the browser, or write them to a self-contained HTML page usage-stats Opt-in anonymous usage totals: see what is sent, or forget the install id config Settings and API keys help [command] display help for command Exit codes: 0 success, 1 error or aborted, 2 usage error, 3 run stopped early (API quota or rate limit). ``` ### polyglots translate ``` Usage: polyglots translate [options] Translate pending (empty or fuzzy) entries of one or more .po files Options: --all Re-translate every entry, including already-translated ones (asks for confirmation) --fresh Ignore the cached drafts and reviews, and translate again --dry-run Run the pipeline without writing to the .po files --draft-engine Draft engine: deepl, openai, local, or none to fill from the translation memory only (default: deepl) --local-model Model for the local draft engine on this run, instead of the configured one --locale Target locale (default: defaultLocale, else the file's Language header) --batch-size Entries per draft/review batch (default: 25) --model Model for the review pass (the agent's, or the local reviewer's) --yes Skip the --all confirmation prompt (required with --all when stdin is not a terminal) -h, --help display help for command Environment: POLYGLOTS_AGENT_BIN agent executable for the review pass, whichever provider is set (default: claude or agy on PATH) POLYGLOTS_CLAUDE_BIN the older name, applied to claude only POLYGLOTS_HOME root for config/ and data/ instead of the XDG directories POLYGLOTS_ASCII=1 plain ASCII glyphs instead of Unicode (also NO_COLOR, FORCE_COLOR) DO_NOT_TRACK=1 never send usage statistics, whatever usageStats says POLYGLOTS_USAGE_URL where opted-in usage statistics go (default: https://ada.tools/polyglots/api/usage) NO_UPDATE_NOTIFIER=1 never check npm for a newer version (also CI, or: config set updateCheck off) ``` ### polyglots rules ``` Usage: polyglots rules [options] [command] Locale-specific rules: built-in switches, common mistakes, patterns, guidance Options: -h, --help display help for command Commands: edit [locale] Open the locale rules file in $VISUAL or $EDITOR, creating it with the defaults if needed check [locale] Validate the locale rules file and summarise what it sets copy [options] Duplicate one locale's rules file as another's, e.g. nl_NL to nl_BE path [locale] Print where the locale rules file lives help [command] display help for command ``` ### polyglots rules edit ``` Usage: polyglots rules edit [options] [locale] Open the locale rules file in $VISUAL or $EDITOR, creating it with the defaults if needed Options: -h, --help display help for command ``` ### polyglots rules check ``` Usage: polyglots rules check [options] [locale] Validate the locale rules file and summarise what it sets Options: -h, --help display help for command ``` ### polyglots rules copy ``` Usage: polyglots rules copy [options] Duplicate one locale's rules file as another's, e.g. nl_NL to nl_BE Options: --force Replace the target file if it exists -h, --help display help for command ``` ### polyglots rules path ``` Usage: polyglots rules path [options] [locale] Print where the locale rules file lives Options: -h, --help display help for command ``` ### polyglots template ``` Usage: polyglots template [options] [command] Reply templates: the whole comment posted back on a PTE request Options: -h, --help display help for command Commands: edit [name] Open a reply template in $VISUAL or $EDITOR, creating it from a starter if needed (default name: approved) list [locale] List the reply templates of one locale, or of every locale path [name] Print where a locale's reply templates live, or where one of them does delete [options] Delete a reply template (asks first; --yes skips the question) help [command] display help for command ``` ### polyglots template edit ``` Usage: polyglots template edit [options] [name] Open a reply template in $VISUAL or $EDITOR, creating it from a starter if needed (default name: approved) Options: -h, --help display help for command ``` ### polyglots template list ``` Usage: polyglots template list [options] [locale] List the reply templates of one locale, or of every locale Options: -h, --help display help for command ``` ### polyglots template path ``` Usage: polyglots template path [options] [name] Print where a locale's reply templates live, or where one of them does Options: -h, --help display help for command ``` ### polyglots template delete ``` Usage: polyglots template delete [options] Delete a reply template (asks first; --yes skips the question) Options: --yes Delete without asking (required when stdin or stderr is not a terminal) -h, --help display help for command ``` ### polyglots tm ``` Usage: polyglots tm [options] [command] Translation memory Options: -h, --help display help for command Commands: import [options] Import TMX or .po exports into the local translation memory (additive) export [options] [file] Write the translation memory as TMX or .po (stdout when no file is given) help [command] display help for command ``` ### polyglots tm import ``` Usage: polyglots tm import [options] Import TMX or .po exports into the local translation memory (additive) Options: --locale Target locale to import (default: defaultLocale, none set yet) --project Tag imported entries with a project name -h, --help display help for command ``` ### polyglots tm export ``` Usage: polyglots tm export [options] [file] Write the translation memory as TMX or .po (stdout when no file is given) Options: --locale Memory locale (default: defaultLocale, none set yet) --format tmx or po (default: from the file name, else tmx) -h, --help display help for command ``` ### polyglots fetch ``` Usage: polyglots fetch [options] [names...] Fetch themes and plugins from translate.wordpress.org and review or translate every one Options: --get waiting (reviewed) or untranslated (translated) --parallel Projects to run at once, 1 to 8 (default: 1) --out-dir Where to save the exports (default: ~/Downloads/polyglots) --force With --get untranslated, replace a file that already exists instead of keeping it --locale Locale (default: defaultLocale, none set yet) --batch-size Entries per batch (default: 25) --fresh Ignore cached verdicts or drafts and ask again --no-ai Review only: run the deterministic checks, skipping AI adjudication --draft-engine Translate only: deepl, openai, local or none (default: deepl) -h, --help display help for command Names are slugs or translate.wordpress.org URLs, as arguments or one per line on stdin. A bare slug is tried as a theme first, then as a plugin. ``` ### polyglots review ``` Usage: polyglots review [options] Audit a submitted .po and write out only the entries that need work Options: --locale Review locale (default: defaultLocale, else the file's Language header) --out-dir Where to write the problems file (default: beside the input) --no-ai Run the deterministic checks only, skipping AI adjudication --batch-size Entries per AI batch (default: 25) --fresh Ignore the cached verdicts for this file and review it again --requester The requester's wp.org username, for {username} in the reply template --template Reply template to fill after the review (default: approved) -h, --help display help for command Environment: POLYGLOTS_AGENT_BIN agent executable for the review pass, whichever provider is set (default: claude or agy on PATH) POLYGLOTS_CLAUDE_BIN the older name, applied to claude only POLYGLOTS_HOME root for config/ and data/ instead of the XDG directories POLYGLOTS_ASCII=1 plain ASCII glyphs instead of Unicode (also NO_COLOR, FORCE_COLOR) DO_NOT_TRACK=1 never send usage statistics, whatever usageStats says POLYGLOTS_USAGE_URL where opted-in usage statistics go (default: https://ada.tools/polyglots/api/usage) NO_UPDATE_NOTIFIER=1 never check npm for a newer version (also CI, or: config set updateCheck off) ``` ### polyglots doctor ``` Usage: polyglots doctor [options] Check which agent CLIs are installed, signed in and set up, without sending a prompt Options: --json Print the result as JSON --live Also send one short prompt to each usable agent (spends a request on metered plans) -h, --help display help for command Exits 1 when the configured review provider cannot be used (or, with --live, fails its prompt). ``` ### polyglots models ``` Usage: polyglots models [options] List local model servers (Ollama, LM Studio, llama.cpp, vLLM) and the models they hold, without loading any Options: --json Print the result as JSON -h, --help display help for command Probes Ollama at ollama.baseUrl, LM Studio on localhost:1234 and llama.cpp on localhost:8080, plus any URL in localModelServers. The defaults are all on this machine; a configured URL may not be, and is asked because it was listed. Exits 1 when no server is up. ``` ### polyglots split ``` Usage: polyglots split [options] Cut a .po into numbered parts so each can be run and submitted on its own Options: --size Entries per part, counted over the whole file --force Write into a folder that already has files in it -h, --help display help for command ``` ### polyglots glossary ``` Usage: polyglots glossary [options] [command] translate.wordpress.org glossary cache Options: -h, --help display help for command Commands: sync [options] Download the WordPress.org glossary for a locale into the local cache export [options] [file] Write the cached glossary as a Poedit-compatible CSV (stdout when no file is given) help [command] display help for command ``` ### polyglots glossary sync ``` Usage: polyglots glossary sync [options] Download the WordPress.org glossary for a locale into the local cache Options: --locale Glossary locale (default: defaultLocale, none set yet) -h, --help display help for command ``` ### polyglots glossary export ``` Usage: polyglots glossary export [options] [file] Write the cached glossary as a Poedit-compatible CSV (stdout when no file is given) Options: --locale Glossary locale (default: defaultLocale, none set yet) --delimiter Column separator, ";" or "," (default: ;) -h, --help display help for command ``` ### polyglots stats ``` Usage: polyglots stats [options] Open review statistics in the browser, or write them to a self-contained HTML page Options: --out Write a standalone copy instead of serving (default off a terminal: polyglots-stats.html) --since Only count reviews started on or after this date, e.g. 2026-09-01 --no-open Serve without opening the browser; the URL is printed either way -h, --help display help for command ``` ### polyglots usage-stats ``` Usage: polyglots usage-stats [options] [command] Opt-in anonymous usage totals: see what is sent, or forget the install id Options: -h, --help display help for command Commands: show Print exactly what the next weekly send carries reset Forget the install id; a new one is made at the next send help [command] display help for command ``` ### polyglots usage-stats show ``` Usage: polyglots usage-stats show [options] Print exactly what the next weekly send carries Options: -h, --help display help for command ``` ### polyglots usage-stats reset ``` Usage: polyglots usage-stats reset [options] Forget the install id; a new one is made at the next send Options: -h, --help display help for command ``` ### polyglots config ``` Usage: polyglots config [options] [command] Settings and API keys Options: -h, --help display help for command Commands: get [key] Show a setting, or all settings (API keys are masked) set Change a setting (defaultLocale, defaultDraftEngine, reviewProvider, wporgUsername, ollama, batchSize, consistencyTtlDays, properNouns, localModelServers, localServerKind, openaiCompatible, localIdleTimeout, usageStats, updateCheck, ollama.model, ollama.baseUrl, ollama.contextLength, openaiCompatible.model, openaiCompatible.baseUrl, openaiCompatible.contextLength) add-name [options] Add a proper noun the title-case check should never flag (places, people, institutions) set-key [value] Store DEEPL_API_KEY or OPENAI_API_KEY; omit the value to read it from stdin help [command] display help for command ``` ### polyglots config get ``` Usage: polyglots config get [options] [key] Show a setting, or all settings (API keys are masked) Options: -h, --help display help for command ``` ### polyglots config set ``` Usage: polyglots config set [options] Change a setting (defaultLocale, defaultDraftEngine, reviewProvider, wporgUsername, ollama, batchSize, consistencyTtlDays, properNouns, localModelServers, localServerKind, openaiCompatible, localIdleTimeout, usageStats, updateCheck, ollama.model, ollama.baseUrl, ollama.contextLength, openaiCompatible.model, openaiCompatible.baseUrl, openaiCompatible.contextLength) Options: -h, --help display help for command ``` ### polyglots config add-name ``` Usage: polyglots config add-name [options] Add a proper noun the title-case check should never flag (places, people, institutions) Options: --locale Locale the name belongs to (default: defaultLocale, none set yet) -h, --help display help for command ``` ### polyglots config set-key ``` Usage: polyglots config set-key [options] [value] Store DEEPL_API_KEY or OPENAI_API_KEY; omit the value to read it from stdin Options: -h, --help display help for command ```