The interactive app

Run polyglots with nothing after it and it opens a full-screen app in your terminal window. Everything polyglots does is there: reviewing a submission, translating a file, fetching from translate.wordpress.org, statistics, and all of the settings. You move with the arrow keys and enter, and every screen lists its own keys at the bottom. If you would rather type commands, or want to script the work, see Getting started: every screen has a command behind it.

The window needs to be at least 60 columns wide and 20 rows tall. At 80 by 24 or larger the home screen shows its cards in a grid; smaller, it shows a list. A window that is too small says so until you make it bigger, and a run in progress carries on underneath.

The first run

On a fresh install the app opens on the setup wizard rather than on home. It has six steps:

  1. Locale: the language you translate into. Type a few letters (de, pt_BR, nl_NL_formal) and choose from the matches.
  2. Review provider: the AI agent that reviews: Claude Code, Antigravity or Codex, whichever is installed and signed in on this machine, or a model on your own computer (experimental), or No AI, which runs the rules alone (what that means). Each option says what it costs.
  3. Draft engine and API keys: what fills in untranslated strings: DeepL, OpenAI, a local model, or translation memory only, and the key it needs. Skip this if you only review.
  4. Glossary sync: downloads your locale’s glossary from translate.wordpress.org. A review will not start without it.
  5. Translation memory: your locale’s published memory from polyglots-data, when it has one: a summary of what would be imported, then y downloads and imports it. Shown only for a locale polyglots-data has; offline, it is skipped with a note. The skip is kept for that locale, so the step is not offered again for it; fetch the memory later from Tools (o) > Import Translation Memory, or with polyglots tm fetch. Optional, like every import. See Fetching a locale’s memory.
  6. Locale rules: the checks for your language’s conventions. polyglots ships none; fetch your locale team’s file (Fetch from polyglots-data on this screen) or start one here. See Locale rules.

Last, it asks once whether to share a few anonymous totals for the website. The answer is No unless you choose Yes; see Usage statistics.

enter chooses and moves on, esc skips a step. You can stop part way: the wizard opens again next time at the first step still missing, and once you have been through it to the end it stays under Configuration › Setup wizard for whenever you want it.

Home

The top of the screen shows:

  • the version, and beside it the newer one when npm has a newer release. The same notice, with the command to update, is printed when you quit,
  • locale and the locale you translate into, or none when no locale is set (the header shows it on every screen; see Changing the locale),
  • review and the agent that reviews (p on home switches it),
  • setup and how many of the six steps are done, with a tick or a cross for each. Press tab to move onto them, arrows to choose one, and enter to open the wizard at that step.
  • stats and an address, while the statistics page is being served.

Below are the cards. Press a card’s letter to open it, or move with the arrows and press enter.

Key Card What it does
r Review a submitted .po Checks a submission with your locale’s rules and the review agent, repairs what it can, and writes the problems to a file. See Reviewing submissions.
t Translate a .po file Fills untranslated entries from your translation memory first, then machine drafts, and marks drafts fuzzy for you to check. See Translating.
f Fetch from translate.wordpress.org Downloads the waiting or untranslated strings for a list of projects, and can review or translate each file as it arrives.
s Review statistics Serves your statistics page from this machine while the app runs, and can write a copy to keep.
o Tools Split a large .po into parts, import translation memory from a file or fetch your locale’s from polyglots-data, export it.
c Configuration Glossary, locale rules, agents, local models, API keys, the setup wizard and interface settings.
h Help Every screen and every key, on one page.
a About The version, where polyglots keeps its files, and links.

q on home quits.

After an update, home lists what is new in that version under the cards, once: the next time you open the app it is gone. If you skipped versions, it lists what each of them added, up to three lines, with a link to the full release notes for the rest. When the window is too short to show it under the cards, it waits until the window is taller.

Keys that work everywhere

Key What it does
? Help for the screen you are on: what it is for and all of its keys.
ctrl+k or : Go to any screen. Type to filter, arrows to choose, enter to go.
l Change the locale, from any screen with a frame except the setup wizard. Not while you type into a field.
esc Back.
q Back one level; quits from home; stops a run.
ctrl+c Quit. If a run is going it asks first; a second ctrl+c quits.
x Stops the statistics server while it serves, from any screen.
page up / page down Scroll a screen taller than the window.

