https://github.com/christianivicevic/intl-watcher
Automated translation key extraction and dictionary management plugin for Next.js
https://github.com/christianivicevic/intl-watcher
i18n internationalization intl localization next nextjs react translate translation
Last synced: about 1 month ago
JSON representation
Automated translation key extraction and dictionary management plugin for Next.js
- Host: GitHub
- URL: https://github.com/christianivicevic/intl-watcher
- Owner: ChristianIvicevic
- License: mit
- Created: 2025-03-27T15:43:15.000Z (about 2 months ago)
- Default Branch: main
- Last Pushed: 2025-04-04T12:54:51.000Z (about 1 month ago)
- Last Synced: 2025-04-04T13:40:42.409Z (about 1 month ago)
- Topics: i18n, internationalization, intl, localization, next, nextjs, react, translate, translation
- Language: TypeScript
- Homepage:
- Size: 8.62 MB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: .github/CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE.md
- Code of conduct: .github/CODE_OF_CONDUCT.md
- Security: .github/SECURITY.md
Awesome Lists containing this project
README
🌐 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.
## Features
- **Automatic Extraction**: Scans your project's source code for i18n keys.
- **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:
```bash
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:
```ts
// next.config.ts
import { createIntlWatcher } from 'intl-watcher'
const withIntlWatcher = createIntlWatcher({
i18nDictionaryPaths: ['./locales/en.json'],
applyPartitioning: true,
debounceDelay: 500,
defaultTranslationGeneratorFn: (key) => `[NYT: ${key}]`,
partitioningOptions: {
clientFunction: 'useTranslations',
serverFunction: 'getTranslations',
},
removeUnusedKeys: true,
sourceDirectory: './src'
})
export default withIntlWatcher({
reactStrictMode: true,
// other Next.js config options...
})
```
## Configuration Options
### Required Options
#### `i18nDictionaryPaths`
- **Type:** `string[]`
- **Description:** Paths to JSON dictionary files to manage.
### Optional Options
#### `applyPartitioning`
- **Type**: `boolean`
- **Default**: `false`
- **Description**: Enables splitting of translation keys into separate client/server dictionaries.
#### `debounceDelay`
- **Type:** `number`
- **Default:** `500`
- **Description:** Delay (ms) for debouncing scans after file changes.
#### `defaultTranslationGeneratorFn`
- **Type**: `(key: string) => string`
- **Default**:
```js
(key) => `[NYT: ${key}]`
```
- **Description**: Function to generate default values for new translation keys.
#### `partitioningOptions`
- **Type:** `{ clientFunction?: string; serverFunction?: string }`
- **Default:**
```json5
{
clientFunction: 'useTranslations',
serverFunction: 'getTranslations'
}
```
- **Description**: Identifiers to distinguish client/server translation functions.
#### `removeUnusedKeys`
- **Type**: `boolean`
- **Default**: `false`
- **Description**: Removes unused translation keys if true; otherwise, logs a warning.
#### `sourceDirectory`
- **Type:** `string`
- **Default:** `'./src'`
- **Description:** Directory to scan for translation keys.
#### `tsConfigFilePath`
- **Type**: `string`
- **Default**: `tsconfig.json`
- **Description**: Path to the tsconfig file to resolve file scanning criteria.
## 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`](./.github/CONTRIBUTING.md), then [`.github/DEVELOPMENT.md`](./.github/DEVELOPMENT.md).
Thanks! 💖
## Contributors
