Agent Wranglers

LOC-18Recommended

Extract messages from the code with a tool

Build the source message file from the code with an extraction tool, never by hand. CI fails when the committed file differs from a fresh extraction.

By Agent Wranglers. Updated .

How to do it

Hand-kept message files drift. A key used in the code is missing from the file, and a deleted screen leaves keys nobody uses. Run the extractor for your format, such as formatjs extract, pybabel extract or xgettext. Commit its output as the one source for translators. Keep the translator notes from Translate whole sentences in the code next to each message, so the extractor carries them along.

Examples

JavaScript example

// package.json scripts, with FormatJS
// "i18n:extract": "formatjs extract 'src/**/*.{js,jsx,ts,tsx}' --out-file lang/en.json --id-interpolation-pattern '[sha512:contenthash:base64:6]'"
const greeting = intl.formatMessage({ defaultMessage: 'Welcome back, {name}', description: 'Heading on the dashboard after sign-in' }, { name });

Python example

# pybabel extract -F babel.cfg -o messages.pot --add-comments=TRANSLATORS: .
# TRANSLATORS: Heading on the dashboard after sign-in
greeting = _("Welcome back, {name}").format(name=name)

How to check

CI runs the extractor and then git diff --exit-code on the source message file. A message added to the code without a new extraction fails the build.

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/localization/messages-and-translation/extract-messages">Agent Wranglers localization playbook</a>. In code you write, add a comment next to it with the same link.