The bottom line of every screen shows the keys that matter at that moment, so during a run it shows pause and stop, and once the run is done it shows how to open the result. When you type into a field, letters go into the field; ctrl+k still opens the go-to list.

Changing the locale

Press l, or choose Change locale in the go-to list (ctrl+k), and a picker opens. Type a few letters to search. With nothing typed, it lists your current locale first, marked current, and then the locales you used before, five in all. enter saves the choice as your default locale, the same setting the setup wizard writes, and the screen you are on loads again in the new locale.

The picker refuses in two cases. While a job runs (a review, a translation, a fetch, a glossary sync or a memory import), it says “The locale changes after the current job ends.” In Locale rules or in the reply templates editor with unsaved changes, it says “Save or discard the changes first.”

The first time you change to a locale that has no glossary or no locale rules yet, the app asks once whether to set it up. y opens the setup wizard at the first missing step and goes on through that locale’s steps (glossary, memory, rules), then returns you to the screen you were on. Offline, the memory step is passed without a lasting skip, so it is offered again later. The app does not ask again for that locale, whatever you answer.

Running a review or a translation

Review and Translate work the same way, in four stages.

  1. Pick a file. The list shows the .po files in the folder you started polyglots from, newest first, with how many entries each holds. .. goes up a folder, s changes the order.
  2. Options. How many entries go to the agent at a time, for a review, whether to skip the AI and use the rules alone, and for a translation, the mode and the draft engine. Start over ignores what is cached and asks again: for a review, instead of carrying on where an earlier run stopped; for a translation, instead of reusing the drafts and reviews from an earlier run, which a re-translation of every entry would otherwise take from the cache unchanged. Move with ↑ ↓ or tab, change a choice with ← → or space, and choose Start with enter. The run uses the locale in the header; l changes it. When the file’s Language header names another language, the options say so. With no locale set, the options start with a Locale field instead, filled in from the file’s Language header when it names one.
  3. Running. A progress bar, the batch being worked on, the time left and when it should finish, and a panel of the most recent entries with what happened to each: approved, flagged, repaired or unreviewed. p pauses, r resumes and q stops. Each takes effect once the batch in progress finishes, so nothing already paid for is thrown away.
  4. Done. A summary. A review shows the message to send the contributor, or, with a reply template for the locale, the whole reply in its place. c copies whichever is shown, t switches template, and o opens the repaired file in your .po editor. Without a template, a line points to Configuration › Reply templates. a picks another file with the same settings, and enter goes back to the menu.

a works after a finished run and after a stopped one. The file list opens in the folder of the file just done, and the pick goes straight to the options with your last choices filled in and Start selected, so one enter starts it. The batch size, skip AI and draft engine carry over. Start over goes back to no, and a translation’s mode goes back to pending only, so neither throws away work in the next file. With no locale set, a locale you typed carries over, and one that came from the file’s Language header is read again for the new file. When a carried locale does not match the new file’s Language header, the options screen says what the header names.

A stopped run is never wasted. Start the same file again and only the entries that were not reached are sent; the rest come from the cache.

Several files in one batch

In the file list, space marks the file under the cursor, with a bullet before its name, and space again unmarks it. * marks every file in the folder, and unmarks them when they are all marked already. Marks stay while you move between folders, so a batch can hold files from several; the count under the list is what is marked, whether or not those files are on screen. A review’s own output (-problems.po, -repaired.po) cannot be marked, and the list says why when you try.

enter with nothing marked opens the one file, as above. enter on a file with anything marked opens the batch options instead, which list the marked files first. They are Fetch’s: the Requester when your locale has a reply template, how many files run at once (Parallel, 1 to 8), the batch size, whether to start over, and for a review whether to skip the AI, or for a translation the draft engine. A batch translation fills pending entries only. Every file runs in the locale in the header. With no locale set there is a Locale field first: leave it empty, shown as per file, and each file runs in the locale its own Language header names; a file whose header names none fails on its own and the rest carry on. esc goes back to the file list with the marks kept.

