amannn · amannn · Dec 12, 2025 · Nov 26, 2024 · Jan 21, 2025 · Feb 17, 2025
diff --git a/.github/workflows/prerelease-canary.yml b/.github/workflows/prerelease-canary.yml
@@ -16,10 +16,9 @@ jobs:
       - uses: pnpm/action-setup@v4
       - uses: actions/setup-node@v4
         with:
-          registry-url: "https://registry.npmjs.org"
-          node-version: 20.x
           cache: "pnpm"
-      - run: npm install -g npm@latest # Trusted publishers
+          node-version: 20.x
+          registry-url: "https://registry.npmjs.org"
       - run: pnpm install
       - run: pnpm turbo run build --filter './packages/**'
       - run: |

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -16,9 +16,9 @@ jobs:
       - uses: pnpm/action-setup@v4
       - uses: actions/setup-node@v4
         with:
-          registry-url: 'https://registry.npmjs.org'
+          cache: "pnpm"
           node-version: 20.x
-          cache: 'pnpm'
+          registry-url: "https://registry.npmjs.org"
       - run: npm install -g npm@latest # Trusted publishers
       - run: pnpm install
       - run: |
@@ -28,5 +28,4 @@ jobs:
         if: "${{startsWith(github.event.head_commit.message, 'fix: ') || startsWith(github.event.head_commit.message, 'feat: ') || startsWith(github.event.head_commit.message, 'feat!: ')}}"
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
-          NPM_CONFIG_PROVENANCE: true
+          # No NODE_AUTH_TOKEN since we use Trusted Publishers
diff --git a/docs/src/pages/docs/usage/configuration.mdx b/docs/src/pages/docs/usage/configuration.mdx
@@ -1,4 +1,3 @@
-import PartnerContentLink from '@/components/PartnerContentLink';
 import Callout from '@/components/Callout';
 import {Tabs} from 'nextra/components';
 import Details from '@/components/Details';

diff --git a/docs/src/pages/docs/usage/extraction.mdx b/docs/src/pages/docs/usage/extraction.mdx
@@ -2,7 +2,7 @@ import Image from 'next/image';
 import Callout from '@/components/Callout';
 import Details from '@/components/Details';
 
-# `useExtracted`
+# `useExtracted` (experimental)
 
 As an alternative to managing namespaces and keys manually, `next-intl` provides an additional API that works similar to [`useTranslations`](/docs/usage/translations) but automatically extracts messages from your source files.
 
