feat(macro): add useLingui macro (#1859)

Co-authored-by: ddyo <danrosenshain@gmail.com>

packages/babel-plugin-extract-messages/test/__snapshots__/index.ts.snap

@@ -287,6 +287,26 @@ exports[`@lingui/babel-plugin-extract-messages should extract all messages from
       48,
     ],
   },
+  {
+    comment: undefined,
+    context: undefined,
+    id: VO4BJY,
+    message: [useLingui]: TplLiteral,
+    origin: [
+      js-with-macros.js,
+      53,
+    ],
+  },
+  {
+    comment: undefined,
+    context: undefined,
+    id: ZxxjOE,
+    message: [useLingui]: Text {0, plural, offset:1 =0 {No books} =1 {1 book} other {# books}},
+    origin: [
+      js-with-macros.js,
+      56,
+    ],
+  },
 ]
 `;
 

packages/babel-plugin-extract-messages/test/fixtures/js-with-macros.js

@@ -1,4 +1,4 @@
-import { t, defineMessage, msg } from "@lingui/macro"
+import { t, defineMessage, msg, useLingui } from "@lingui/macro"
 
 t`Message`
 
@@ -46,3 +46,17 @@ const defineMessageAlias = msg({
 })
 
 const defineMessageAlias2 = msg`TplLiteral`
+
+function MyComponent() {
+  const { t } = useLingui()
+
+  t`[useLingui]: TplLiteral`
+
+  // macro nesting
+  const a = t`[useLingui]: Text ${plural(users.length, {
+    offset: 1,
+    0: "No books",
+    1: "1 book",
+    other: "# books",
+  })}`
+}

packages/conf/src/__snapshots__/index.test.ts.snap

@@ -57,6 +57,8 @@ exports[`@lingui/conf should return default config 1`] = `
     TransImportName: Trans,
     i18nImportModule: @lingui/core,
     i18nImportName: i18n,
+    useLinguiImportModule: @lingui/react,
+    useLinguiImportName: useLingui,
   },
   service: {
     apiKey: ,

packages/conf/src/migrations/normalizeRuntimeConfigModule.test.ts

@@ -1,62 +1,77 @@
 import { normalizeRuntimeConfigModule } from "./normalizeRuntimeConfigModule"
 
 describe("normalizeRuntimeConfigModule", () => {
-  it("only i18n specified", () => {
-    const actual = normalizeRuntimeConfigModule({
-      runtimeConfigModule: ["../my-i18n", "myI18n"],
-    })
+  test("all defaults", () => {
+    const actual = normalizeRuntimeConfigModule({ runtimeConfigModule: {} })
 
-    expect(actual.runtimeConfigModule).toStrictEqual({
-      TransImportModule: "@lingui/react",
-      TransImportName: "Trans",
-      i18nImportModule: "../my-i18n",
-      i18nImportName: "myI18n",
-    })
+    expect(actual.runtimeConfigModule).toMatchInlineSnapshot(`
+      {
+        TransImportModule: @lingui/react,
+        TransImportName: Trans,
+        i18nImportModule: @lingui/core,
+        i18nImportName: i18n,
+        useLinguiImportModule: @lingui/react,
+        useLinguiImportName: useLingui,
+      }
+    `)
   })
 
-  it("Trans and i18n specified", () => {
+  test("i18n specified as legacy shorthand", () => {
     const actual = normalizeRuntimeConfigModule({
-      runtimeConfigModule: {
-        i18n: ["./custom-i18n", "myI18n"],
-        Trans: ["./custom-trans", "myTrans"],
-      },
+      runtimeConfigModule: ["../my-i18n", "myI18n"],
     })
 
-    expect(actual.runtimeConfigModule).toStrictEqual({
-      TransImportModule: "./custom-trans",
-      TransImportName: "myTrans",
-      i18nImportModule: "./custom-i18n",
-      i18nImportName: "myI18n",
-    })
+    expect(actual.runtimeConfigModule).toMatchInlineSnapshot(`
+      {
+        TransImportModule: @lingui/react,
+        TransImportName: Trans,
+        i18nImportModule: ../my-i18n,
+        i18nImportName: myI18n,
+        useLinguiImportModule: @lingui/react,
+        useLinguiImportName: useLingui,
+      }
+    `)
   })
 
-  it("i18n specified as object", () => {
+  it("All runtime modules specified", () => {
     const actual = normalizeRuntimeConfigModule({
       runtimeConfigModule: {
         i18n: ["./custom-i18n", "myI18n"],
+        Trans: ["./custom-trans", "myTrans"],
+        useLingui: ["./custom-use-lingui", "myLingui"],
       },
     })
 
-    expect(actual.runtimeConfigModule).toStrictEqual({
-      TransImportModule: "@lingui/react",
-      TransImportName: "Trans",
-      i18nImportModule: "./custom-i18n",
-      i18nImportName: "myI18n",
-    })
+    expect(actual.runtimeConfigModule).toMatchInlineSnapshot(`
+      {
+        TransImportModule: ./custom-trans,
+        TransImportName: myTrans,
+        i18nImportModule: ./custom-i18n,
+        i18nImportName: myI18n,
+        useLinguiImportModule: ./custom-use-lingui,
+        useLinguiImportName: myLingui,
+      }
+    `)
   })
 
-  it("Trans specified as object", () => {
+  it("only module is specified", () => {
     const actual = normalizeRuntimeConfigModule({
       runtimeConfigModule: {
-        Trans: ["./custom-trans", "myTrans"],
+        i18n: ["./custom-i18n"],
+        Trans: ["./custom-trans"],
+        useLingui: ["./custom-use-lingui"],
       },
     })
 
-    expect(actual.runtimeConfigModule).toStrictEqual({
-      TransImportModule: "./custom-trans",
-      TransImportName: "myTrans",
-      i18nImportModule: "@lingui/core",
-      i18nImportName: "i18n",
-    })
+    expect(actual.runtimeConfigModule).toMatchInlineSnapshot(`
+      {
+        TransImportModule: ./custom-trans,
+        TransImportName: Trans,
+        i18nImportModule: ./custom-i18n,
+        i18nImportName: i18n,
+        useLinguiImportModule: ./custom-use-lingui,
+        useLinguiImportName: useLingui,
+      }
+    `)
   })
 })

packages/conf/src/migrations/normalizeRuntimeConfigModule.ts

@@ -9,12 +9,18 @@ const getSymbolSource = (
   const name = defaults[1]
   if (Array.isArray(config)) {
     if (name === "i18n") {
-      return config
+      return config as ModuleSrc
     }
     return defaults
   }
 
-  return config[name] || defaults
+  const override = (config as any)[name] as ModuleSrc
+
+  if (!override) {
+    return defaults
+  }
+
+  return [override[0], override[1] || name]
 }
 
 export function normalizeRuntimeConfigModule(
@@ -28,6 +34,10 @@ export function normalizeRuntimeConfigModule(
     ["@lingui/react", "Trans"],
     config.runtimeConfigModule
   )
+  const [useLinguiImportModule, useLinguiImportName] = getSymbolSource(
+    ["@lingui/react", "useLingui"],
+    config.runtimeConfigModule
+  )
 
   return {
     ...config,
@@ -36,6 +46,8 @@ export function normalizeRuntimeConfigModule(
       i18nImportName,
       TransImportModule,
       TransImportName,
+      useLinguiImportModule,
+      useLinguiImportName,
     } satisfies LinguiConfigNormalized["runtimeConfigModule"],
   }
 }

packages/conf/src/types.ts

@@ -111,7 +111,7 @@ type LocaleObject = {
 
 export type FallbackLocales = LocaleObject
 
-type ModuleSource = [string, string?]
+type ModuleSource = readonly [module: string, specifier?: string]
 
 type CatalogService = {
   name: string
@@ -207,7 +207,9 @@ export type LinguiConfig = {
   orderBy?: OrderBy
   pseudoLocale?: string
   rootDir?: string
-  runtimeConfigModule?: ModuleSource | { [symbolName: string]: ModuleSource }
+  runtimeConfigModule?:
+    | ModuleSource
+    | Partial<Record<"useLingui" | "Trans" | "i18n", ModuleSource>>
   sourceLocale?: string
   service?: CatalogService
   experimental?: {
@@ -225,5 +227,7 @@ export type LinguiConfigNormalized = Omit<
     i18nImportName: string
     TransImportModule: string
     TransImportName: string
+    useLinguiImportModule: string
+    useLinguiImportName: string
   }
 }

packages/macro/__typetests__/index.test-d.tsx

@@ -12,6 +12,7 @@ import {
   Plural,
   Select,
   SelectOrdinal,
+  useLingui,
 } from "../index"
 // eslint-disable-next-line import/no-extraneous-dependencies
 import React from "react"
@@ -338,3 +339,17 @@ m = (
     other={<Trans>...</Trans>}
   />
 )
+
+////////////////////////
+//// React useLingui()
+////////////////////////
+function MyComponent() {
+  const { t, i18n } = useLingui()
+
+  expectType<string>(t`Hello world`)
+  expectType<string>(t({ message: "my message" }))
+  // @ts-expect-error: you could not pass a custom instance here
+  t(i18n)({ message: "my message" })
+
+  expectType<I18n>(i18n)
+}

packages/macro/index.d.ts

@@ -1,7 +1,7 @@
 // eslint-disable-next-line import/no-extraneous-dependencies
 import type { ReactNode, VFC, FC } from "react"
 import type { I18n, MessageDescriptor } from "@lingui/core"
-import type { TransRenderCallbackOrComponent } from "@lingui/react"
+import type { TransRenderCallbackOrComponent, I18nContext } from "@lingui/react"
 
 export type ChoiceOptions = {
   /** Offset of value when calculating plural forms */
@@ -316,3 +316,36 @@ export const SelectOrdinal: VFC<PluralChoiceProps>
  * ```
  */
 export const Select: VFC<SelectChoiceProps>
+
+export function _t(descriptor: MacroMessageDescriptor): string
+export function _t(
+  literals: TemplateStringsArray,
+  ...placeholders: any[]
+): string
+
+/**
+ *
+ * Macro version of useLingui replaces _ function with `t` macro function which is bound to i18n passed from React.Context
+ *
+ * Returned `t` macro function has all the same signatures as global `t`
+ *
+ * @example
+ * ```
+ * const { t } = useLingui();
+ * const message = t`Text`;
+ * ```
+ *
+ * @example
+ * ```
+ * const { i18n, t } = useLingui();
+ * const locale = i18n.locale;
+ * const message = t({
+ *   id: "msg.hello",
+ *   comment: "Greetings at the homepage",
+ *   message: `Hello ${name}`,
+ * });
+ * ```
+ */
+export function useLingui(): Omit<I18nContext, "_"> & {
+  t: typeof _t
+}