From eb1d9c8d0ad21f59bfbabf700c39087785fb14c8 Mon Sep 17 00:00:00 2001
From: Timofei Iatsenko <timiatsenko@gmail.com>
Date: Sun, 20 Oct 2024 14:07:28 +0200
Subject: [PATCH] feat(macro): deprecate custom i18n instance on `t` macro

---
 packages/core/macro/index.d.ts       | 10 +++++++---
 website/docs/releases/migration-5.md | 24 ++++++++++++++++++++++++
 2 files changed, 31 insertions(+), 3 deletions(-)

diff --git a/packages/core/macro/index.d.ts b/packages/core/macro/index.d.ts
index 17deeca28..72e590f4c 100644
--- 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/releases/migration-5.md b/website/docs/releases/migration-5.md
index c14df30c5..f2b449263 100644
--- 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).