feat(macro): Add arg macro tests, docs and typings

packages/babel-plugin-lingui-macro/test/__snapshots__/js-defineMessage.test.ts.snap

@@ -106,7 +106,7 @@ const message =
 `;
 
 exports[`should expand macros in message property 1`] = `
-import { defineMessage, plural, arg } from "@lingui/core/macro";
+import { defineMessage, plural } from "@lingui/core/macro";
 const message = defineMessage({
   comment: "Description",
   message: plural(value, { one: "book", other: "books" }),

packages/babel-plugin-lingui-macro/test/__snapshots__/js-plural.test.ts.snap

@@ -147,6 +147,31 @@ _i18n._(
 
 `;
 
+exports[`Macro with utility arg macro usage in options 1`] = `
+import { plural, arg } from "@lingui/core/macro";
+plural(count, {
+  one: \`# book on {\${arg(today)}, date}\`,
+  other: \`# books on {\${arg(today)}, date}\`,
+});
+
+↓ ↓ ↓ ↓ ↓ ↓
+
+import { i18n as _i18n } from "@lingui/core";
+_i18n._(
+  /*i18n*/
+  {
+    id: "lEIbMo",
+    message:
+      "{count, plural, one {# book on {today, date}} other {# books on {today, date}}}",
+    values: {
+      count: count,
+      today: today,
+    },
+  }
+);
+
+`;
+
 exports[`plural macro could be renamed 1`] = `
 import { plural as plural2 } from "@lingui/core/macro";
 const a = plural2(count, {

packages/babel-plugin-lingui-macro/test/__snapshots__/js-t.test.ts.snap

@@ -514,6 +514,26 @@ _i18n._(
 
 `;
 
+exports[`Variables with arg macro is not wrapped in curly brackets 1`] = `
+import { t, arg } from "@lingui/core/macro";
+t\`Number {\${arg(num)}, number, myNumberStyle}\`;
+
+↓ ↓ ↓ ↓ ↓ ↓
+
+import { i18n as _i18n } from "@lingui/core";
+_i18n._(
+  /*i18n*/
+  {
+    id: "6HvXd1",
+    message: "Number {num, number, myNumberStyle}",
+    values: {
+      num: num,
+    },
+  }
+);
+
+`;
+
 exports[`Variables with escaped double quotes are correctly formatted 1`] = `
 import { t } from "@lingui/core/macro";
 t\`Variable "name"\`;

packages/babel-plugin-lingui-macro/test/js-defineMessage.test.ts

@@ -21,7 +21,7 @@ macroTester({
     {
       name: "should expand macros in message property",
       code: `
-        import { defineMessage, plural, arg } from '@lingui/core/macro';
+        import { defineMessage, plural } from '@lingui/core/macro';
         const message = defineMessage({
           comment: "Description",
           message: plural(value, { one: "book", other: "books" })

packages/babel-plugin-lingui-macro/test/js-plural.test.ts

@@ -69,6 +69,17 @@ macroTester({
       `,
     },
 
+    {
+      name: "Macro with utility arg macro usage in options",
+      code: `
+        import { plural, arg } from '@lingui/core/macro';
+        plural(count, {
+          "one": \`# book on {\${arg(today)}, date}\`,
+          other: \`# books on {\${arg(today)}, date}\`
+        });
+      `,
+    },
+
     {
       useTypescriptPreset: true,
       name: "Macro with labeled expression with `as` expression",

packages/babel-plugin-lingui-macro/test/js-t.test.ts

@@ -109,6 +109,13 @@ macroTester({
         t\`Variable \${{name} as any}\`;
     `,
     },
+    {
+      name: "Variables with arg macro is not wrapped in curly brackets",
+      code: `
+        import { t, arg } from '@lingui/core/macro';
+        t\`Number {\${arg(num)}, number, myNumberStyle}\`;
+      `,
+    },
     {
       name: "Newlines are preserved",
       code: `

packages/core/macro/index.d.ts

@@ -233,3 +233,15 @@ export const msg: typeof defineMessage
  * Helps to define a name for a variable in the message
  */
 export function ph(def: LabeledExpression<string | number>): string
+
+/**
+ * Helps to inject a variable into the other macro usage without automatically wrapping it in curly brackets,
+ * so it can be used with custom formats.
+ *
+ * @example
+ * ```
+ * import { t, arg } from "@lingui/core/macro";
+ * t`Number {${arg(num)}, number, myNumberStyle}`;
+ * ```
+ */
+export function arg(def: string | number): string

website/docs/ref/macro.mdx

@@ -499,6 +499,35 @@ const message = /*i18n*/ {
 
 :::
 
+### `arg`
+
+The `arg` macro is a utility macro that helps to inject a message variables into the other macro usage without automatically wrapping them in curly brackets.
+
+```ts
+arg(value: string | number)
+```
+
+It can be used to apply custom formatting to a variable inside the other macro call. It is an escape hatch for writing message syntax using [ICU MessageFormat](/guides/message-format) on your own.
+
+```js
+import { t, arg } from "@lingui/core/macro";
+const message = t`Number {${arg(num)}, number, myNumberStyle}`;
+
+// ↓ ↓ ↓ ↓ ↓ ↓
+
+import { i18n } from "@lingui/core";
+
+const message = i18n._(
+  /*i18n*/ {
+    id: "6HvXd1",
+    message: "Number {num, number, myNumberStyle}",
+    values: { num },
+  }
+);
+```
+
+:::
+
 ## React Macros
 
 React (JSX) Macros are used in JSX elements and are transformed into the [`Trans`](/ref/react#trans) component imported from the [`@lingui/react`](/ref/react) package.