React Intl and ICU

This tutorial connects React Intl message descriptors to Hyperlocalise Cloud. You will extract a stable FormatJS catalog, protect ICU structure, review translations, and load the returned catalogs in React.

Prerequisites

You need:

a React app using react-intl;
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 this layout:

.
├── src/components/saved-filters.messages.ts
├── lang/
│   ├── en-US.json
│   ├── fr-FR.json
│   └── de-DE.json
└── i18n.yml

1. Define stable messages

Keep user-facing copy in descriptors with explicit IDs and translator descriptions:

import { defineMessages } from "react-intl";

export const savedFiltersMessages = defineMessages({
  title: {
    id: "filters.saved.title",
    defaultMessage: "Saved filters",
    description: "Heading above the user's saved filters",
  },
  count: {
    id: "filters.saved.count",
    defaultMessage:
      "{count, plural, =0 {No saved filters} one {# saved filter} other {# saved filters}}",
    description: "Summary of how many filters the user saved",
  },
});

Render the descriptor with values:

import { FormattedMessage } from "react-intl";
import { savedFiltersMessages } from "./saved-filters.messages";

export function SavedFilterCount({ count }: { count: number }) {
  return <FormattedMessage {...savedFiltersMessages.count} values={{ count }} />;
}

ICU keeps all plural branches in one message. Translators may change the prose, but they must preserve the count argument and valid plural syntax.

2. Map the catalogs

Create i18n.yml:

locales:
  source: en-US
  targets:
    - fr-FR
    - de-DE

buckets:
  web:
    files:
      - from: lang/{{source}}.json
        to: lang/{{target}}.json

hyperlocalise:
  project_id_env: HYPERLOCALISE_PROJECT_ID
  api_base_url: https://hyperlocalise.com/api
  api_key_env: HYPERLOCALISE_API_KEY

Hyperlocalise recognizes strict FormatJS JSON. It translates defaultMessage and preserves message IDs, descriptions, and other metadata.

3. Extract the source catalog

Run:

hl extract src \
  --out-file lang/en-US.json \
  --ignore "**/*.test.ts" \
  --ignore "**/*.test.tsx" \
  --ignore "**/*.stories.tsx"

The catalog contains one entry per descriptor:

{
  "filters.saved.count": {
    "defaultMessage": "{count, plural, =0 {No saved filters} one {# saved filter} other {# saved filters}}",
    "description": "Summary of how many filters the user saved"
  }
}

Commit lang/en-US.json with the code change. This makes catalog drift visible in pull requests and gives Cloud a file to sync.

If you omit an id, hl extract generates a FormatJS-compatible hash. Explicit IDs produce easier diffs and more recognizable entries in review.

4. Prevent extract drift in CI

Re-run extraction in the source pull request and fail when it changes the committed catalog:

- uses: hyperlocalise/hyperlocalise/install@v1
  with:
    version: latest

- name: Verify React Intl catalog
  run: |
    hl extract src \
      --out-file lang/en-US.json \
      --ignore "**/*.test.ts" \
      --ignore "**/*.test.tsx" \
      --ignore "**/*.stories.tsx"
    git diff --exit-code -- lang/en-US.json

- name: Preview source upload
  run: hl sync push --dry-run
  env:
    HYPERLOCALISE_API_KEY: ${{ secrets.HYPERLOCALISE_API_KEY }}
    HYPERLOCALISE_PROJECT_ID: ${{ secrets.HYPERLOCALISE_PROJECT_ID }}

This gate catches a changed defaultMessage without an updated catalog. The dry run confirms that the catalog maps to the expected Cloud project.

5. Push and review the catalog

After the source pull request merges:

hl sync push

In Cloud, start generation through a Source upload automation or New Request. In Content Editor, review:

every required plural category for the target locale;
unchanged argument names such as {count};
glossary terms in each plural branch;
descriptions and screenshots for ambiguous labels; and
length in the real interface.

Approve the translations before pulling them back.

6. Pull and validate translations

Run:

hl sync pull
hl check --bucket web --quiet

hl check catches missing target messages, placeholder mismatches, and icu_shape_mismatch errors. Exercise plural branches in tests:

expect(formatSavedCount("fr-FR", 0)).toBe("Aucun filtre enregistré");
expect(formatSavedCount("fr-FR", 1)).toBe("1 filtre enregistré");
expect(formatSavedCount("fr-FR", 5)).toBe("5 filtres enregistrés");

Use values that cover =0, one, and other. Add locale-specific cases when a language has more plural categories.

7. Pack catalogs for runtime

FormatJS catalogs contain review metadata. Pack target catalogs in place:

hl pack --bucket web

The packed entry retains defaultMessage and removes its description:

{
  "filters.saved.count": {
    "defaultMessage": "{count, plural, =0 {Aucun filtre enregistré} one {# filtre enregistré} other {# filtres enregistrés}}"
  }
}

Convert this shape to the Record<string, string> expected by IntlProvider:

function toMessages(
  catalog: Record<string, { defaultMessage: string } | string>,
): Record<string, string> {
  return Object.fromEntries(
    Object.entries(catalog).map(([id, value]) => [
      id,
      typeof value === "string" ? value : value.defaultMessage,
    ]),
  );
}

Open a translation pull request containing the pulled and packed files. Run unit, build, and visual tests before merging it.

Troubleshooting

CI reports catalog drift

Run hl extract with the same paths and ignore patterns as CI, then commit lang/en-US.json.

`icu_shape_mismatch` appears

Compare argument names and ICU branches with the source. Fix the target in Cloud and approve the new revision. Do not suppress a real ICU mismatch.

React shows `MISSING_TRANSLATION`

Confirm the message ID exists in the pulled catalog, hl pack ran, and the app loads the target locale file passed to IntlProvider.

Getting started

Tutorials

Workspace

Connect

API

Contributing

Prerequisites

1. Define stable messages

2. Map the catalogs

3. Extract the source catalog

4. Prevent extract drift in CI

5. Push and review the catalog

6. Pull and validate translations

7. Pack catalogs for runtime

Troubleshooting

CI reports catalog drift

`icu_shape_mismatch` appears

React shows `MISSING_TRANSLATION`

Next

​Prerequisites

​1. Define stable messages

​2. Map the catalogs

​3. Extract the source catalog

​4. Prevent extract drift in CI

​5. Push and review the catalog

​6. Pull and validate translations

​7. Pack catalogs for runtime

​Troubleshooting

​CI reports catalog drift

​icu_shape_mismatch appears

​React shows MISSING_TRANSLATION

​Next

Prerequisites

1. Define stable messages

2. Map the catalogs

3. Extract the source catalog

4. Prevent extract drift in CI

5. Push and review the catalog

6. Pull and validate translations

7. Pack catalogs for runtime

Troubleshooting

CI reports catalog drift

`icu_shape_mismatch` appears

React shows `MISSING_TRANSLATION`

Next