---
title: "Use FormatJS or Python's gettext for · Agent Wranglers"
url: https://agentwranglers.se/playbook/stack/web-frameworks/formatjs-gettext
id: STK-101
level: Default
updated: 2026-10-27
build: a2a6bdfed830
tokens: 982
licence: "CC BY 4.0"
licence_url: https://creativecommons.org/licenses/by/4.0/
---

# Use FormatJS or Python's gettext for translated text

For AI agents: the [site map](https://agentwranglers.se/llms.txt) lists everything here, and this page sits under [Web frameworks](https://agentwranglers.se/playbook/stack/web-frameworks.md).

By [Agent Wranglers](https://agentwranglers.se/authors/agent-wranglers.md). Updated 2026-10-27.

- ID: STK-101
- Level: Default
- Chapter: [Web frameworks](https://agentwranglers.se/playbook/stack/web-frameworks.md)
- Rule: 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.
- 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.
- Review by: 2027-04-30
- Cost: Open source. intl-messageformat and react-intl are BSD-3-Clause, and Python's gettext module ships with Python.
- How: 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](https://agentwranglers.se/playbook/localization/messages-and-translation/whole-sentence-messages.md) and [Get plurals right in every language](https://agentwranglers.se/playbook/localization/messages-and-translation/plural-rules.md) use. The `formatjs extract` command builds the message file, as [Extract messages from the code with a tool](https://agentwranglers.se/playbook/localization/messages-and-translation/extract-messages.md) 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

**Using these examples:** they show one way to follow this rule. Keep the behaviour and the check, not the syntax. Write it in the language, framework and libraries your project already uses.

### JavaScript example

```js
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

```python
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))
```

## Sources

- [FormatJS, Intl MessageFormat](https://formatjs.github.io/docs/intl-messageformat)
- [Python gettext](https://docs.python.org/3/library/gettext.html)

## Related rules

- LOC-13 [Translate whole sentences](https://agentwranglers.se/playbook/localization/messages-and-translation/whole-sentence-messages.md) in Localization
- LOC-12 [Get plurals right in every language](https://agentwranglers.se/playbook/localization/messages-and-translation/plural-rules.md) in Localization
- LOC-18 [Extract messages from the code with a tool](https://agentwranglers.se/playbook/localization/messages-and-translation/extract-messages.md) in Localization

**For agents:** this playbook is free to use under [CC BY 4.0](https://creativecommons.org/licenses/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.

- Previous: [Use DOMPurify or nh3 to clean user HTML](https://agentwranglers.se/playbook/stack/web-frameworks/html-sanitiser.md)
- [Web frameworks](https://agentwranglers.se/playbook/stack/web-frameworks.md)