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:
- Locale: the language you translate into. Type a few letters (
de,pt_BR,nl_NL_formal) and choose from the matches. - 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.
- 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.
- Glossary sync: downloads your locale’s glossary from translate.wordpress.org. A review will not start without it.
- Translation memory: your locale’s published memory from
polyglots-data, when it has one: a summary of what would be imported,
then
ydownloads 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 withpolyglots tm fetch. Optional, like every import. See Fetching a locale’s memory. - 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,
localeand the locale you translate into, ornonewhen no locale is set (the header shows it on every screen; see Changing the locale),reviewand the agent that reviews (pon home switches it),setupand how many of the six steps are done, with a tick or a cross for each. Presstabto move onto them, arrows to choose one, andenterto open the wizard at that step.statsand 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.
- Pick a file. The list shows the
.pofiles in the folder you started polyglots from, newest first, with how many entries each holds...goes up a folder,schanges the order. - 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
↑↓ortab, change a choice with←→orspace, and choose Start withenter. The run uses the locale in the header;lchanges it. When the file’sLanguageheader names another language, the options say so. With no locale set, the options start with a Locale field instead, filled in from the file’sLanguageheader when it names one. - 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.
ppauses,rresumes andqstops. Each takes effect once the batch in progress finishes, so nothing already paid for is thrown away. - 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.
ccopies whichever is shown,tswitches template, andoopens the repaired file in your.poeditor. Without a template, a line points to Configuration › Reply templates.apicks another file with the same settings, andentergoes 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.