feat(macro): deprecate custom i18n instance on t macro

lingui · Oct 20, 2024 · c938a5c · c938a5c
1 parent 3a51350
commit c938a5c
Show file tree

Hide file tree

Showing 3 changed files with 35 additions and 3 deletions.
diff --git a/packages/core/macro/index.d.ts b/packages/core/macro/index.d.ts
@@ -78,7 +78,7 @@ export function t(
  * import { I18n } from "@lingui/core";
  * const i18n = new I18n({
  *   locale: "nl",
- *   messages: { "Hello {0}": "Hallo {0}" },
+ *   messages: { "Hello {name}": "Hallo {name}" },
  * });
  * const message = t(i18n)`Hello ${name}`;
  * ```
@@ -89,10 +89,14 @@ export function t(
  * import { I18n } from "@lingui/core";
  * const i18n = new I18n({
  *   locale: "nl",
- *   messages: { "Hello {0}": "Hallo {0}" },
+ *   messages: { "Hello {name}": "Hallo {name}" },
  * });
  * const message = t(i18n)({ message: `Hello ${name}` });
  * ```
+ *
+ * @deprecated in v5, would be removed in v6.
+ * Please use `` i18n._(msg`Hello ${name}`) `` instead
+ *
  */
 export function t(i18n: I18n): {
   (literals: TemplateStringsArray, ...placeholders: any[]): string
@@ -209,6 +213,6 @@ export function defineMessage(
 
 /**
  * Define a message for later use
- * Alias for {@see defineMessage}
+ * Alias for {@link defineMessage}
  */
 export const msg: typeof defineMessage
diff --git a/website/docs/ref/macro.mdx b/website/docs/ref/macro.mdx
@@ -161,6 +161,10 @@ const message = i18n._(
 
 Optionally, a custom `i18n` instance can be passed that can be used instead of the global instance:
 
+:::note
+Deprecated in V5, would be removed in v6
+:::
+
 ```jsx
 import { t } from "@lingui/core/macro";
 import { i18nCustom } from "./lingui";

diff --git a/website/docs/releases/migration-5.md b/website/docs/releases/migration-5.md
@@ -204,3 +204,27 @@ You'll need to [re-compile](/docs/ref/cli.md#compile) your messages in the new f
 
 - Removed the deprecated `isTranslated` prop from the React `Trans` component.
 - Removed support of the module path strings in `LinguiConfig.extractors` property. Please pass extractor object directly.
+
+### Using a Custom i18n Instance with the `t` Macro is Deprecated
+
+When you use the global `t` macro from `@lingui/macro`, it automatically relies on the global `i18n` instance. If you want to use a custom `i18n` instance, you could pass it directly to the `t` macro like this:
+
+```js
+import { t } from "@lingui/macro";
+
+t(i18n)`Hello!`;
+```
+
+However, as Lingui evolved, an alternative approach was introduced using the `msg` macro:
+
+```js
+import { msg } from "@lingui/macro";
+
+i18n._(msg(`Hello!`));
+```
+
+This approach is neither better nor worse; it simply offers a different way to achieve the same result.
+
+From a technical perspective, supporting the custom i18n instance with the `t` macro required extra handling in Lingui's plugins for Babel, SWC, and ESLint, which introduced unnecessary complexity and maintenance overhead.
+
+As a result, using a custom i18n instance with the `t` macro has been deprecated. To assist with the transition, an automatic migration is available using [GritQL](https://gist.github.com/timofei-iatsenko/876706f265d725d0aac01018f1812b39).