fix: Deprecate toJSONString (no longer needed) (#2350)

Co-authored-by: Claude <noreply@anthropic.com>

Author: amannn

docs/src/pages/docs/usage/plugin.mdx

@@ -261,10 +261,6 @@ export default defineCodec(() => ({
 
   encode(messages, context) {
     // ...
-  },
-
-  toJSONString(content, context) {
-    // ...
   }
 }));
 ```

packages/next-intl/src/extractor/format/ExtractorCodec.tsx

@@ -26,18 +26,11 @@ export default interface ExtractorCodec {
   ): string;
 
   /**
-   * Turns the content of a file into a JSON string that represents extracted
-   * messages. The returned value will be passed to `JSON.parse`.
-   *
-   * @return E.g. `[{"id":"-YJVTi","message":"Hey!"}]`
-   *
-   * This is used when loading messages into your application, typically via a
-   * dynamic import (e.g. `import(`../messages/${locale}.json`)`).
-   *
-   * If your file content is JSON and should be used as-is, you can set this to
-   * an identity function.
+   * @deprecated No longer used. Catalogs are loaded into your application via
+   * `decode`, so you can remove `toJSONString` from your codec. Providing it
+   * logs a deprecation warning and has no effect.
    */
-  toJSONString(content: string, context: ExtractorCodecContext): string;
+  toJSONString?(content: string, context: ExtractorCodecContext): string;
 }
 
 export function defineCodec(factory: () => ExtractorCodec) {

packages/next-intl/src/extractor/format/codecs/JSONCodec.tsx

@@ -28,10 +28,6 @@ export default defineCodec(() => ({
       setNestedProperty(root, message.id, message.message);
     }
     return JSON.stringify(root, null, 2) + '\n';
-  },
-
-  toJSONString(source) {
-    return source;
   }
 }));
 

packages/next-intl/src/extractor/format/codecs/POCodec.tsx

@@ -1,5 +1,5 @@
 import POParser from 'po-parser';
-import {getSortedMessages, setNestedProperty} from '../../utils.js';
+import {getSortedMessages} from '../../utils.js';
 import {defineCodec} from '../ExtractorCodec.js';
 
 export default defineCodec(() => {
@@ -77,15 +77,6 @@ export default defineCodec(() => {
         },
         messages: encodedMessages
       });
-    },
-
-    toJSONString(source, context) {
-      const parsed = this.decode(source, context);
-      const messagesObject = {};
-      for (const message of parsed) {
-        setNestedProperty(messagesObject, message.id, message.message);
-      }
-      return JSON.stringify(messagesObject);
     }
   };
 });

packages/next-intl/src/extractor/format/codecs/fixtures/JSONCodecStructured.tsx

@@ -25,15 +25,5 @@ export default defineCodec(() => ({
       };
     }
     return JSON.stringify(obj, null, 2) + '\n';
-  },
-
-  toJSONString(content) {
-    const data = JSON.parse(content);
-    const result: Record<string, string> = {};
-    for (const [id, value] of Object.entries(data)) {
-      const obj = value as StoredMessage;
-      result[id] = obj.message;
-    }
-    return JSON.stringify(result);
   }
 }));

packages/next-intl/src/extractor/format/codecs/fixtures/POCodecSourceMessageKey.tsx

@@ -1,5 +1,5 @@
 import POParser from 'po-parser';
-import {getSortedMessages, setNestedProperty} from '../../../utils.js';
+import {getSortedMessages} from '../../../utils.js';
 import {defineCodec} from '../../ExtractorCodec.js';
 
 export default defineCodec(() => {
@@ -81,15 +81,6 @@ export default defineCodec(() => {
         },
         messages: encodedMessages
       });
-    },
-
-    toJSONString(source, context) {
-      const parsed = this.decode(source, context);
-      const messagesObject = {};
-      for (const message of parsed) {
-        setNestedProperty(messagesObject, message.id, message.message);
-      }
-      return JSON.stringify(messagesObject);
     }
   };
 });

packages/next-intl/src/plugin/catalog/catalogLoader.tsx

@@ -16,6 +16,8 @@ import type {TurbopackLoaderContext} from '../types.js';
 // create multiple loader instances so don't expect a singleton.
 let cachedCodec: ExtractorCodec | null = null;
 
+let hasWarnedAboutToJSONString = false;
+
 type CompiledMessageCacheEntry = {
   compiledMessage: unknown;
   messageValue: string;
@@ -62,26 +64,66 @@ export default function catalogLoader(
 
   getCodec(options, this.rootContext)
     .then((codec) => {
+      warnIfToJSONStringProvided(codec);
+
       const locale = path.basename(this.resourcePath, extension);
-      let outputString: string;
+      const decoded = codec.decode(source, {locale});
 
+      let messages: Record<string, unknown>;
       if (options.messages.precompile) {
-        const decoded = codec.decode(source, {locale});
         const cache = getMessageCache(this.resourcePath);
-        const precompiled = precompileMessages(decoded, cache);
-        outputString = JSON.stringify(precompiled);
+        messages = precompileMessages(decoded, cache);
       } else {
-        outputString = codec.toJSONString(source, {locale});
+        messages = buildMessages(decoded);
       }
 
       // https://v8.dev/blog/cost-of-javascript-2019#json
-      const result = `export default JSON.parse(${JSON.stringify(outputString)});`;
+      const result = `export default JSON.parse(${JSON.stringify(JSON.stringify(messages))});`;
 
       callback(null, result);
     })
     .catch(callback);
 }
 
+function warnIfToJSONStringProvided(codec: ExtractorCodec) {
+  if (hasWarnedAboutToJSONString || !codec.toJSONString) return;
+  hasWarnedAboutToJSONString = true;
+  console.warn(
+    '`toJSONString` is deprecated and no longer needed, please remove it.'
+  );
+}
+
+/**
+ * Builds a nested messages object from decoded messages, mirroring the shape
+ * produced by `precompileMessages` but keeping the raw message strings.
+ */
+function buildMessages(
+  messages: Array<ExtractorMessage>
+): Record<string, unknown> {
+  const result = Object.create(null) as Record<string, unknown>;
+  for (const message of messages) {
+    assertStringMessage(message);
+    setNestedProperty(result, message.id, message.message);
+  }
+  return result;
+}
+
+function assertStringMessage(message: ExtractorMessage) {
+  const messageValue = message.message;
+
+  if (Array.isArray(messageValue)) {
+    throw new Error(
+      `Message at \`${message.id}\` resolved to an array, but only strings are supported. See https://next-intl.dev/docs/usage/translations#arrays-of-messages`
+    );
+  }
+
+  if (typeof messageValue === 'object') {
+    throw new Error(
+      `Message at \`${message.id}\` resolved to \`${typeof messageValue}\`, but only strings are supported. Use a \`.\` to retrieve nested messages. See https://next-intl.dev/docs/usage/translations#structuring-messages`
+    );
+  }
+}
+
 /**
  * Recursively precompiles all ICU message strings in a messages object
  * using icu-minify/compile for smaller runtime bundles.
@@ -95,20 +137,9 @@ function precompileMessages(
 
   for (const message of messages) {
     cacheKeysToEvict.delete(message.id);
+    assertStringMessage(message);
     const messageValue = message.message;
 
-    if (Array.isArray(messageValue)) {
-      throw new Error(
-        `Message at \`${message.id}\` resolved to an array, but only strings are supported. See https://next-intl.dev/docs/usage/translations#arrays-of-messages`
-      );
-    }
-
-    if (typeof messageValue === 'object') {
-      throw new Error(
-        `Message at \`${message.id}\` resolved to \`${typeof messageValue}\`, but only strings are supported. Use a \`.\` to retrieve nested messages. See https://next-intl.dev/docs/usage/translations#structuring-messages`
-      );
-    }
-
     const cachedEntry = cache.get(message.id);
     const hasCacheMatch = cachedEntry?.messageValue === messageValue;