feat: clarify the order by messageId in v4 and support order by message

packages/cli/src/api/catalog.test.ts

@@ -553,6 +553,46 @@ describe("order", () => {
     // Jest snapshot order the keys automatically, so test that the key order explicitly
     expect(Object.keys(orderedCatalogs)).toMatchSnapshot()
   })
+
+  it("should order messages by message", () => {
+    const catalog = {
+      msg1: makeNextMessage({
+        message: "B",
+        translation: "B",
+        origin: [
+          ["file2.js", 2],
+          ["file1.js", 2],
+        ],
+      }),
+      msg2: makeNextMessage({
+        // message is optional.
+        translation: "A",
+        origin: [["file2.js", 3]],
+      }),
+      msg3: makeNextMessage({
+        message: "D",
+        translation: "D",
+        origin: [["file2.js", 100]],
+      }),
+      msg4: makeNextMessage({
+        message: "C",
+        translation: "C",
+        origin: [["file1.js", 1]],
+      }),
+    }
+
+    const orderedCatalogs = order("message")(catalog)
+
+    // Jest snapshot order the keys automatically, so test that the key order explicitly
+    expect(Object.keys(orderedCatalogs)).toMatchInlineSnapshot(`
+      [
+        msg2,
+        msg1,
+        msg4,
+        msg3,
+      ]
+    `)
+  })
 })
 
 describe("writeCompiled", () => {

packages/cli/src/api/catalog.ts

@@ -290,6 +290,7 @@ export function order<T extends ExtractedCatalogType>(
 ): (catalog: T) => T {
   return {
     messageId: orderByMessageId,
+    message: orderByMessage,
     origin: orderByOrigin,
   }[by]
 }
@@ -337,3 +338,16 @@ export function orderByOrigin<T extends ExtractedCatalogType>(messages: T): T {
       return acc
     }, {} as T)
 }
+
+export function orderByMessage<T extends ExtractedCatalogType>(messages: T): T {
+  return Object.keys(messages)
+    .sort((a, b) => {
+      const aMsg = messages[a].message || ""
+      const bMsg = messages[b].message || ""
+      return aMsg.localeCompare(bMsg)
+    })
+    .reduce((acc, key) => {
+      ;(acc as any)[key] = messages[key]
+      return acc
+    }, {} as T)
+}

packages/conf/src/types.ts

@@ -37,7 +37,7 @@ export type CatalogFormatOptions = {
   disableSelectWarning?: boolean
 }
 
-export type OrderBy = "messageId" | "origin"
+export type OrderBy = "messageId" | "message" | "origin"
 
 export type CatalogConfig = {
   name?: string

website/docs/ref/conf.md

@@ -369,7 +369,11 @@ Order of messages in catalog:
 
 #### messageId
 
-Sort by the message ID.
+Sort by the message ID, `js-lingui-id` will be used if no custom id provided.
+
+#### message
+
+Sort by source message.
 
 #### origin