Linting plugin and theme strings
polyglots lint is for the people who write plugins and themes. It reads
your translatable strings and lists the ones translators cannot get right,
whatever language they work in: a placeholder nobody explained, a sentence
glued together in code, a word that is a noun in one place and a verb in
another. Fix a string once and every locale gains.
polyglots lint ./my-plugin
polyglots lint ./my-plugin/languages/my-plugin.pot
It needs no account, no API key and no AI, and costs nothing to run.
What it reads
A folder is turned into a temporary .pot with wp i18n make-pot, the same
command WordPress.org uses, then linted. The temporary file is removed
afterwards. If the .pot cannot be made, nothing is checked and the command
exits 2 with make-pot’s own message.
make-pot keeps only the strings whose text domain matches the Text Domain
header of your main plugin file or style.css. Without that header it uses
the folder’s name, which in CI is usually the repository’s name. When the
.pot has nothing in it beyond the header, polyglots says so. Add the
header, or name the domain:
polyglots lint . --domain my-plugin
Strings make-pot takes from the header itself (the name, description and URIs) are not checked: you cannot give them a context or a placeholder.
A .pot file is linted as it is. To read polyglots-ignore markers,
polyglots needs the source files the .pot points to. It looks in the
.pot’s folder, then one folder up, which is where they are when the
.pot is in languages/. Anywhere else, name the folder:
polyglots lint build/my-plugin.pot --source .
Where make-pot comes from
In this order:
- The
wpexecutable named inPOLYGLOTS_WP_BIN. wpon yourPATH.- WP-CLI downloaded by polyglots and run with
php.
The download happens once, says so before it starts, gives up after five
minutes, and is kept in
polyglots’ data folder (~/.local/share/polyglots/wp-cli/). The version and
its SHA-512 hash are fixed in polyglots’ source; a download that does not
match is refused and not kept, and the kept file is checked again before
each use. This needs PHP on your PATH.
make-pot runs outside the folder being checked, so a wp-cli.yml in that
folder is not loaded and the files its require: names never run. That
matters when you lint a plugin you did not write.
Without PHP, make the .pot another way and lint that. With Docker, for
example:
npx wp-env run cli wp i18n make-pot . languages/my-plugin.pot
polyglots lint languages/my-plugin.pot
The rules
Errors are strings translators cannot get right. Warnings are likely problems that need your judgement.
| Rule | Level | Finds |
|---|---|---|
translators-comment |
error | A placeholder with no translators: comment |
unordered-placeholders |
error | Two or more placeholders, not all numbered |
plural-placeholders |
error | Singular and plural with different placeholders |
plural-without-count |
error | A plural form with no number in it |
concatenation |
warning | A fragment meant to be glued to other text |
ambiguous-word |
warning | A word that is both noun and verb, with no context |
same-text-different-use |
warning | A short string used in several files, with no context |
markup-in-string |
warning | HTML or a URL inside the string |
typography |
warning | Three full stops for an ellipsis, or a double space |
translators-comment
// Bad: a translator sees "%s" and has to guess.
printf( __( 'Hello %s', 'my-plugin' ), $name );
// Good
/* translators: %s: the customer's first name */
printf( __( 'Hello %s', 'my-plugin' ), $name );
The comment must be directly above the call, with nothing between, or
make-pot does not carry it into the .pot.
unordered-placeholders
// Bad: a language that names the site first cannot reorder these.
__( '%s commented on %s', 'my-plugin' );
// Good
/* translators: 1: a person's name, 2: a post title */
__( '%1$s commented on %2$s', 'my-plugin' );
plural-placeholders
// Bad: many languages use the singular form for 21, 31 and so on, which
// would then say "One item".
_n( 'One item', '%d items', $count, 'my-plugin' );
// Good
/* translators: %d: number of items */
_n( '%d item', '%d items', $count, 'my-plugin' );
plural-without-count
// Bad: _n() with no number in it.
_n( 'Item', 'Items', $count, 'my-plugin' );
// Good: put the number in, or use __() if the text does not depend on it.
_n( '%d item', '%d items', $count, 'my-plugin' );
concatenation
// Bad: word order differs between languages.
echo __( 'Posted by', 'my-plugin' ) . ' ' . $author;
// Good
/* translators: %s: author name */
printf( __( 'Posted by %s', 'my-plugin' ), $author );
Also found: strings with spaces at either end, and strings of punctuation
only, such as ':'.
ambiguous-word
// Bad: "Post" the noun and "Post" the verb are different words in most
// languages.
__( 'Post', 'my-plugin' );
// Good
_x( 'Post', 'verb: publish the post', 'my-plugin' );
same-text-different-use
A short string, one to three words, used in more than one file with no
context. If it means the same everywhere, leave it. If it does not, give
each use its own context with _x().
markup-in-string
// Bad: a translation can break the link.
__( 'Read the <a href="https://example.com/docs">documentation</a>.', 'my-plugin' );
// Good
/* translators: %s: link to the documentation */
sprintf( __( 'Read the %s.', 'my-plugin' ), '<a href="https://example.com/docs">' . esc_html__( 'documentation', 'my-plugin' ) . '</a>' );
With createInterpolateElement() in JavaScript the tags are meant to be in
the string, and translators keep them. Silence the warning there with a
marker, or for the whole plugin in the settings file.
typography
Use … instead of ..., and one space between words.
Silencing a warning
Errors cannot be silenced except by turning their rule off in the settings file, where the whole team sees it.
In the code
Put polyglots-ignore in a comment on the line of the call, or in the
comment block directly above it:
echo __( 'Post', 'my-plugin' ); // polyglots-ignore
/* polyglots-ignore concatenation -- glued to a number on purpose */
echo __( 'of', 'my-plugin' );
Rule ids after the marker silence only those rules. With no rule id, every
warning on the string is silenced. Text after the ids is ignored, so a --
and a reason is a good habit.
With a translators: comment, put the marker above it, or on the call’s
line. A comment between the translators comment and the call stops make-pot
from carrying the translators comment, and translators-comment then fires.
/* polyglots-ignore typography */
/* translators: %s: a place name */
printf( __( 'Welcome to %s...', 'my-plugin' ), $place );
When the same string is used in several places, every place needs the marker; one marked call does not hide another.
In .polyglots-lint.json
In the plugin or theme folder (or name another file with --config):
{
"rules": {
"same-text-different-use": "off",
"markup-in-string": "error"
},
"ignore": [
{ "rule": "concatenation", "msgid": "of" },
{ "msgid": "Post", "msgctxt": "admin menu" }
]
}
rulessets a rule tooff,warningorerror. Raising a warning to an error makes it fail CI.ignoresilences warnings on one string.ruleis optional (all warnings);msgctxtis optional (any context).- An unknown rule id or key stops the lint with exit 2, so a typo never silences nothing quietly.
Output and exit codes
--format text (the default) groups findings by rule, errors first.
--format json is for tools. --format github writes annotations that
GitHub Actions draws on the pull request; their paths are written from
GITHUB_WORKSPACE, so they point at the right files when the plugin is in a
subfolder of the repository.
| Exit | Means |
|---|---|
| 0 | No errors (warnings are allowed) |
| 1 | Errors, or warnings with --strict |
| 2 | Nothing was checked: bad path or settings, or no .pot could be made |
In GitHub Actions
name: Strings
on: [pull_request]
jobs:
lint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: shivammathur/setup-php@v2
with:
php-version: '8.3'
tools: wp-cli
- uses: actions/setup-node@v4
with:
node-version: 24
- run: npx polyglots lint . --format github
This page is docs/lint.md in the repository.