Generate next-intl JSON Message Files from an Excel Key-Value Spreadsheet

Single namespace into messages/en.json

The canonical next-intl shape: a HomePage namespace with a few keys. Run once per locale, changing valueColumn, to get matching en/fr files.

Sheet (first tab):
key               | en              | fr
------------------|-----------------|------------------
HomePage.title    | Welcome         | Bienvenue
HomePage.subtitle | Get started     | Commencez

Options: keyColumn=key, valueColumn=en, nested=true

Output → en.json (save as messages/en.json):
{
  "HomePage": {
    "title": "Welcome",
    "subtitle": "Get started"
  }
}

Deep nesting for sub-sections

Three-level keys build a three-level tree. next-intl reads it with a namespace plus a dotted lookup inside the component.

Sheet:
key                    | en
-----------------------|------------------
Dashboard.header.title | Your dashboard
Dashboard.header.kpi   | Active users
Dashboard.empty        | Nothing yet

Output → en.json:
{
  "Dashboard": {
    "header": {
      "title": "Your dashboard",
      "kpi": "Active users"
    },
    "empty": "Nothing yet"
  }
}

// useTranslations('Dashboard'); t('header.title')

ICU plural messages survive untouched

next-intl uses ICU MessageFormat. The braces and pluralisation syntax are part of the VALUE, which is written verbatim — only keys are trimmed.

Sheet:
key               | en
------------------|---------------------------------------------
Cart.items        | {count, plural, one {# item} other {# items}}
Cart.greeting     | Hi {name}!

Output → en.json:
{
  "Cart": {
    "items": "{count, plural, one {# item} other {# items}}",
    "greeting": "Hi {name}!"
  }
}
(ICU syntax preserved exactly)

Two locales, identical structure

Running once per locale guarantees the same key tree in every file. That alignment is what makes next-intl's missing-key detection meaningful.

key            | en       | fr
---------------|----------|-----------
Nav.home       | Home     | Accueil
Nav.account    | Account  | Compte

Run 1 valueColumn=en → en.json
Run 2 valueColumn=fr → fr.json

en.json: { "Nav": { "home": "Home",   "account": "Account" } }
fr.json: { "Nav": { "home": "Accueil","account": "Compte"  } }

Untranslated cells become empty strings

A row with a key but a blank value writes "". This is handy: next-intl will fall back, and you can grep the file for : "" to find every string still awaiting translation.

Sheet:
key            | fr
---------------|-----------
Nav.home       | Accueil
Nav.beta       |            ← not translated yet

Output → fr.json:
{
  "Nav": {
    "home": "Accueil",
    "beta": ""
  }
}
(grep ': ""' to list untranslated keys)

With nested: false, HomePage.title stays a flat key "HomePage.title". next-intl's useTranslations('HomePage') then can't find a HomePage namespace object and the lookup misses. For next-intl you almost always want nested: true.

If you have both Settings (a value) and Settings.theme (a child), they collide on the Settings path under nesting. One overwrites the other by row order, so a whole namespace can vanish. Keep namespace names distinct from leaf keys.

Set valueColumn: EN when the header is en and every value reads as empty string — you get a correctly-shaped tree full of "". next-intl will render blanks. Match the header text exactly, including case.

Only the first sheet is parsed. A workbook with a glossary on sheet 1 and messages on sheet 2 yields the glossary. Move messages to the first sheet or export that sheet as CSV.

If HomePage.title appears twice, the later row's value overwrites the earlier one silently. Output key count drops below row count. Dedupe with the duplicate-purge tool if duplicates were unintended.

Translators pasting from Google Docs often bring smart quotes (“ ”) into values. These are kept verbatim — valid in JSON and fine for display. The tool doesn't normalise them; if you want straight quotes, clean the sheet first.

A Free-tier upload above 5 MB or 10,000 rows is rejected before any JSON is produced. A focused single-locale extract usually fits easily; a giant master sheet may need Pro or a per-locale split.

An ICU value with many braces looks dense in the output, but it's exactly what you typed — escaped only where JSON requires. next-intl parses it at runtime. Don't hand-edit the braces out; that breaks pluralisation.

A value cell like 2.0 is read and written as the string "2.0" (values are always strings here). For next-intl message text that's correct — messages are strings, not numbers.

Blank rows used to visually separate HomePage from Dashboard in the sheet are skipped because their key is empty. They don't appear in the JSON, so your messages file stays clean.