The run and its summary are Fetch’s too. While it runs, two lines on top say how many files are done, running and queued, how long the batch has taken, an estimate of the time left (an upper bound while files are still queued) and how many batches failed. Under them is a line per file: a running file shows its batch and how long that batch has been open, in yellow with “near the time limit” once it is a minute short of the agent’s timeout, and a finished file shows its total time and any failed batches. ↑↓ moves over the files and enter opens one file’s own progress screen, the one a single run shows, updating as it runs; esc goes back to the list. p, r and q still act on the whole batch from there.

The summary lists how each file ended and the tally. Under them is the reply for the file under the cursor, or its message for the contributor when there is no template. ↑↓ moves to another file, c copies the one shown and t switches its template. enter opens that file’s final screen, with its time and the reason each failed batch gave; esc or q leaves the summary. A requester typed in the options fills every reply; left empty, each reply keeps {username} for you to fill in. a is not offered after a batch. The command line does the same with polyglots review a.po b.po --parallel 2.

Fetch adds two stages at the front: type the projects, one per line, as slugs or translate.wordpress.org addresses (enter on an empty line, or ctrl+d, when the list is done), then choose waiting or untranslated strings and let it check the list. It shows which projects have work and which have none before anything is downloaded. A plugin’s readme comes as a line of its own when it has strings to get; r on the same step turns that off.

While a run is going, the go-to list will not leave its screen, and quitting asks first. Once you quit, the path of the last file a run wrote is printed in your terminal, where it stays after the app has closed. Turn that off under Configuration › Interface settings.

Statistics

The statistics screen serves your review history as a page on this machine; o opens it in your browser. It keeps serving after you leave the screen, and the address stays in the header until you stop it with x. w writes a standalone copy you can keep or share, and s serves it again once stopped.

Configuration

Key Screen What it does
g Sync WordPress.org glossary Downloads your locale’s glossary on enter. Run it again when your team changes it. With no locale set, it asks which.
e Edit glossary Opens your locale’s glossary in the browser as a table, and keeps your changes across a sync. See Glossary editor.
r Locale rules Edits your locale’s rules: which built-in checks run, proper nouns, common mistakes, patterns, and guidance for the reviewer. s saves. It opens on the current locale, and asks which locale only when none is set. Fetch from polyglots-data comes first in the list when polyglots-data has maintained rules for the locale; it shows what the published file would change and writes it on y. Open the rules builder in your browser opens the website’s rules builder for the locale, and shows its address.
t Reply templates Your locale’s reply templates: e edits one, n creates one from a starter, d deletes one, v previews it clean or with problems.
a Check AI agents Shows whether each review agent is installed, signed in and set up for polyglots. r checks again. d turns debug mode on or off.
m Local models Finds model servers on this machine, such as Ollama or LM Studio, and chooses the drafting model. See Local models.
k Configure API keys Stores your DeepL and OpenAI keys. A key set in your environment wins over a saved one.
w Setup wizard The six setup steps, from wherever you left them.
i Interface settings Settings for the app only, such as printing the last output path after you quit.
u Usage statistics Shows exactly what would be shared for the website’s totals, and turns it on or off. Below it, whether to offer problem reports. See Usage statistics.

Everything set here is the same configuration the commands read; see Configuration.

Terminals without Unicode

Where the terminal cannot draw Unicode (LANG=C, TERM=dumb, or POLYGLOTS_ASCII=1), the app uses plain ASCII: + for a tick, > for the pointer, and simple boxes.

On Windows the app is plain ASCII unless it runs in Windows Terminal, VS Code’s terminal, a JetBrains IDE or Cmder. The PowerShell and Command Prompt windows of Windows 10 show the Unicode symbols as empty boxes. Windows 11 opens them in Windows Terminal, which draws them. If your console font has the symbols, POLYGLOTS_ASCII=0 turns Unicode back on.

This page is docs/interactive.md in the repository.