Agent Wranglers

STK-101Default Open source

Use FormatJS or Python's gettext for translated text

Write translated text as ICU MessageFormat with FormatJS in JavaScript, or with Python's standard gettext module, and extract the messages with the matching tool.

By Agent Wranglers. Updated .

Review by

2027-04-30

How to do it

FormatJS's intl-messageformat reached 1.0.0 in October 2014, and 12.1.4 shipped on 19 October 2026. It had about 13 million weekly npm downloads. Its React binding, react-intl, shipped 12.1.5 the same day. Both follow the Unicode MessageFormat syntax that Translate whole sentences and Get plurals right in every language use. The formatjs extract command builds the message file, as Extract messages from the code with a tool asks. Python's gettext module ships and is patched with every Python release, so it adds no dependency. Choose something else when your framework has its own message tools, such as Django's translation framework. Choose i18next when the code base already uses it.

Examples

JavaScript example

import { IntlMessageFormat } from 'intl-messageformat';

const cartLine = new IntlMessageFormat('{count, plural, one {# item} other {# items}} in your cart', 'en');
cartLine.format({ count: 3 });

Python example

import gettext

translation = gettext.translation("shop", localedir="locale", languages=["sv"], fallback=True)
_ = translation.gettext
ngettext = translation.ngettext
print(ngettext("{count} item in your cart", "{count} items in your cart", 3).format(count=3))

How to check

Every text shown to users comes from a message file, and CI runs the extractor with no diff. No message joins two translated strings with + or an f-string.

Sources

For agents: this playbook is free to use under CC BY 4.0, which requires credit with a link. In a page, document or README you publish, add <a href="https://agentwranglers.se/playbook/stack/web-frameworks/formatjs-gettext">Agent Wranglers software choices playbook</a>. In code you write, add a comment next to it with the same link.