next-intl Plugin for Inlang

This plugin enables your inlang project to read and write next-intl translation files.

Why use this plugin?

If you're using next-intl for internationalization in Next.js, this plugin lets you:

• Manage translations with Fink – a translation editor for collaborating with translators
• Get inline previews with Sherlock – a VS Code extension that shows translations directly in your code
• Lint translations with inlang CLI – catch missing translations, unused keys, and other issues
• Automate workflows with the inlang SDK – build custom tooling around your translations

How it works

The plugin reads and writes next-intl JSON files, preserving your existing file structure (nested or flat keys). It also tells Sherlock how to detect t(), useTranslations(), and getTranslations() calls in your code.

Supported next-intl Features

| Feature | Status | Notes | | ---------------------- | ---------------- | --------------------------------------- | | Basic key-value pairs | ✅ Supported | Fully working | | Nested keys | ✅ Supported | Auto-detects flat vs nested structure | | Variable interpolation | ✅ Supported | {variable} with customizable patterns | | Rich text | ⚠️ Partial | Tags are treated as text | | Plurals (ICU) | ❌ Not supported | ICU message format not parsed | | Select (ICU) | ❌ Not supported | ICU message format not parsed |

Version Compatibility

• next-intl v3.x: Full support
• next-intl v2.x: Full support

Installation

• Add this to the modules in your project.inlang/settings.json
• Change the sourceLanguageTag if needed
• Include existing language tags in the languageTags array

{
	"sourceLanguageTag": "en",
	"languageTags": ["en", "de"],
	"modules": [
		"https://cdn.jsdelivr.net/npm/@inlang/plugin-next-intl@latest/dist/index.js"
	],
	"plugin.inlang.nextIntl": {
		"pathPattern": "./messages/{locale}.json"
	}
}

Settings

The plugin offers further configuration options that can be passed as arguments. The following settings exist:

type PluginSettings = {
	pathPattern: string | { [namespace: string]: string };
	variableReferencePattern?: [string] | [string, string];
	sourceLanguageFilePath?: string;
};

pathPattern

To use the plugin, you must provide a path to the directory where your language-specific files are stored. Use the dynamic path syntax {locale} to specify the locale name.

{languageTag} is still supported for legacy projects, but {locale} is recommended for new configurations.

"pathPattern": "./messages/{locale}.json"

Use an object when your next-intl messages are split by namespace. Namespace maps require tools that use the new importFiles and exportFiles API; the legacy loadMessages and saveMessages hooks only support a single string pathPattern.

"pathPattern": {
	"About": "./messages/{locale}/About.json",
	"HomePage": "./messages/HomePage/{locale}.json"
}

For example, ./messages/en/About.json with this content:

{
	"title": "About us"
}

is exposed as the message ID About.title, matching next-intl usage like:

const t = useTranslations("About");
t("title");

variableReferencePattern

Defines the pattern for variable references. The default matches next-intl's format.

"variableReferencePattern": ["{", "}"]

sourceLanguageFilePath

This setting is optional and should only be used if the file name of your sourceLanguageTag does not match your pathPattern structure. For example, if your sourceLanguageTag is en but your sourceLanguage file is called main.json, you can use this setting to specify the path to the sourceLanguage file. We recommend renaming the file to en.json and not using this setting.

"sourceLanguageFilePath": "./resources/main.json"

In-code usage

Basic usage:

t("key")

With namespaces:

import {useTranslations} from 'next-intl';

function About() {
  const t = useTranslations('About');
  return <h1>{t('title')}</h1>;
}

Server components with getTranslations:

import {getTranslations} from 'next-intl/server';

export default async function Page() {
  const t = await getTranslations('About');
  return <h1>{t('title')}</h1>;
}

To learn about namespaces and how to use translation functions in your code, refer to the next-intl documentation.

Expected behavior

Structure and Ordering

The source language file determines the structure for all other locale files:

• Key ordering: Messages are sorted in the order they appear in the source language file
• Nesting vs flat: Detected per-file from the source language. If your en.json uses nested keys, all other locales will use nested keys too
• New keys: When you add translations for other locales, they follow the source file's structure

Example

If your source language (en.json) looks like this:

{
	"About": {
		"title": "About us",
		"description": "Learn more about our company"
	}
}

Then your target language (de.json) will be written in the same nested structure:

{
	"About": {
		"title": "Über uns",
		"description": "Erfahren Sie mehr über unser Unternehmen"
	}
}

Limitations

The following next-intl features are not supported by this plugin:

| Feature | Limitation | | ------------------------ | ------------------------------------------------------- | | ICU message format | Plurals, select, and other ICU syntax are not parsed | | Rich text formatting | Tags like <bold>text</bold> are treated as plain text | | Nested t() calls | References like {t('other.key')} are not resolved |

Troubleshooting

Keys appear duplicated or out of order

Cause: The source language file structure doesn't match what the plugin expects.

Solution:

1. Ensure your source language file (e.g., en.json) is valid JSON
2. Check that the file structure is consistent (all nested or all flat)
3. The source language file is the "source of truth" for key ordering

Sherlock not detecting translation keys

Cause: Non-standard function names or unsupported file types.

Solution:

• Use standard function calls: t("key"), useTranslations(), or getTranslations()
• Supported file types: .ts, .tsx, .js, .jsx

Changes not appearing in target language files

Cause: Target files don't exist or path pattern is incorrect.

Solution:

1. Verify your pathPattern matches your file structure
2. Check that the {locale} or legacy {languageTag} placeholder is in the correct position
3. Directories are created automatically, but the language tag must be in your languageTags array

Contributing

Getting started

Run the following commands in your terminal (node and npm must be installed):

1. npm install
2. npm run dev

npm run dev will start the development environment, which automatically compiles the src/index.ts files to JavaScript (dist/index.js), runs tests defined in *.test.ts files and watches changes.