@@ -48,7 +48,7 @@ function InlineMessages() {
 
 **Links:**
 
-- [Blog post](/blog/use-extracted)
+- [Introduction blog post](/blog/use-extracted)
 - [Example app](/examples#app-router-extracted)
 
 ## Getting started
@@ -73,7 +73,7 @@ const withNextIntl = createNextIntlPlugin({
       // Relative path to the directory
       path: './messages',
 
-      // Either 'json' or 'po'
+      // Either 'json', 'po', or a custom format (see below)
       format: 'json',
 
       // Either 'infer' to automatically detect locales based on
@@ -268,11 +268,11 @@ it('renders', () => {
 });
 ```
 
-## Formatters
+## Formats [#formats]
 
-Currently, messages can be extracted as either JSON or PO files. Support for custom formatters is planned for a future release.
+Messages can be extracted as JSON, PO, or with custom file formats.
 
-When [`messages`](/docs/usage/plugin#messages) is configured, this will also set up a Turbo- or Webpack loader that will ensure loaded messages can be imported as plain JavaScript objects.
+When [`messages`](/docs/usage/plugin#messages) is configured, this will also set up a Turbo- or Webpack loader that will ensure imported messages can be used as plain JavaScript objects.
 
 For example, when using `format: 'po'`, messages can be imported as:
 
@@ -283,14 +283,14 @@ import {getRequestConfig} from 'next-intl/server';
 export default getRequestConfig(async () => {
   const locale = 'en';
 
-  // E.g. `{"NhX4DJ": "Hello"}`
+  // E.g. `[{"NhX4DJ": "Hello"}]`
   const messages = (await import(`../../messages/${locale}.po`)).default;
 
   // ...
 });
 ```
 
-### JSON formatter [#formatters-json]
+### JSON format [#formats-json]
 
 When using this option, your messages will look like this:
 
@@ -300,7 +300,7 @@ When using this option, your messages will look like this:
 }
 ```
 
-Note that JSON files can only hold pairs of keys and values. To provide more context about a message like file references and descriptions, it's therefore recommended to use [PO files](#po) instead. Another alternative will be to use a custom JSON formatter in the future.
+Note that JSON files can only hold pairs of keys and values. To provide more context about a message like file references and descriptions, it's therefore recommended to use [PO files](#formats-po) instead. Alternatively, you can create a [custom format](#formats-custom) to store additional metadata.
 
 For local editing of JSON messages, you can use e.g. a [VSCode integration](/docs/workflows/vscode-integration) like i18n Ally:
 
@@ -318,7 +318,7 @@ For local editing of JSON messages, you can use e.g. a [VSCode integration](/doc
 
 </Callout>
 
-### PO formatter [#formatters-po]
+### PO format [#formats-po]
 
 When using this option, your messages will look like this:
 
@@ -331,10 +331,58 @@ msgstr "Right"
 
 Besides the message key and the label itself, this format also supports optional descriptions and file references to all modules that consume this message.
 
-For local editing of PO messages, you can use e.g. a tool like [Poedit](https://poedit.net/) (replacing keys with source text requires a pro license).
+For local editing of .po files, you can use e.g. a tool like [Poedit](https://poedit.net/) (note however that replacing keys with source text requires a pro license).
 
 <Callout>
 
 **Tip:** AI-based translation can be automated with a translation management system like [Crowdin](/docs/workflows/localization-management).
 
 </Callout>
+
+### Custom format [#formats-custom]
+
+To configure a custom format, you need to specify a codec along with an extension.
+
+The codec can be created via `defineCodec` from `next-intl/extractor`:
+
+```tsx filename="./CustomCodec.ts"
+import {defineCodec} from 'next-intl/extractor';
+
+export default defineCodec(() => ({
+  decode(content, context) {
+    // ...
+  },
+
+  encode(messages, context) {
+    // ...
+  },
+
+  toJSONString(content, context) {
+    // ...
+  }
+}));
+```
+
+Then, reference it in your configuration along with an `extension`:
+
+```tsx filename="next.config.ts"
+const withNextIntl = createNextIntlPlugin({
+  experimental: {
+    messages: {
+      format: {
+        codec: './CustomCodec.ts',
+        extension: '.json'
+      }
+      // ...
+    }
+  }
+});
+```
+
+See also the built-in [`codecs`](https://github.com/amannn/next-intl/tree/main/packages/next-intl/src/extractor/format/codecs) for inspiration.
+
+<Callout>
+
+Node.js supports native TypeScript execution like it's needed for the example above starting with v22.18. If you're on an older version, you should define your codec as a JavaScript file.
+
+</Callout>
diff --git a/docs/src/pages/docs/usage/plugin.mdx b/docs/src/pages/docs/usage/plugin.mdx
@@ -93,7 +93,7 @@ const withNextIntl = createNextIntlPlugin({
       // Automatically detects locales based on `path`
       locales: 'infer',
 
-      // Either 'json' or 'po'
+      // Either 'json', 'po', or a custom format
       format: 'json'
     }
     // ...
@@ -107,7 +107,7 @@ If you want to specify the locales explicitly, you can provide an array for `loc
 locales: ['en', 'de'];
 ```
 
-Configuring `experimental.messages` will also set up a Turbo- or Webpack loader that will ensure loaded messages can be imported as plain JavaScript objects (see [formatters](/docs/usage/extraction#formatters)).
+Configuring `experimental.messages` will also set up a Turbo- or Webpack loader that will ensure loaded messages can be imported as plain JavaScript objects (see [formats](/docs/usage/extraction#formats)).
 
 **Note:** The `messages` option should be used together with [`extract`](#extract) and [`srcPath`](#src-path).
 

diff --git a/examples/example-app-router-extracted/src/app/Counter.tsx b/examples/example-app-router-extracted/src/app/Counter.tsx
@@ -3,7 +3,7 @@
 import {useExtracted} from 'next-intl';
 import {useState} from 'react';
 
-export default function Client() {
+export default function Counter() {
   const [count, setCount] = useState(1000);
   const t = useExtracted();
 

diff --git a/examples/example-app-router-mixed-routing/playwright.config.ts b/examples/example-app-router-mixed-routing/playwright.config.ts
@@ -1,12 +1,11 @@
-/* eslint-disable import/no-extraneous-dependencies */
 import type {PlaywrightTestConfig} from '@playwright/test';
 import {devices} from '@playwright/test';
 
 // Use a distinct port on CI to avoid conflicts during concurrent tests
 const PORT = process.env.CI ? 3002 : 3000;
 
 const config: PlaywrightTestConfig = {
-  retries: process.env.CI ? 1 : 0,
+  retries: process.env.CI ? 2 : 0,
   testDir: './tests',
   projects: [
     {

diff --git a/examples/example-app-router-next-auth/playwright.config.ts b/examples/example-app-router-next-auth/playwright.config.ts
@@ -6,7 +6,7 @@ import {devices} from '@playwright/test';
 const PORT = process.env.CI ? 3003 : 3000;
 
 const config: PlaywrightTestConfig = {
-  retries: process.env.CI ? 1 : 0,
+  retries: process.env.CI ? 2 : 0,
   testDir: './tests',
   projects: [
     {

diff --git a/examples/example-app-router-playground/playwright.config.ts b/examples/example-app-router-playground/playwright.config.ts
@@ -9,7 +9,7 @@ const PORT = process.env.CI ? 3004 : 3000;
 process.env.PORT = PORT.toString();
 
 const config: PlaywrightTestConfig = {
-  retries: process.env.CI ? 1 : 0,
+  retries: process.env.CI ? 2 : 0,
   testMatch: process.env.TEST_MATCH || 'main.spec.ts',
   testDir: './tests',
   projects: [

diff --git a/examples/example-app-router-single-locale/playwright.config.ts b/examples/example-app-router-single-locale/playwright.config.ts
@@ -6,7 +6,7 @@ import {devices} from '@playwright/test';
 const PORT = process.env.CI ? 3005 : 3000;
 
 const config: PlaywrightTestConfig = {
-  retries: process.env.CI ? 1 : 0,
+  retries: process.env.CI ? 2 : 0,
   testDir: './tests',
   projects: [
     {

diff --git a/examples/example-app-router-without-i18n-routing/playwright.config.ts b/examples/example-app-router-without-i18n-routing/playwright.config.ts
@@ -6,7 +6,7 @@ import {devices} from '@playwright/test';
 const PORT = process.env.CI ? 3006 : 3000;
 
 const config: PlaywrightTestConfig = {
-  retries: process.env.CI ? 1 : 0,
+  retries: process.env.CI ? 2 : 0,
   testDir: './tests',
   projects: [
     {

diff --git a/examples/example-app-router/playwright.config.ts b/examples/example-app-router/playwright.config.ts
@@ -6,7 +6,7 @@ import {devices} from '@playwright/test';
 const PORT = process.env.CI ? 3001 : 3000;
 
 const config: PlaywrightTestConfig = {
-  retries: process.env.CI ? 1 : 0,
+  retries: process.env.CI ? 2 : 0,
   testDir: './tests',
   projects: [
     {

diff --git a/package.json b/package.json
@@ -6,9 +6,9 @@
     "build-packages": "turbo run build --filter './packages/**' --filter '!./packages/swc-plugin-extractor'"
   },
   "devDependencies": {
-    "@lerna-lite/cli": "3.9.0",
-    "@lerna-lite/publish": "3.9.0",
-    "conventional-changelog-conventionalcommits": "7.0.2",
+    "@lerna-lite/cli": "^4.9.4",
+    "@lerna-lite/publish": "^4.9.4",
+    "conventional-changelog-conventionalcommits": "^8.0.0",
     "turbo": "^2.4.4"
   },
   "pnpm": {

diff --git a/packages/next-intl/package.json b/packages/next-intl/package.json
@@ -125,10 +125,11 @@
   ],
   "dependencies": {
     "@formatjs/intl-localematcher": "^0.5.4",
+    "@parcel/watcher": "^2.4.1",
     "@swc/core": "^1.15.2",
     "negotiator": "^1.0.0",
     "next-intl-swc-plugin-extractor": "workspace:^",
-    "po-parser": "^1.0.2",
+    "po-parser": "^2.0.0",
     "use-intl": "workspace:^"
   },
   "peerDependencies": {

diff --git a/packages/next-intl/rollup.config.js b/packages/next-intl/rollup.config.js
@@ -73,7 +73,8 @@ export default [
     output: {
       dir: 'dist/cjs/development',
       format: 'cjs',
-      entryFileNames: '[name].cjs'
+      entryFileNames: '[name].cjs',
+      chunkFileNames: '[name]-[hash].cjs'
     }
   })
 ];