next-intl-utils

Split next-intl dictionaries into small index.json files and merge them back into locale files for development, type checking, and build-time consumption.

Why

Large translation files become hard to maintain when everything lives in a single en.json or vi.json.

This package lets you organize messages like this:

src/i18n/dictionaries/
  en/
    common/
      index.json
    home/
      index.json
  vi/
    common/
      index.json
    home/
      index.json

And generate merged locale files like:

src/i18n/dictionaries/
  en.json
  vi.json

Installation

npm install next-intl-utils next-intl

Folder structure

The package looks for files named index.json under each locale directory.

Example:

src/i18n/dictionaries/
  en/
    common/
      index.json
    auth/
      index.json
  vi/
    common/
      index.json
    auth/
      index.json

src/i18n/dictionaries/en/common/index.json

{
  "title": "Hello",
  "description": "Welcome back"
}

src/i18n/dictionaries/en/auth/index.json

{
  "signIn": "Sign in"
}

Merged output:

src/i18n/dictionaries/en.json

{
  "common": {
    "title": "Hello",
    "description": "Welcome back"
  },
  "auth": {
    "signIn": "Sign in"
  }
}

Quick start with Next.js

1. Add the plugin in next.config.ts

import createNextIntlSplitPlugin from "next-intl-utils/plugin";

const withNextIntl = createNextIntlSplitPlugin({
  dictionariesPath: "./src/i18n/dictionaries",
  i18nPathOrConfig: "./src/i18n/request.ts"
});

export default withNextIntl({});

What this does:

• Merges locale files once when Next starts.
• Watches your split index.json files in development.
• Regenerates merged locale files when translations change.

2. Load messages in your next-intl request config

import {getRequestConfig} from "next-intl/server";
import {loadI18nTranslations} from "next-intl-utils";

export default getRequestConfig(async ({locale}) => ({
  locale,
  messages: loadI18nTranslations(
    "./src/i18n/dictionaries",
    locale,
    process.env.NODE_ENV === "development"
  )
}));

enableTypeCheck is optional. When enabled, the package refreshes merged locale files during load so next-intl can keep type information aligned with your split dictionaries.

API

next-intl-utils

loadI18nTranslations(dictionariesPath, locale, enableTypeCheck?)

Loads a single locale as nested next-intl messages.

import {loadI18nTranslations} from "next-intl-utils";

const messages = loadI18nTranslations("./src/i18n/dictionaries", "en", true);

Arguments:

• dictionariesPath: path to the dictionaries folder.
• locale: locale key like "en" or "vi".
• enableTypeCheck: optional boolean to refresh merged locale files while loading.

loadMessages(dictionariesPath)

Loads all locales from a split dictionaries folder.

import {loadMessages} from "next-intl-utils";

const messages = loadMessages("./src/i18n/dictionaries");

next-intl-utils/plugin

createNextIntlSplitPlugin({dictionariesPath, i18nPathOrConfig})

Creates a next-intl plugin wrapper with automatic merging and file watching.

import createNextIntlSplitPlugin from "next-intl-utils/plugin";

Arguments:

• dictionariesPath: relative path to the split dictionaries folder.
• i18nPathOrConfig: same argument you would pass to next-intl/plugin.

next-intl-utils/merge

mergeMessages(pathToDictionaries)

Manually merges split dictionaries into top-level locale JSON files.

import {mergeMessages} from "next-intl-utils/merge";

mergeMessages("./src/i18n/dictionaries");

Important:

• This function expects a relative path starting with ./.

next-intl-utils/write

writeMessages(dictionariesPath, messages, options?)

Writes merged locale JSON files to disk.

import {writeMessages} from "next-intl-utils/write";

next-intl-utils/load

This entrypoint exports the same loading helpers:

• loadI18nTranslations
• loadMessages

Development behavior

The plugin is designed to be safe in Next.js development mode:

• Watches only split source files named index.json.
• Avoids rewriting locale files when content has not changed.
• Uses a singleton watcher to avoid duplicated watchers during Next reloads.
• Cleans up the watcher on process exit.

Notes

• mergeMessages requires a relative path such as ./src/i18n/dictionaries.
• The package merges based on folder names, so directory nesting becomes nested message keys.
• Generated files such as en.json and vi.json should usually be committed only if your workflow needs them in CI or production.

License

MIT