feat!: Consolidate Metadata Transformation Options into descriptorFields (#2513)

Author: timofei-iatsenko

packages/babel-plugin-extract-messages/test/extract-messages.test.ts

@@ -47,7 +47,7 @@ const transformCode = (
         [
           linguiMacroPlugin,
           {
-            extract: true,
+            descriptorFields: "all",
           } satisfies LinguiPluginOpts,
         ],
         [plugin, pluginOpts],

packages/babel-plugin-lingui-macro/src/index.ts

@@ -1,33 +1,34 @@
-import type { PluginObj, Visitor, PluginPass } from "@babel/core"
+import type { PluginObj, PluginPass, Visitor } from "@babel/core"
 import type * as babelTypes from "@babel/types"
-import { Program, Identifier } from "@babel/types"
+import { Identifier, Program } from "@babel/types"
 import { MacroJSX } from "./macroJsx"
 import type { NodePath } from "@babel/traverse"
 import { MacroJs } from "./macroJs"
 import { JsMacroName } from "./constants"
 import {
-  type LinguiConfigNormalized,
   getConfig as loadConfig,
   LinguiConfig,
+  type LinguiConfigNormalized,
 } from "@lingui/conf"
+import { ResolvedDescriptorFields } from "./messageDescriptorUtils"
 
 let config: LinguiConfigNormalized
 
 export type LinguiPluginOpts = {
-  /*
-   * When set `true` all auxiliary data such as `comment`, `context`,
-   * and default message would be kept regardless of the current environment
-   *
-   * This flag explicitly set by Lingui CLI when running extraction process
-   */
-  extract?: boolean
   /**
-   * Setting `stripMessageField` to `true` will strip messages and comments from both development and production bundles.
-   * Alternatively, set it to `false` to keep the original messages in both environments.
+   * Controls which descriptor fields are preserved in the transformed code.
    *
-   * If not set value would be determined based on `process.env.NODE_ENV === "production"`
+   * - `"auto"` (default): In production (`NODE_ENV === "production"`), keeps only the `id`.
+   *    Otherwise, behaves like `"all"`.
+   * - `"all"`: Keeps every field: `id`, `message`, `context`, and `comment`.
+   *    Used by Lingui CLI during extraction.
+   * - `"id-only"`: Strips everything except the `id`. Most optimized for production.
+   * - `"message"`: Keeps `id`, `message`, and `context` (but not `comment`).
+   *    Use when you need runtime access to message and context.
+   *
+   * @default "auto"
    */
-  stripMessageField?: boolean
+  descriptorFields?: "auto" | "all" | "id-only" | "message"
 
   /**
    * Resolved and normalized Lingui Configuration
@@ -58,13 +59,45 @@ function reportUnsupportedSyntax(path: NodePath, e: Error) {
   throw codeFrameError
 }
 
-function shouldStripMessageProp(opts: LinguiPluginOpts) {
-  if (typeof opts.stripMessageField === "boolean") {
-    // if explicitly set in options, use it
-    return opts.stripMessageField
+const VALID_DESCRIPTOR_FIELDS = [
+  "auto",
+  "all",
+  "id-only",
+  "message",
+] as LinguiPluginOpts["descriptorFields"][]
+
+const REMOVED_OPTIONS: Record<string, string> = {
+  extract:
+    'Use `descriptorFields: "all"` instead of `extract: true` to preserve all fields during extraction.',
+  stripMessageField:
+    'Use `descriptorFields: "id-only"` instead of `stripMessageField: true`, ' +
+    'or `descriptorFields: "message"` to keep message and context.',
+}
+
+function resolveDescriptorFields(
+  opts: LinguiPluginOpts,
+): ResolvedDescriptorFields {
+  // introduced in v6, remove these hints in V7
+  for (const [key, hint] of Object.entries(REMOVED_OPTIONS)) {
+    if (key in (opts as Record<string, unknown>)) {
+      throw new Error(`[lingui] Option "${key}" has been removed. ${hint}`)
+    }
+  }
+
+  const mode = opts.descriptorFields ?? "auto"
+
+  if (!VALID_DESCRIPTOR_FIELDS.includes(mode)) {
+    throw new Error(
+      `[lingui] Invalid descriptorFields value: "${mode}". ` +
+        `Expected one of: ${VALID_DESCRIPTOR_FIELDS.join(", ")}.`,
+    )
+  }
+
+  if (mode !== "auto") {
+    return mode as ResolvedDescriptorFields
   }
-  // default to strip message in production if no explicit option is set and not during extract
-  return process.env.NODE_ENV === "production" && !opts.extract
+  // "auto": production → "id-only", otherwise → "all"
+  return process.env.NODE_ENV === "production" ? "id-only" : "all"
 }
 
 type LinguiSymbol = "Trans" | "useLingui" | "i18n"
@@ -236,10 +269,7 @@ export default function ({
                   { types: t },
                   {
                     transImportName: getSymbolIdentifier(state, "Trans").name,
-                    stripNonEssentialProps:
-                      process.env.NODE_ENV == "production" &&
-                      !(state.opts as LinguiPluginOpts).extract,
-                    stripMessageProp: shouldStripMessageProp(
+                    descriptorFields: resolveDescriptorFields(
                       state.opts as LinguiPluginOpts,
                     ),
                     isLinguiIdentifier: (node: Identifier, macro) =>
@@ -269,10 +299,7 @@ export default function ({
                 state: PluginPass,
               ) {
                 const macro = new MacroJs({
-                  stripNonEssentialProps:
-                    process.env.NODE_ENV == "production" &&
-                    !(state.opts as LinguiPluginOpts).extract,
-                  stripMessageProp: shouldStripMessageProp(
+                  descriptorFields: resolveDescriptorFields(
                     state.opts as LinguiPluginOpts,
                   ),
                   i18nImportName: getSymbolIdentifier(state, "i18n").name,

packages/babel-plugin-lingui-macro/src/macroJs.ts

@@ -13,7 +13,10 @@ import type { NodePath } from "@babel/traverse"
 
 import { Tokens } from "./icu"
 import { JsMacroName } from "./constants"
-import { createMessageDescriptorFromTokens } from "./messageDescriptorUtils"
+import {
+  createMessageDescriptorFromTokens,
+  ResolvedDescriptorFields,
+} from "./messageDescriptorUtils"
 import {
   isLinguiIdentifier,
   isDefineMessage,
@@ -28,8 +31,7 @@ export type MacroJsOpts = {
   i18nImportName: string
   useLinguiImportName: string
 
-  stripNonEssentialProps: boolean
-  stripMessageProp: boolean
+  descriptorFields: ResolvedDescriptorFields
   isLinguiIdentifier: (node: Identifier, macro: JsMacroName) => boolean
 }
 
@@ -49,8 +51,7 @@ export class MacroJs {
 
     this._ctx = createMacroJsContext(
       opts.isLinguiIdentifier,
-      opts.stripNonEssentialProps,
-      opts.stripMessageProp,
+      opts.descriptorFields,
     )
   }
 
@@ -63,8 +64,7 @@ export class MacroJs {
       createMessageDescriptorFromTokens(
         tokens,
         path.node.loc,
-        this._ctx.stripNonEssentialProps,
-        this._ctx.stripMessageProp,
+        this._ctx.descriptorFields,
       ),
       linguiInstance,
     )
@@ -94,8 +94,7 @@ export class MacroJs {
       return createMessageDescriptorFromTokens(
         tokens,
         path.node.loc,
-        ctx.stripNonEssentialProps,
-        ctx.stripMessageProp,
+        ctx.descriptorFields,
       )
     }
 
@@ -260,8 +259,7 @@ export class MacroJs {
 
         const _ctx = createMacroJsContext(
           ctx.isLinguiIdentifier,
-          ctx.stripNonEssentialProps,
-          ctx.stripMessageProp,
+          ctx.descriptorFields,
         )
 
         // { t } = useLingui()
@@ -272,8 +270,7 @@ export class MacroJs {
           const descriptor = createMessageDescriptorFromTokens(
             tokens,
             currentPath.node.loc,
-            _ctx.stripNonEssentialProps,
-            _ctx.stripMessageProp,
+            _ctx.descriptorFields,
           )
 
           const callExpr = t.callExpression(

packages/babel-plugin-lingui-macro/src/macroJsAst.test.ts

@@ -35,13 +35,9 @@ const parseExpression = (expression: string) => {
 }
 
 function createMacroCtx() {
-  return createMacroJsContext(
-    (identifier, macro) => {
-      return identifier.name === macro
-    },
-    false, // stripNonEssentialProps
-    false, // stripMessageProp
-  )
+  return createMacroJsContext((identifier, macro) => {
+    return identifier.name === macro
+  }, "all")
 }
 
 describe("js macro", () => {

packages/babel-plugin-lingui-macro/src/macroJsAst.ts

@@ -11,27 +11,27 @@ import {
 } from "@babel/types"
 import { JsMacroName, MsgDescriptorPropKey } from "./constants"
 import { ArgToken, TextToken, Token } from "./icu"
-import { createMessageDescriptorFromTokens } from "./messageDescriptorUtils"
+import {
+  createMessageDescriptorFromTokens,
+  ResolvedDescriptorFields,
+} from "./messageDescriptorUtils"
 import { makeCounter } from "./utils"
 
 export type MacroJsContext = {
   // Positional expressions counter (e.g. for placeholders `Hello {0}, today is {1}`)
   getExpressionIndex: () => number
-  stripNonEssentialProps: boolean
-  stripMessageProp: boolean
+  descriptorFields: ResolvedDescriptorFields
   isLinguiIdentifier: (node: Identifier, macro: JsMacroName) => boolean
 }
 
 export function createMacroJsContext(
   isLinguiIdentifier: MacroJsContext["isLinguiIdentifier"],
-  stripNonEssentialProps: boolean,
-  stripMessageProp: boolean,
+  descriptorFields: ResolvedDescriptorFields,
 ): MacroJsContext {
   return {
     getExpressionIndex: makeCounter(),
     isLinguiIdentifier,
-    stripNonEssentialProps,
-    stripMessageProp,
+    descriptorFields,
   }
 }
 
@@ -87,8 +87,7 @@ export function processDescriptor(
   return createMessageDescriptorFromTokens(
     tokens,
     descriptor.loc,
-    ctx.stripNonEssentialProps,
-    ctx.stripMessageProp,
+    ctx.descriptorFields,
     {
       id: idProperty,
       context: contextProperty,

packages/babel-plugin-lingui-macro/src/macroJsx.test.ts

@@ -38,8 +38,7 @@ function createMacro() {
   return new MacroJSX(
     { types },
     {
-      stripNonEssentialProps: false,
-      stripMessageProp: false,
+      descriptorFields: "all",
       transImportName: "Trans",
       isLinguiIdentifier: () => true,
     },

packages/babel-plugin-lingui-macro/src/macroJsx.ts

@@ -20,7 +20,10 @@ import { ArgToken, ElementToken, TextToken, Token } from "./icu"
 import { makeCounter } from "./utils"
 import { JsxMacroName, MsgDescriptorPropKey, JsMacroName } from "./constants"
 import cleanJSXElementLiteralChild from "./utils/cleanJSXElementLiteralChild"
-import { createMessageDescriptorFromTokens } from "./messageDescriptorUtils"
+import {
+  createMessageDescriptorFromTokens,
+  ResolvedDescriptorFields,
+} from "./messageDescriptorUtils"
 import {
   createMacroJsContext,
   MacroJsContext,
@@ -52,8 +55,7 @@ export type MacroJsxContext = MacroJsContext & {
 }
 
 export type MacroJsxOpts = {
-  stripNonEssentialProps: boolean
-  stripMessageProp: boolean
+  descriptorFields: ResolvedDescriptorFields
   transImportName: string
   isLinguiIdentifier: (node: Identifier, macro: JsMacroName) => boolean
 }
@@ -79,11 +81,7 @@ export class MacroJSX {
     this.types = types
 
     this.ctx = {
-      ...createMacroJsContext(
-        opts.isLinguiIdentifier,
-        opts.stripNonEssentialProps,
-        opts.stripMessageProp,
-      ),
+      ...createMacroJsContext(opts.isLinguiIdentifier, opts.descriptorFields),
       transImportName: opts.transImportName,
       elementIndex: makeCounter(),
     }
@@ -111,8 +109,7 @@ export class MacroJSX {
     const messageDescriptor = createMessageDescriptorFromTokens(
       tokens,
       path.node.loc,
-      this.ctx.stripNonEssentialProps,
-      this.ctx.stripMessageProp,
+      this.ctx.descriptorFields,
       {
         id,
         context,