Damaged format placeholders in the el and fa catalogues abort the build instead of warning

[katerynaKhar]

Describe the bug

Three strings in the shipped catalogues have damaged str.format placeholders.
Because sphinx/config.py formats the translated message eagerly —
logger.warning(msg.format(...)) — the result is not a mangled warning but an
aborted build.

check_confval_types is a config-inited handler, so the exception is caught by
EventManager.emit and re-raised as

ExtensionError: Handler <function check_confval_types ...> for event 'config-inited' threw an exception

A user running under LANGUAGE=el or LANGUAGE=fa therefore gets a crash that
blames an extension, in place of the warning that their conf.py holds a value
of the wrong type.

The three strings:

locale	msgid at	what the translation has	why it fails
el	config.py:829	'{name]' … '[current__name__}'	braces swapped for brackets; does not parse as a format string
el	config.py:846	{current__name__}, {default__name__}	the dots are gone, so the names do not exist → KeyError
fa	config.py:846	{permitted} where {default.__name__} belongs	permitted is not passed to this call → KeyError

The fa one looks borrowed from the sibling message at config.py:829, which
does take permitted.

I checked all 71 catalogues — 18,968 translated strings — and these are the only
three where the placeholders do not match their msgid. Everything else is clean.

doc/internals/contributing.rst says pull requests altering translation files
are not accepted, so I have not opened one; these need someone with Transifex
access. The second half, under Additional context, is code rather than
translation, and I would be glad to send a PR for it.

How to Reproduce

I have no Python interpreter on this machine, so this comes from reading the
shipped catalogues and the call sites rather than from a build I ran. The
catalogue half can be confirmed on its own, from a checkout, without building
anything:

import gettext

t = gettext.translation('sphinx', 'sphinx/locale', languages=['el'])
msg = t.gettext(
    "The config value `{name}' has type `{current.__name__}', "
    "defaults to `{default.__name__}'."
)
print(msg.format(name='x', current=int, default=str))

That is the same lookup and the same .format() call as sphinx/config.py:849,
with the same keyword arguments, and it raises.

For the build-level symptom: build any project whose conf.py holds a value of
the wrong type, under LANGUAGE=el or LANGUAGE=fa.

The damaged strings are present in the compiled .mo files, which are tracked in
the repository, so nothing needs recompiling to reproduce this.

Environment Information

Read from a checkout of sphinx-doc/sphinx at `e44a40e` (main), specifically
`sphinx/locale/*/LC_MESSAGES/sphinx.po` and the matching `.mo` files.

No `sphinx-build --bug-report` output: there is no Python interpreter on this
machine and I did not run Sphinx. Everything above comes from the catalogues and
the source, and the snippet under "How to Reproduce" is there so it can be
checked in a second rather than taken on trust.

Sphinx extensions

Additional context

Repairing the three strings is one thing; the exposure behind them is another.

.format() is called on a translated string in six places:

sphinx/config.py:801, 840, 849
sphinx/transforms/i18n.py:156
sphinx/_cli/__init__.py:73, 170

Each is evaluated eagerly, so a damaged placeholder in any locale, in any of
these messages, raises rather than degrades. Messages passed as
logger.warning(__('...%s'), arg) are safer, because the logging module catches
formatting errors itself — the .format() calls have no such backstop.

Two ways to close it, not mutually exclusive:

1. Fall back to the untranslated message when formatting the translated one
   fails. The user then gets an English warning instead of a dead build.
2. Check placeholders when the catalogues are compiled. utils/babel_runner.py compile already walks every .po; comparing the format fields of each
   msgstr against its msgid there would have caught all three of these when
   they were pulled from Transifex, and would keep catching the next ones.

Happy to send a PR for either.

Found with i18n-keeper, then
verified by hand against the catalogues and the call sites.

[shashb27]

Confirmed against a checkout of main — the catalogue half reproduces in a second, no build needed (the .mo files are tracked in the repo):

>>> import gettext
>>> t = gettext.translation('sphinx', 'sphinx/locale', languages=['el'])
>>> msg = t.gettext("The config value `{name}' has type `{current.__name__}', "
...                 "defaults to `{default.__name__}'.")
>>> msg.format(name='x', current=int, default=str)
KeyError: 'current__name__'        # el, the config.py:846 family

and fa raises KeyError: 'permitted' on the same msgid — both exactly as in the table above.

For the code half, I'd propose the fallback route (option 1 in the report): the six eager .format() call sites (config.py:801, 840, 849, transforms/i18n.py:156, _cli/__init__.py:73, 170) format translated text directly, so a single damaged placeholder in any locale kills the build with an ExtensionError that blames an extension. A small safe-format helper that falls back to the untranslated msgid when .format() raises degrades that to an English warning instead of a dead build — a strictly smaller behavioral change than compile-time validation (a similar locale-check CI approach was attempted and closed in #12394).

Happy to send that PR with a regression test that drives a corrupted placeholder through check_confval_types under a stubbed catalogue. (Can't help with the Transifex half — flagging that for someone with access.)

[katerynaKhar]

Thanks for confirming — and for offering to take the code half. Option 1 is the
right first step, and a PR from you is better than one from me: you can drive it
through check_confval_types properly.

One thing that saves you a detour. The compile-time check I suggested as option 2
has been tried: #12394, closed in 2024. Not because the check was wrong, but
because .po files edited in this repo are not pushed back to Transifex, so a
repo-side CI job guards something the next sync overwrites. The author landed on
the right place himself — inside the workflow that pulls translations, before
they are committed. Worth aiming there rather than at babel_runner.py compile.

Also relevant to "someone with Transifex access": in that same thread a maintainer
said they could not see what was happening in Transifex either. So the catalogue
half may not have an obvious owner.

[shashb27]

PR for the code half is now open: #14666.

Thanks @katerynaKhar for yielding the code half and for the #12394 pointer — knowing that repo-side .po edits don't survive the Transifex sync is what kept this scoped to the runtime fallback, and your "validate inside the pull workflow" placement is noted here for whoever picks up the catalogue half.

What the PR does, briefly: a safe_format helper in sphinx.locale formats the translated message and falls back to the original English text when the translation's str.format placeholders don't match the msgid's (renamed, dropped, or added) or when formatting raises. A plain try/except alone would miss dropped placeholders — str.format silently ignores surplus arguments — so it compares placeholder sets instead, while still allowing legitimate translator reordering. All six eager call sites (config.py x3, _cli/__init__.py x2, transforms/i18n.py) now route through it: a damaged el/fa catalogue degrades to an English warning instead of a dead build.

The Transifex/data half remains open here for someone with access.

[katerynaKhar]

Nice — and the placeholder-set comparison is the right call, not just extra
caution. A dropped placeholder doesn't raise at all: str.format ignores
surplus arguments, so try/except alone would have covered the malformed half
and missed the silent half entirely.

For what it is worth, the silent half is the larger one. Across the four
projects I scanned, placeholders that were simply dropped outnumbered malformed
ones by roughly fifteen to one — 1352 of 1439 findings in Laravel-Lang. Sphinx
happens to have caught the loud cases first.