Skip to content

Clarify when ngettext is required in agent guidelines #2476

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
dsblank wants to merge 2 commits into
base: master
Choose a base branch
from
Open

Clarify when ngettext is required in agent guidelines #2476

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
95e5736
Clarify when ngettext is required in agent guidelines
dsblank Jul 18, 2026
4485f48
Fix wrong English-plural framing in ngettext guidance
dsblank Jul 18, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 25 additions & 1 deletion AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -202,7 +202,31 @@ All user-visible strings must be wrapped with `_()` for translation support:
raise ValueError(_("Invalid handle: %s") % handle)
```
The alias `_(string , context)` is preferred to `pgettext(context, message)`.
Use `ngettext(singular, plural, n)` for plural forms.

Use `ngettext(singular, plural, n)` instead of `_()` whenever a formatted

@Nick-Hall Nick-Hall Jul 18, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We still need to use ngettext even when the English plural form is the same as the singular or the case where n is always greater than 1. Many languages have more complex plural forms than in English.

@dsblank dsblank Jul 18, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good catch, that framing was itself wrong. Reworded to drop the "English form changes" test entirely — the rule is now "any string that counts a noun" uses ngettext, and I called out explicitly that identical English singular/plural and n-always->1 are not valid reasons to skip it, since other languages have plural rules (2-4 vs 5+, dual forms, etc.) English doesn't. Commit 4485f48.

string embeds a count next to a noun whose English form changes between 1
and 2+ (person/people, entry/entries, generation/generations, match/matches,
timestamp/timestamps, etc.):

```python
ngettext(
"%(count)d person",
"%(count)d people",
count,
) % {"count": count}
```

Before finishing a change, check every `_("...%d..."` / `_("...%(name)d..."`
string you wrote or touched against this rule — `_("Found %d people")`
produces "Found 1 people" for translators with no way to fix it.

Ordinal or fraction displays with no inflecting noun (`"page %(cur)d/%(total)d"`,
`"generation %(gen)d/%(total)d"`, `"row %(row)d"`) do *not* need `ngettext` —
only convert a string when an actual noun in it would change form.

If a package centralizes its `_` alias (e.g. `_ = glocale.translation.gettext`
in an `__init__.py`), also export `ngettext = glocale.translation.ngettext`
there, so submodules can import both together.

## Submodule Import Rules

Expand Down
Loading