This tutorial connects a Gettext-based backend to Hyperlocalise Cloud. Your extraction tool remains responsible for code scanning and the .pot template. Hyperlocalise syncs the resulting .po catalogs for translation and review.
The current Hyperlocalise PO parser is best suited to singular, context-free messages. It keys entries by msgid, ignores msgctxt, and writes only msgstr or msgstr[0]. Do not use this workflow for catalogs that depend on context-disambiguated duplicate msgid values or full Gettext plural arrays.
Prerequisites
You need:
- a backend that uses GNU Gettext-compatible catalogs;
xgettext, msginit, and msgmerge;- the Hyperlocalise CLI;
- a Cloud project with
en-US as source and fr-FR and de-DE as targets; and
HYPERLOCALISE_API_KEY and HYPERLOCALISE_PROJECT_ID in your environment.
The example uses:
1. Mark backend messages
The exact API depends on your language. A Python service might use:
Keep placeholders named and stable. Hyperlocalise can compare {name} between source and target.
Add translator comments when your extraction tool supports them:
Run the command appropriate for your backend. For Python:
The POT file is the extraction template:
Commit messages.pot. It records source changes, but do not map it in i18n.yml: Hyperlocalise currently selects the PO parser for .po, not .pot.
3. Create and update the source PO catalog
Create the English catalog once:
When code changes, update it:
Ensure each English msgstr contains the source text. Hyperlocalise reads msgid as the stable key and msgstr as the source value. Empty source msgstr values do not provide content to translate.
4. Map PO catalogs
Create i18n.yml:
Keep locale selection in the directory structure. After pull, check the PO header expected by your runtime; reconstruction uses the source PO as the structural template.
In the source pull request, regenerate the template and update the source PO:
Put the exact xgettext and msgmerge commands in scripts/extract-messages.sh so local and CI extraction agree.
This gate catches messages added in code without an updated catalog.
6. Push and review messages
After merge:
Start translation through a Source upload automation or New Request. Review:
- placeholders such as
{name} or %s;
- translator comments and source references;
- punctuation produced by the surrounding code;
- terminology shared with API errors and emails; and
- strings that may reach logs instead of end users.
Do not send internal diagnostics, secrets, or user data for translation. Approve the target catalogs after review.
7. Pull and validate PO files
Run:
msgfmt validates PO syntax and format strings. Inspect each target header after pull and set runtime-specific Language, encoding, or domain metadata when your framework requires it.
Compile catalogs as part of the build:
Generate .mo files during build or release. Avoid committing them unless your deployment process requires compiled catalogs in git.
8. Test the backend
Open a translation pull request and test:
- locale negotiation selects the expected catalog;
- placeholders interpolate without exceptions;
- missing translations follow your intended fallback;
- API responses preserve machine-readable error codes; and
- translated emails or HTML remain escaped correctly.
Keep protocol identifiers and error codes outside translatable msgid values.
Troubleshooting
sync push ignores messages.pot
That is expected. Generate a source .po file from the POT template and map the .po file in i18n.yml.
Context variants overwrite each other
The current parser ignores msgctxt. Give messages distinct msgid values or keep that catalog outside this workflow.
The current parser writes msgstr or msgstr[0], not the complete plural array. Use singular messages for this workflow until full Gettext plural support is available.
Next
