feat: Custom formats for useExtracted, consistency fixes for file references, pruning of messages and sorting of keys (#2155)

Co-authored-by: Cursor Agent <cursoragent@cursor.com>

Author: amannn

.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: |

.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

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';

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>

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).
 

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();
 

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: [
     {

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: [
     {

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: [

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: [
     {