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

Author: timofei-iatsenko

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

website/docs/releases/migration-5.md

@@ -233,7 +233,35 @@ You'll need to re-[`compile`](/ref/cli#compile) your messages in the new format.
 Read more about the motivation and discuss the changes in the related [issue](https://github.com/lingui/js-lingui/issues/2043).
 :::
 
-## Deprecations and Removals
+## Deprecations
 
-- 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.
+In this release, we've removed some deprecated features and introduced new deprecations.
+
+### Previous Deprecations Removed
+
+- Removed the `isTranslated` prop from the React `Trans` component.
+- Removed support of the module path strings in `LinguiConfig.extractors` property. Pass the extractor object directly.
+
+### New Deprecations
+
+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).