From c938a5c9a9b39e5d54eb671caccc47dcafcc689b Mon Sep 17 00:00:00 2001 From: Timofei Iatsenko Date: Sun, 20 Oct 2024 14:07:28 +0200 Subject: [PATCH 1/2] feat(macro): deprecate custom i18n instance on `t` macro --- packages/core/macro/index.d.ts | 10 +++++++--- website/docs/ref/macro.mdx | 4 ++++ website/docs/releases/migration-5.md | 24 ++++++++++++++++++++++++ 3 files changed, 35 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/ref/macro.mdx b/website/docs/ref/macro.mdx index 7d3de28fa..3942e3a6a 100644 --- 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 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). From 4c06d0ebf82c8a437168cfad9f4b512d161e715c Mon Sep 17 00:00:00 2001 From: Andrii Bodnar Date: Wed, 6 Nov 2024 16:59:47 +0200 Subject: [PATCH 2/2] update --- website/docs/ref/macro.mdx | 4 ---- website/docs/releases/migration-5.md | 18 +++++++++++------- 2 files changed, 11 insertions(+), 11 deletions(-) diff --git a/website/docs/ref/macro.mdx b/website/docs/ref/macro.mdx index 3942e3a6a..7d3de28fa 100644 --- a/website/docs/ref/macro.mdx +++ b/website/docs/ref/macro.mdx @@ -161,10 +161,6 @@ 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 index f2b449263..8e9fa9dbf 100644 --- a/website/docs/releases/migration-5.md +++ b/website/docs/releases/migration-5.md @@ -200,14 +200,18 @@ The structure of compiled messages has been changed to make them more predictabl You'll need to [re-compile](/docs/ref/cli.md#compile) your messages in the new format. -## 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. -### Using a Custom i18n Instance with the `t` Macro is Deprecated +### Previous Deprecations Removed -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: +- 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"; @@ -225,6 +229,6 @@ 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. +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). +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).