WP-CLI (SwiftLing Pro)

Documentation / Developers

SwiftLing Pro adds wp swiftling to WP-CLI, on the same functions as its REST API (see REST API and AI agents). Run it where WordPress runs, in a script, in a deploy or over SSH (wp --ssh=user@host/path swiftling …). wp help swiftling <command> describes every command and option on your installation.

Commands that read or change translations run as a user: add --user=admin. They may do what that user may do in the translation editor.

The commands

Command	What it does
wp swiftling status	The original, the translation service and its characters this month, and how far each language has come across the pages and posts visitors open. --format=table|json|csv|yaml.
wp swiftling languages	The languages, the original first. --format as above.
wp swiftling check	Checks pages on the server, so their texts are known.
wp swiftling translate	Translates with the translation service. See below.
wp swiftling to-translate	What still needs translating in a language.
wp swiftling export	Texts with their originals, translations and states, as JSON, for a translator or another tool.
wp swiftling import	The translations of such a file, filled in, back into the site.
wp swiftling flush-cache	Empties SwiftLing’s cache of maps and translations, and the pages of the cache plugins SwiftLing knows.
wp swiftling clean	Removes what SwiftLing kept of posts no longer on the site.

What you translate: subjects

A subject is what the translation editor opens:

Subject	Example
A post, page or product	post:12 (or just 12)
A template of a block theme	template:twentytwentyfive//archive
A kind of page of a classic theme	view:search
The terms of a list	terms:category
A classic menu	menu:3
A builder’s subject, such as an options page of Advanced Custom Fields	as wp swiftling to-translate lists it

Several commands take subjects in two ways: name them (post:12 post:13), or use --all for every subject of a kind.

Option	Meaning
--all	Every subject of a kind instead of the ones you name.
--kind=<kind>	With --all: post (the default), template, terms, menu or all.
--type=<type>	With --all and posts: only one post type, as page.

wp swiftling check takes <subject>…, --all, --kind and --type.

States

Every text of a page is in one state:

State	Meaning
missing	Not translated yet: visitors read the original.
machine	A service translated it, nobody has read it yet.
reviewed	Someone checked it (or wrote it).
outdated	The original changed since it was translated. The old translation stays, marked outdated, until someone reviews it.
official	The translation of WordPress, the theme or a plugin. SwiftLing never sends these to a service.
partial	Of a page: some texts are translated, some not.
duplicate	Of a page: the language keeps the original on purpose (“Keep the original” in the editor).

Translating

wp swiftling translate [<subject>…] --lang=<slug> [--all] [--kind=<kind>] [--type=<type>] [--again=<states>] [--recheck] [--yes] --user=admin

• --lang is the language’s slug, several separated by commas (de,fr,hr), or all for every language.
• It uses the service chosen on Settings › Translation service, with its key, and counts against your account with that service. Only one service translates at a time.
• Each page is checked on the server first. What the service translated before it stops (a refused key, a used-up quota) is kept.
• --all asks before it starts, because it costs characters. Add --yes to skip the question, as in a script.

Fill the empty texts (the default)

wp swiftling translate post:12 --lang=de --user=admin
wp swiftling translate --all --type=page --lang=de,fr --yes --user=admin
wp swiftling translate --all --lang=all --yes --user=admin

Only texts without a translation are sent. A text someone wrote or reviewed is never touched, and a machine translation is left as it is.

--all takes the pages that still have texts to fill, as their last check knows them: not translated, partly translated, or outdated. A page changed since its last check can have new texts that the check does not know yet. Add --recheck to check every page again:

wp swiftling translate --all --lang=all --recheck --yes --user=admin

A text whose original changed keeps its previous translation, marked outdated, for someone to review in the editor. The default run does not replace it.

Translate again: --again

--again=<states> translates again the texts that are in those states, instead of filling the empty ones. <states> is machine, reviewed, or both separated by a comma.

You write	What it translates again
--again=machine	Texts a service translated before and nobody has reviewed. The new translation replaces the old one and is saved as machine. Reviewed texts stay.
--again=reviewed	Texts someone checked or wrote by hand. They are replaced with a machine translation, so this overwrites manual work. Use it only when you mean it.
--again=machine,reviewed	Both: every text that has a translation of its own, except the official ones. This is “translate everything from scratch” for what is already translated.

Things to know about --again:

• It does not fill empty texts. To also fill what was never translated, run the command once without --again as well (before or after).
• No copy of the old translations is kept. If you might want them back, run wp swiftling export first.
• official texts (WordPress, theme and plugin translations) and outdated texts are never sent. An outdated text is for review.
• With --all, --again takes every subject except one that keeps the original. --recheck is not needed.
• Texts that are only addresses, code or have no words are never sent, whatever you ask for.
• Everything still goes to the service you chose, so it counts against your account. Check wp swiftling status for the characters this month.

# translate the machine translations of one page into German again
wp swiftling translate post:12 --lang=de --again=machine --user=admin

# a whole site, every language: fill what is empty, then redo the machine translations
wp swiftling translate --all --lang=all --yes --user=admin
wp swiftling translate --all --lang=all --again=machine --yes --user=admin

# the templates (header, footer) again, including what someone reviewed. Back up first.
wp swiftling export --all --kind=template --lang=de --file=templates-de.json --user=admin
wp swiftling translate --all --kind=template --lang=de --again=machine,reviewed --yes --user=admin

What is left to translate

wp swiftling to-translate --lang=de [--kind=<kind>] [--type=<type>] [--state=<states>] [--format=<format>] --user=admin

By default it lists what is not translated, partly translated, outdated or only machine translated. --kind is post (the default), template, terms or menu. --state is a comma list of missing, partial, outdated, machine, reviewed and duplicate. --format is table, json, csv, yaml or count.

wp swiftling to-translate --lang=de --format=count --user=admin
wp swiftling to-translate --lang=de --kind=post --type=page --state=machine --user=admin

A page never checked has no texts known yet, so it is listed as missing.

Export and import

wp swiftling export [<subject>…] --lang=<slug> [--all] [--kind=<kind>] [--type=<type>] [--state=<states>] [--file=<file>] --user=admin
wp swiftling import <file> [--state=<state>] [--dry-run] --user=admin

export writes JSON with each text’s original, translation and state. Each page is checked on the server first. --state takes only texts in those states: missing, outdated, machine, reviewed, official. Without --file it is printed.

import reads such a file with the translations filled in:

• <file> is a path, or - for the standard input.
• --state=reviewed (the default) or --state=machine is the state the translations are saved in.
• --dry-run checks and saves nothing.
• Each subject’s page is checked first, and everything of it before anything is saved. A translation of an original that changed since the export is refused with that subject, as is a translation of a text from code that asks for a value its original does not give. An empty translation in the file leaves the text as it is.

wp swiftling export --all --lang=de --state=missing --file=de.json --user=admin
wp swiftling import de.json --dry-run --user=admin
wp swiftling import de.json --user=admin

Checking pages

wp swiftling check post:12 --user=admin
wp swiftling check --all --kind=template --user=admin

Checks the page of each subject on the server, as the translation editor does, so its texts are known. The check runs no scripts: a text a script builds after the page loads, or one kept in a data-* attribute that a script prints, is not found.

Keeping the site fast

After a big run, wp swiftling flush-cache empties SwiftLing’s cache and the pages of cache plugins SwiftLing knows. wp swiftling clean removes what SwiftLing kept of posts that are no longer on the site.