intl-watcher

🌐 intl-watcher plugin for Next.js

Automatically scans your Next.js project's source files to manage internationalization (i18n) translation keys. It keeps your translation dictionaries up-to-date by extracting new keys, removing unused ones, and optionally partitioning keys into separate client and server dictionaries.

[!NOTE] Primarily designed for use with next-intl, this plugin can technically be adapted for other i18n libraries or frameworks that share a similar dictionary structure and access pattern in code.

Features

• Automatic Extraction: Scans your project's source code for i18n keys.
• Namespace Support: Handles nested i18n keys organized into namespaces for structured translations.
• Dictionary Syncing: Automatically updates JSON dictionaries with new translation keys.
• Unused Keys Handling: Warns or removes unused keys.
• Client/Server Partitioning: Separates translation keys into client-side and server-side bundles.
• Debounced Scanning: Efficiently handles rapid file changes.

Installation

Install the package via npm, yarn or pnpm:

npm install intl-watcher
# or
yarn add intl-watcher
# or
pnpm add intl-watcher

Usage

Wrap your Next.js configuration with the provided createIntlWatcher function:

// next.config.ts
import { createIntlWatcher } from 'intl-watcher'

const withIntlWatcher = createIntlWatcher({
	dictionaryPaths: ['./i18n/en.json', './i18n/de.json'],
})

export default withIntlWatcher({
	reactStrictMode: true,
	// other Next.js config options...
})

Configuration Options

Required Options

dictionaryPaths

• Type: string[]
• Description: Paths to JSON dictionary files for each language. These files will be managed and kept in sync with your source.

Shared Optional Options

defaultValue

• Type: (key: string) => string
• Default:

  (key) => `[NYT: ${key}]`

• Description: Function that generates a default translation for new keys.

removeUnusedKeys

• Type: boolean
• Default: false
• Description: When true, removes keys no longer found in source files; otherwise emits warnings.

scanDelay

• Type: number
• Default: 500
• Description: Delay in milliseconds before re‑scanning after file changes.

sourceDirectory

• Type: string
• Default: './src'
• Description: Directory path to scan for translation key extraction.

tsConfigFilePath

• Type: string
• Default: tsconfig.json
• Description: Path to tsconfig.json for project file resolution.

Non-Partitioning Mode (default)

applyPartitioning

• Type: false
• Default: false
• Description: Default mode where keys are not split.

translationFunctions

• Type: string[]
• Default: ['useTranslations', 'getTranslations']
• Description: Translation function name(s) to scan for keys.

Partitioning Mode

applyPartitioning

• Type: true
• Description: Enables splitting translation keys into separate client and server bundles.

partitioningOptions

• Type: { clientFunction?: string; serverFunction?: string }
• Default:

  {
    clientFunction: 'useTranslations',
    serverFunction: 'getTranslations'
  }

• Description: Function names to use for extracting client vs server translation keys.

Dictionary Partitioning

When applyPartitioning is enabled, the plugin generates separate dictionaries for client and server bundles. For example:

locales/
├── en.json
├── en.client.json
└── en.server.json

This enables optimized bundle sizes and clearer separation of translations by environment.

Development

See .github/CONTRIBUTING.md, then .github/DEVELOPMENT.md. Thanks! 💖

Contributors

Christian Ivicevic 💻 🖋 📖 🤔 🚇 🚧 📆 🔧