Fix ICU and placeholder errors in translations

To fix a placeholder error, compare the source and target message for the reported key. Restore missing or renamed arguments and repair malformed ICU syntax. Keep translated prose, then rerun hyperlocalise check on that locale and key. An icu_shape_mismatch can also reflect the CLI’s strict branch-parity rules, not just an invalid message. See locale-specific plurals below before changing a linguistically correct translation.

Find the failing message

From a configured project, run:

hyperlocalise check --format json --json-report check-report.json

The report identifies the finding, locale, file, and message key. Narrow the check using that key and locale. This guide’s examples use es-ES:

hyperlocalise check --locale es-ES --key home.greeting

--file, when needed, selects the configured source file path. See check for all scope filters.

Understand the finding

Finding	Meaning	First check
`placeholder_mismatch`	Source and target placeholders differ	Missing, extra, or renamed arguments
`icu_shape_mismatch`	ICU parsing or structural comparison failed	Braces, argument names, block types, offsets, and branch labels
`html_tag_mismatch`	Recognized HTML tag names differ in sequence	Missing or changed inline tags
`not_localized`	A target entry is absent or empty	Generate or supply a translation first

One message can produce multiple findings. Fix the underlying message before changing validation settings.

Restore a renamed argument

Source JSON:

{
    "home.greeting": "Hello, {name}!"
}

Broken Spanish target:

{
    "home.greeting": "¡Hola, {nombre}!"
}

The app supplies name, so renaming it to nombre breaks the contract. Keep the argument name in the translated message:

{
    "home.greeting": "¡Hola, {name}!"
}

Argument position can change to fit the sentence. Argument names must match the source. In a FormatJS catalog, edit the entry’s defaultMessage rather than replacing the descriptor object. i18next and mustache catalogs use interpolation instead of ICU. Keep the double braces and the placeholder name:

{
    "home.greeting": "Hello, {{name}}!"
}

Broken target {nombre} or {name} is not the same placeholder. Restore {{name}}. Formats ({{val, number}}), unescape prefixes ({{- html}}), and nesting calls ($t(help.link)) must also match the source. See i18next and interpolation placeholders.

Restore a missing plural branch

Source:

{
    "cart.items": "{count, plural, one {# item} other {# items}}"
}

Broken target with the one branch removed:

{
    "cart.items": "{count, plural, other {# artículos}}"
}

For this English-to-Spanish example, restore the branch and translate its text:

{
    "cart.items": "{count, plural, one {# artículo} other {# artículos}}"
}

Retain the argument count, the plural type, and the structural tokens. Review offset: values and exact-number branches such as =0 when present. ICU keywords are syntax, not text to translate. See the FormatJS ICU syntax guide. The CLI also flags duplicate # tokens within a plural/selectordinal branch. That is a CLI validation constraint, not a claim that every repeated number is invalid ICU.

Repair malformed ICU syntax

An unmatched brace or missing required other branch can make a message fail to parse. Compare the whole source and target expression, including nested branches. Check the source too. The current parity comparison cannot reliably diagnose all cases when the source itself fails ICU parsing. A clean CLI check is not a substitute for parsing and rendering messages in your application’s i18n runtime. For rich-text messages, preserve the tags and values your React Intl components expect. A tag check can catch structural changes, but it cannot prove that your app supplies every required rendering function. Unreal Engine gettext .po catalogs use nameless </> style tags. Hyperlocalise shows those tags as chips such as UE#0. Keep every chip. {ItemName} inside a style pair is a separate placeholder. See Unreal Engine rich text in gettext PO.

Validate the repaired message

hyperlocalise check --locale es-ES --key home.greeting
hyperlocalise check --locale es-ES --key cart.items
hyperlocalise check --locale es-ES

A clean run exits successfully. Review any other reported findings instead of assuming a structural repair also resolves missing translations or warnings. Render the messages in the app: test names containing punctuation, plural counts such as 0, 1, and 2, and any exact-number or nested select branches you use.

Can the CLI repair the translation?

check --fix retranslates fixable entries using your configured provider. Preview one key first:

hyperlocalise check --locale es-ES --key cart.items --fix --fix-dry-run

Then, with provider credentials configured, request the repair:

hyperlocalise check --locale es-ES --key cart.items --fix
hyperlocalise check --locale es-ES --key cart.items

The preview makes no translation API calls and writes no target files. The actual repair can incur provider charges and replace reviewed text. Review the diff and validate again. Missing files and orphaned keys are not repaired by --fix.

What if the target language needs different plural categories?

Plural categories depend on the locale. A target may drop or add CLDR categories such as one, few, or many. icu_shape_mismatch still requires matching argument names, block types, offsets, and exact matches (=0, =1). unreachable_plural_case flags a category the target locale never selects. Japanese has no one category, so delete that branch and keep other. Do not remove a needed grammatical form to silence the check. Cover 0, 1, and several items in runtime tests.

Prevent repeat failures

Add descriptions explaining what argument values represent.
Keep source ICU expressions valid and test their branches.
Review both language quality and runtime behavior after translation.
Add GitHub Actions validation to catch regressions.

For the complete app workflow, see Translate React Intl messages.

​Find the failing message

​Understand the finding

​Restore a renamed argument

​Restore a missing plural branch

​Repair malformed ICU syntax

​Validate the repaired message

​Can the CLI repair the translation?

​What if the target language needs different plural categories?

​Prevent repeat failures