From 7e35c7fb4292d2e3cb21b0735091131c5537e78b Mon Sep 17 00:00:00 2001
From: Timofei Iatsenko <ty@road.travel>
Date: Wed, 7 Aug 2024 15:28:23 +0200
Subject: [PATCH 1/6] docs: update for v5

---
 website/docs/guides/typescript.md        |  22 ---
 website/docs/ref/macro.mdx               |  19 +--
 website/docs/ref/react.md                |   2 +-
 website/docs/releases/migration-5.md     | 185 ++++++++++++-----------
 website/docs/tutorials/javascript.md     |   8 +-
 website/docs/tutorials/react-native.md   |   4 +-
 website/docs/tutorials/react-patterns.md |   2 +-
 website/docs/tutorials/react-rsc.md      |   9 +-
 website/docs/tutorials/react.md          |   6 +-
 website/docs/tutorials/setup-react.mdx   |  19 +--
 website/docs/tutorials/setup-vite.md     |  12 +-
 11 files changed, 130 insertions(+), 158 deletions(-)
 delete mode 100644 website/docs/guides/typescript.md

diff --git a/website/docs/guides/typescript.md b/website/docs/guides/typescript.md
deleted file mode 100644
index 1bdbcdf3e..000000000
--- a/website/docs/guides/typescript.md
+++ /dev/null
@@ -1,22 +0,0 @@
-# Typescript
-
-Lingui is written in Typescript and ships with TS typings out of the box. You should not need to do anything to get type support working.
-
-## Macros types in non-React environments
-
-We investigated how macros can be used on Typescript environments where React isn't required.
-
-Now we're shipping two declaration types:
-
-- `index.d.ts` files with `@lingui/core`, `@lingui/react` and `react` as peerDependencies.
-- `global.d.ts` files with just `@lingui/core` as peerDependencies.
-
-Now you can modify your `tsconfig.json` in your root directory and reference the global file:
-
-```json title="tsconfig.json"
-{
-  "compilerOptions": {
-    "types": ["./node_modules/@lingui/macro/global"]
-  }
-}
-```
diff --git a/website/docs/ref/macro.mdx b/website/docs/ref/macro.mdx
index 9eb16ec3b..6fb64faec 100644
--- a/website/docs/ref/macro.mdx
+++ b/website/docs/ref/macro.mdx
@@ -14,24 +14,25 @@ import TabItem from "@theme/TabItem";
 
 <Tabs groupId="babel-swc">
   <TabItem value="babel" label="Babel" default>
-    Babel macros require [babel-plugin-macros](https://github.com/kentcdodds/babel-plugin-macros) to work. If you use a framework (for example GatsbyJS, Create React App > 2.0) you might already have macros enabled. Otherwise, install it as any other Babel plugin:
-    - Install `babel-plugin-macros` as a dev dependency and `@lingui/macro` as dependency:
+    Lingui macros require `@lingui/babel-plugin-lingui-macro` or [babel-plugin-macros](https://github.com/kentcdodds/babel-plugin-macros) to work.
+
+    Recommended way is to use `@lingui/babel-plugin-lingui-macro` directly, but if you use a framework which is not allowing to change babel configuration (for example GatsbyJS, Create React App > 2.0) that frameworks might support `babel-plugin-macros` out of the box.
+
+    - Install `@lingui/babel-plugin-lingui-macro` as a dev dependency:
 
       ```bash npm2yarn
       npm install --save-dev babel-plugin-macros
-      npm install --save @lingui/macro
       ```
 
-    - Add `macros` to the top of plugins section in your Babel config:
+    - Add `@lingui/babel-plugin-lingui-macro` to the top of plugins section in your Babel config:
 
       ```json
       {
-        "plugins": ["macros"]
+        "plugins": ["@lingui/babel-plugin-lingui-macro"]
       }
       ```
 
       When using any preset, first check if it includes the `macros` plugin. These presets already includes the `macros` plugin: `react-scripts`.
-
   </TabItem>
   <TabItem value="swc" label="SWC">
     - Install `@lingui/swc-plugin` as a dev dependency and `@lingui/macro` as dependency:
@@ -46,10 +47,6 @@ import TabItem from "@theme/TabItem";
   </TabItem>
 </Tabs>
 
-:::note
-It's recommended to install `@lingui/macro` package as a production dependency rather than development one to avoid `import/no-extraneous-dependencies` errors in ESLint.
-:::
-
 :::tip
 Don't miss the [Lingui ESLint Plugin](/docs/ref/eslint-plugin.md) which can help you find and prevent common l10n mistakes in your code.
 :::
@@ -1026,7 +1023,7 @@ Use `<Select>` inside `<Trans>` macro if you want to provide `id`, `context` or
 ### `useLingui`
 
 :::note
-`useLingui` is available from `@lingui/macro@4.8.0` and not available yet in the `@lingui/swc-plugin`
+`useLingui` is available from lingui v5
 :::
 
 Gives access to a [`t`](/docs/ref/macro.mdx#t) macro bound to the local i18n object passed from React context.
diff --git a/website/docs/ref/react.md b/website/docs/ref/react.md
index 7a94dccd5..de7fc9827 100644
--- a/website/docs/ref/react.md
+++ b/website/docs/ref/react.md
@@ -206,7 +206,7 @@ It's also possible to use `Trans` component directly without macros. In that cas
 
 ### Plurals
 
-If you cannot use [@lingui/macro](/docs/ref/macro.mdx) for some reason, you can render plurals using the plain Trans component like this:
+If you cannot use [@lingui/react/macro](/docs/ref/macro.mdx) for some reason, you can render plurals using the plain Trans component like this:
 
 ```jsx
 import React from "react";
diff --git a/website/docs/releases/migration-5.md b/website/docs/releases/migration-5.md
index 97baec93c..8fe852d02 100644
--- a/website/docs/releases/migration-5.md
+++ b/website/docs/releases/migration-5.md
@@ -4,157 +4,164 @@
 
 TBD
 
-## Split React and JS Macro into separate packages
+## React and Js Macros was split to separate packages
 
-The current Lingui macro is tightly coupled with React, which poses problems for developers using vanilla JavaScript or other frameworks such as Vue.
+The current Lingui macro is tightly coupled with React, which poses problems for developers using Lingui with vanilla JavaScript or other frameworks such as Vue.
 
-#### Issues
-
-- The existing macro assumes React usage, which isn't ideal for non-React projects.
-- Using `@types/react` and `@lingui/react` adds React dependencies to projects that don't use React, which is unnecessary.
-
-#### Benefits of the Split
-
-- Allows the macro to be used with other JSX-based frameworks in the future.
-- Removes unwanted React dependencies, making Lingui more versatile.
-
-#### Solution
-
-To address this, the macro package has been split into two separate packages:
+The macro package has been split into two separate entrypoints from existing packages:
 
 - `@lingui/react/macro`
 - `@lingui/core/macro`
 
-Also, the transformation code has been extracted into a separate Babel plugin `@lingui/babel-plugin-lingui-macro`, which can be used independently of `babel-plugin-macros`.
-
 **Example Usage:**
 
 ```jsx
 import { Trans } from "@lingui/react/macro";
-import { t } from "@lingui/core/macro";
+import { msg } from "@lingui/core/macro";
+
+const colors = [msg`Red`, msg`Yellow`, msg`Green`];
 
 function MyComponent() {
-  <Trans>Hi, my name is {name}</Trans>
-  <span title={t`Title`} />
+  <Trans>Hi, my name is {name}</Trans>;
 }
 ```
 
-#### Migration Strategy
+### Migration
+
+This is not a breaking change.
+
+Imports from `@lingui/macro` still work, but marked as deprecated. They would be removed in the next major release.
 
-- Users can migrate gradually by starting with `@lingui/macro`, which consolidates macros from both core and React-specific packages.
-- Over time, users are encouraged to migrate directly to `@lingui/core/macro` or `@lingui/react/macro` depending on their specific needs.
+You can use an automatic [codemod](https://www.npmjs.com/package/@lingui/codemods) to convert your codebase to the new imports:
+
+```bash
+npx @lingui/codemods split-macro-imports <path>
+```
 
-:::tip
-There is a Codemod [@lingui/codemods](https://www.npmjs.com/package/@lingui/codemods) to help you with the migration. Check out the [`split-macro-imports.ts`](https://github.com/lingui/codemods/blob/main/transforms/split-macro-imports.ts) for more details.
-:::
+After this codemod you can drop `@lingui/macro` from your dependencies.
 
 ## Full Vue.js support
 
 TBD ([#1925](https://github.com/lingui/js-lingui/pull/1925))
 
-## Whitespaces handling changes
+## Changes in whitespaces handling
 
-The current whitespace handling in Lingui, specifically through `normalizeWhitespace`, has been identified as problematic due to occasional incorrect processing of whitespace normalization. This proposal suggests a revised approach that uses stricter rules based on JSX node types to ensure more accurate and predictable whitespace handling.
+### Robust whitespace cleaning in JSX
 
-#### Issues
+Whitespace cleaning in JSX expression is unavoidable, otherwise formatting your JSX code, for example with Prettier, will cause changes in extracted message.
 
-- The existing `normalizeWhitespace` function uses regex to manage whitespace, which sometimes leads to unintended normalization results.
-- Complex JSX structures and interactions with Babel transformations can further complicate whitespace management.
-- The current method merges various JSX node types into a single string before normalization, potentially losing context-specific whitespace information.
+```jsx
+// prettier-ignore
+<Trans>
+  Hello◦{"◦"}◦world
+</Trans>
+
+// should be extracted as
+// "Hello◦◦◦world"
+// without new lines in start and end of tag
+```
+
+Previously Lingui used some regexp based approach to normalize whitespaces in the JSX nodes processed by macro. That approach was not perfect and didn't follow JSX language grammar, that sometimes lead to unexpected results.
 
-#### Solution
+With this version lingui use the same set of rules to clean whitespaces as it's done in JSX. This lead to more anticipated results without unwanted cleaning of whitespaces.
 
-- **Utilize JSX Node Information:**
-  - Instead of treating JSX content as a single string for normalization, use specific JSX node types (e.g., JSXText, JSXExpressionContainer) to apply appropriate whitespace rules.
-  - Implement a function (cleanJSXElementLiteralChild) that adheres to JSX's intrinsic whitespace handling rules, similar to those defined in Babel's sources.
+### No whitespaces cleaning in `t` and other JS macros
 
-**Before:**
+We've got a feedback which we agreed on that whitespaces cleaning in the JS macros is redundant and counterintuitive.
 
-```ts
-<Trans>Hello◦{"◦"}◦world</Trans>
-// -> normalizeWhitespace("Hello◦◦◦world")  we lost here information that middle space came from explicit `{"◦"}`
+```js
+t`Label:◦` + value;
 ```
 
-**After:**
+Note the space after ":", it's expected by developer to be there, but "normalization" will remove it.
+
+Other example would be a markdown, or just a whatever purpose developer want to have an original formatting.
+
+Starting from v5 cleaning whitespaces for JS macros is completely removed.
+
+### Migration
+
+This is a breaking change. Some messages in catalogs might be extracted with different whitespaces and therefore with different ids.
+
+There is no way to automatically convert your catalogs to pick-up existing translation.
+
+If you use TMS (such as Crowdin or Translation.io), migration should be pretty simple. Use Translation Memory feature (or analog).
+
+if you don't use TMS you will need to migrate catalogs manually.
 
-```ts
-<Trans>Hello◦{"◦"}◦world</Trans>
+## Standalone `babel-plugin-lingui-macro`
 
-// there are strict rules how whitespaces processed in JSXText,
-// use `cleanJSXElementLiteralChild` function which follows this rules (taken from babel's sources)
-cleanJSXElementLiteralChild("processHello◦") // JSXText
-{"◦"} // JSXExpressionContainer - arbitary content, left as is
-cleanJSXElementLiteralChild("◦world") // JSXText
+Starting with this version there two ways of using Lingui macro with Babel. With `babel-macro-plugin` and with `babel-plugin-lingui-macro`.
+
+```bash npm2yarn
+npm install --save-dev @lingui/babel-plugin-lingui-macro
 ```
 
-This revised approach to whitespace handling in Lingui addresses current limitations and aligns with best practices observed in JSX processing. The processing now mirrors how JSX handles whitespace.
+### Migration
+
+If you have access to the babel configuration and don't use any other macro in your code, you can drop `babel-macro-plugin` and add `babel-plugin-lingui-macro` to your babel config.
+
+You will benefit from a slightly faster transpiling time and more configuration options for the plugin which are not available for `babel-macro-plugin` version.
 
-## Introducing `useLingui` Macro for Simplified Localization in React
+## Introducing `useLingui` macro
 
-The `useLingui` macro simplifies the handling of non-JSX messages in React components, making internationalization (i18n) integration easy. It replaces direct `t` function calls with cleaner syntax and supports advanced usage within React hooks.
+The `useLingui` macro simplify working with non-jsx messages in react components.
 
-**For example:**
+Before this macro you have to combine `t` or `msg` macro with an instance returned from `useLingui` hook:
 
 ```jsx
-import { useLingui } from "@lingui/macro";
+import { t, msg } from "@lingui/macro";
+import { useLingui } from "@lingui/react";
+
 function MyComponent() {
-  const { t } = useLingui();
-  const a = t`Text`;
+  const { i18n, _ } = useLingui();
+
+  const a = t(i18n)`Text`;
+  // or
+  const b = _(msg`Text`);
 }
+```
 
-// ↓ ↓ ↓ ↓ ↓ ↓
+With the new macro code above simplifies to:
+
+```jsx
+import { useLingui } from "@lingui/react/macro";
 
-import { useLingui } from "@lingui/react";
 function MyComponent() {
-  const { _: _t } = useLingui();
-  const a = _t(
-    /*i18n*/
-    {
-      id: "xeiujy",
-      message: "Text",
-    }
-  );
+  const { t } = useLingui();
+
+  const a = t`Text`;
 }
 ```
 
-As a result, it reduces complexity by consolidating i18n handling into a single macro call.
+Note that `useLingui()` is imported from `@lingui/react/macro`, because it's a macro and not a runtime function. This will be transpiled to the regular `useLingui` from `@lingui/react` under the hood by Lingui.
 
 ## Dependency tree crawling extractor improvements
 
 TBD ([#1958](https://github.com/lingui/js-lingui/pull/1958))
 
-## Improved context
-
-This proposal improves Lingui messages by automatically adding placeholder values as comments in PO files. This improves clarity for translators and AI tools. This feature provides critical **context** to support accurate translations.
+## Print placeholder values for better translation context
 
-For example:
+If the message contains unnamed placeholders, such as `{0}` Lingui will print theirs values into PO comments, so translators and AI got more context what this placeholder is about.
 
-```js title="Message"
-t`from ${myTrip.date}`;
+```js
+t`Hello ${user.name} ${value}`;
 ```
 
-```po title="PO file" {1}
-#. placeholder {0}: myTrip.date
-msgid "from {0}"
-```
-
-In case the string is used in multiple places with different values, the context will be more specific:
-
-```js title="Messages"
-t`from ${myTrip.date}`;
+This will be extracted as
 
-// ...
+Before:
 
-t`from ${eventDate}`;
+```po
+msgid "Hello {0} {value}"
 ```
 
-```po title="PO file" {1,2}
-#. placeholder {0}: myTrip.date
-#. placeholder {0}: eventDate
-msgid "from {0}"
-```
+After:
 
-By improving the handling of placeholder contexts, Lingui enhances the **usability for translators and AI**, promoting more accurate and efficient localization processes.
+```po
+#. placeholder {0}: user.name
+msgid "Hello {0} {value}"
+```
 
 ## Deprecations
 
diff --git a/website/docs/tutorials/javascript.md b/website/docs/tutorials/javascript.md
index 8f779da0d..dfc74d9b8 100644
--- a/website/docs/tutorials/javascript.md
+++ b/website/docs/tutorials/javascript.md
@@ -21,14 +21,14 @@ Let's start with the three major packages:
 
 > The core library responsible for translation and handling of message catalogs
 
-`@lingui/macro`
+`@lingui/babel-plugin-lingui-macro`
 
 > Transforms messages wrapped in tagged template literals to ICU MessageFormat and validates them.
 
-1. Install `@lingui/cli`, `@lingui/macro`, `babel-plugin-macros` and Babel core packages as a development dependencies and `@lingui/core` as a runtime dependency:
+1. Install `@lingui/cli`, `@lingui/babel-plugin-lingui-macro` and Babel core packages as a development dependencies and `@lingui/core` as a runtime dependency:
 
 ```bash npm2yarn
-npm install --save-dev @lingui/cli @lingui/macro babel-plugin-macros @babel/core
+npm install --save-dev @lingui/cli @lingui/babel-plugin-lingui-macro @babel/core
 npm install --save @lingui/core
 ```
 
@@ -36,7 +36,7 @@ npm install --save @lingui/core
 
     ```json
     {
-      "plugins": ["macros"]
+      "plugins": ["@lingui/babel-plugin-lingui-macro"]
     }
     ```
 
diff --git a/website/docs/tutorials/react-native.md b/website/docs/tutorials/react-native.md
index 84204c622..a28db43bc 100644
--- a/website/docs/tutorials/react-native.md
+++ b/website/docs/tutorials/react-native.md
@@ -103,7 +103,7 @@ First, we need to wrap our app with [`I18nProvider`](/docs/ref/react.md#i18nprov
 
 ```tsx
 import { I18nProvider } from "@lingui/react";
-import { Trans } from "@lingui/macro";
+import { Trans } from "@lingui/react/macro";
 import { i18n } from "@lingui/core";
 import { Text } from "react-native";
 
@@ -126,7 +126,7 @@ Translating the heading is done. Now, let's translate the `title` prop in the `<
 The solution is to use the `t` macro which we can obtain from the `useLingui` hook. We use it like this to get a translated string:
 
 ```tsx
-import { useLingui } from '@lingui/macro';
+import { useLingui } from '@lingui/react/macro';
 
 const { t } = useLingui()
 ...
diff --git a/website/docs/tutorials/react-patterns.md b/website/docs/tutorials/react-patterns.md
index c192f0142..e932de358 100644
--- a/website/docs/tutorials/react-patterns.md
+++ b/website/docs/tutorials/react-patterns.md
@@ -102,7 +102,7 @@ function MyComponent() {
 }
 ```
 
-Note that we import `useLingui` from `@lingui/macro`. There is also a runtime version of `useLingui` hook exported from `@lingui/react`. In the case above, it doesn't matter what version to choose since we use only `i18n` object which is presented in both.
+Note that we import `useLingui` from `@lingui/react/macro`. There is also a runtime version of `useLingui` hook exported from `@lingui/react`. In the case above, it doesn't matter what version to choose since we use only `i18n` object which is presented in both.
 
 :::
 
diff --git a/website/docs/tutorials/react-rsc.md b/website/docs/tutorials/react-rsc.md
index 12700e183..e1025b74f 100644
--- a/website/docs/tutorials/react-rsc.md
+++ b/website/docs/tutorials/react-rsc.md
@@ -117,17 +117,16 @@ Below you can see an example of a React component. This component can be rendere
 In fact, if you swapped the html tags for their more universal alternatives, this component could also be used in React Native.
 
 ```tsx title="app/[lang]/components/SomeComponent.tsx"
-import { Trans, t } from "@lingui/macro";
-import { useLingui } from "@lingui/react";
+import { Trans, useLingui } from "@lingui/react/macro";
 
 export function SomeComponent() {
-  const { i18n } = useLingui();
+  const { t } = useLingui();
   return (
     <div>
       <p>
         <Trans>Some Item</Trans>
       </p>
-      <p>{t(i18n)`Other Item`}</p>
+      <p>{t`Other Item`}</p>
     </div>
   );
 }
@@ -162,7 +161,7 @@ It's important that you do not create any locale-dependent strings at a place in
 
 ```tsx
 import { i18n } from "@lingui/core";
-import { t } from "@lingui/macro";
+import { t } from "@lingui/core/macro";
 // 😰 if this code runs at build time, it'll always be in the locale
 // which the imported global i18n object had at that time
 const immutableGreeting = t(i18n)`Hello World`;
diff --git a/website/docs/tutorials/react.md b/website/docs/tutorials/react.md
index dbb80436e..582f4b530 100644
--- a/website/docs/tutorials/react.md
+++ b/website/docs/tutorials/react.md
@@ -327,9 +327,7 @@ const markAsRead = () => {
 To translate it, we will use the `useLingui` macro hook:
 
 ```js
-import { useLingui } from '@lingui/macro';
-
-...
+import { useLingui } from "@lingui/react/macro";
 
 const { t } = useLingui();
 
@@ -347,7 +345,7 @@ const { t } = useLingui();
 
 const markAsRead = () => {
   const userName = "User1234";
-  alert(t`Hello {userName}, your messages marked as read!`);
+  alert(t`Hello ${userName}, your messages marked as read!`);
 };
 ```
 
diff --git a/website/docs/tutorials/setup-react.mdx b/website/docs/tutorials/setup-react.mdx
index 2a51a6b98..b71bbf1be 100644
--- a/website/docs/tutorials/setup-react.mdx
+++ b/website/docs/tutorials/setup-react.mdx
@@ -14,32 +14,29 @@ import TabItem from "@theme/TabItem";
 
 <Tabs groupId="babel-swc" queryString="babel-or-swc">
   <TabItem value="babel" label="Babel" default>
-    - Install `@lingui/cli`, `@lingui/macro`, `babel-plugin-macros` and Babel core packages as a development dependencies, and `@lingui/react` as a runtime dependency:
+    - Install `@lingui/cli`, ` @lingui/babel-plugin-lingui-macro` and Babel core packages as a development dependencies, and `@lingui/react` as a runtime dependency:
 
       ```bash npm2yarn
       npm install --save-dev @lingui/cli @babel/core
-      npm install --save-dev @lingui/macro babel-plugin-macros
+      npm install --save-dev @lingui/babel-plugin-lingui-macro
       npm install --save @lingui/react
       ```
 
-    - Add `macros` plugin to Babel config (e.g: `.babelrc`):
+    - Add `lingui-macro` plugin to Babel config (e.g: `.babelrc`):
 
       ```json
       {
-        "plugins": ["macros"]
+        "plugins": ["@lingui/babel-plugin-lingui-macro"]
       }
       ```
-
-      When using any preset, first check if it includes the `macros` plugin. These presets already includes the `macros` plugin: `react-scripts`.
-
+      When using any preset, first check if it includes the `macros` plugin. Than you don't need to install and setup  `@lingui/babel-plugin-lingui-macro`. These presets already includes the `macros` plugin: `react-scripts`.
   </TabItem>
   <TabItem value="swc" label="SWC">
-    - Install `@lingui/cli`, `@lingui/macro`, and `@lingui/react` as a runtime dependency:
+    - Install `@lingui/cli`, and `@lingui/react` as a runtime dependency:
 
       ```bash npm2yarn
       npm install --save-dev @lingui/cli
       npm install --save @lingui/react
-      npm install --save @lingui/macro
       ```
 
     - Install the `@lingui/swc-plugin` package as a development dependency:
@@ -53,10 +50,6 @@ import TabItem from "@theme/TabItem";
   </TabItem>
 </Tabs>
 
-:::note
-It's recommended to install `@lingui/macro` package as a production dependency rather than development one to avoid `import/no-extraneous-dependencies` errors in ESLint.
-:::
-
 :::tip
 Don't miss the [Lingui ESLint Plugin](/docs/ref/eslint-plugin.md) which can help you find and prevent common l10n mistakes in your code.
 :::
diff --git a/website/docs/tutorials/setup-vite.md b/website/docs/tutorials/setup-vite.md
index 2055d2058..b3449ef2e 100644
--- a/website/docs/tutorials/setup-vite.md
+++ b/website/docs/tutorials/setup-vite.md
@@ -14,11 +14,11 @@ The Lingui Vite integration:
 
 `@vitejs/plugin-react` uses Babel to transform your code. LinguiJS relies on `babel-plugin-macros` to compile JSX to [ICU Message Format](/docs/guides/message-format.md) and for automatic ID generation.
 
-1.  Install `@lingui/cli`, `@lingui/vite-plugin`, `babel-plugin-macros` as development dependencies and `@lingui/macro`, `@lingui/react` as a runtime dependency:
+1.  Install `@lingui/cli`, `@lingui/vite-plugin`, `@lingui/babel-plugin-lingui-macro` as development dependencies and `@lingui/react` as a runtime dependency:
 
     ```bash npm2yarn
-    npm install --save-dev @lingui/cli @lingui/vite-plugin babel-plugin-macros
-    npm install --save @lingui/react @lingui/macro
+    npm install --save-dev @lingui/cli @lingui/vite-plugin @lingui/babel-plugin-lingui-macro
+    npm install --save @lingui/react
     ```
 
 2.  Setup Lingui in `vite.config.ts`:
@@ -36,7 +36,7 @@ The Lingui Vite integration:
       plugins: [
         react({
           babel: {
-            plugins: ["macros"],
+            plugins: ["@lingui/babel-plugin-lingui-macro"],
           },
         }),
         lingui(),
@@ -48,11 +48,11 @@ The Lingui Vite integration:
 
 `@vitejs/plugin-react-swc` uses [SWC](https://swc.rs/) to transform your code, which is 20x faster than Babel. LinguiJS relies on [`@lingui/swc-plugin`](/docs/ref/swc-plugin.md) to compile JSX to [ICU Message Format](/docs/guides/message-format.md) and for automatic ID generation.
 
-1.  Install `@lingui/cli`, `@lingui/swc-plugin` as development dependencies and `@lingui/macro`, `@lingui/react` as a runtime dependency:
+1.  Install `@lingui/cli`, `@lingui/swc-plugin` as development dependencies and `@lingui/react` as a runtime dependency:
 
     ```bash npm2yarn
     npm install --save-dev @lingui/cli @lingui/vite-plugin @lingui/swc-plugin
-    npm install --save @lingui/react @lingui/macro
+    npm install --save @lingui/react
     ```
 
 2.  Setup Lingui in `vite.config.ts`:

From 553bd9c0065ceceae5d44dea0e82cd8d297ab381 Mon Sep 17 00:00:00 2001
From: Timofei Iatsenko <ty@road.travel>
Date: Wed, 7 Aug 2024 15:54:50 +0200
Subject: [PATCH 2/6] docs: disable remark-lint-code-block-style because it's
 gives false-positive

---
 website/.remarkrc.mjs | 1 +
 1 file changed, 1 insertion(+)

diff --git a/website/.remarkrc.mjs b/website/.remarkrc.mjs
index d838c74a9..33b37fd4b 100644
--- a/website/.remarkrc.mjs
+++ b/website/.remarkrc.mjs
@@ -39,6 +39,7 @@ export default {
     ],
 
     // Rules enabled by default by presents above that we don't want
+    ["remark-lint-code-block-style", false],
     ["remark-lint-file-extension", false],
     ["remark-lint-heading-style", false],
     ["remark-lint-list-item-indent", false],

From fec726df24d61c2acec4eeb4a78e9f1616eff6da Mon Sep 17 00:00:00 2001
From: Timofei Iatsenko <ty@road.travel>
Date: Wed, 7 Aug 2024 15:59:19 +0200
Subject: [PATCH 3/6] prettier

---
 website/docs/ref/macro.mdx             | 1 +
 website/docs/tutorials/setup-react.mdx | 1 +
 2 files changed, 2 insertions(+)

diff --git a/website/docs/ref/macro.mdx b/website/docs/ref/macro.mdx
index 6fb64faec..b69af4160 100644
--- a/website/docs/ref/macro.mdx
+++ b/website/docs/ref/macro.mdx
@@ -33,6 +33,7 @@ import TabItem from "@theme/TabItem";
       ```
 
       When using any preset, first check if it includes the `macros` plugin. These presets already includes the `macros` plugin: `react-scripts`.
+
   </TabItem>
   <TabItem value="swc" label="SWC">
     - Install `@lingui/swc-plugin` as a dev dependency and `@lingui/macro` as dependency:
diff --git a/website/docs/tutorials/setup-react.mdx b/website/docs/tutorials/setup-react.mdx
index b71bbf1be..97ccc140e 100644
--- a/website/docs/tutorials/setup-react.mdx
+++ b/website/docs/tutorials/setup-react.mdx
@@ -30,6 +30,7 @@ import TabItem from "@theme/TabItem";
       }
       ```
       When using any preset, first check if it includes the `macros` plugin. Than you don't need to install and setup  `@lingui/babel-plugin-lingui-macro`. These presets already includes the `macros` plugin: `react-scripts`.
+
   </TabItem>
   <TabItem value="swc" label="SWC">
     - Install `@lingui/cli`, and `@lingui/react` as a runtime dependency:

From 93d6f69a1478e0f391f4e10586f76c5b48840ce3 Mon Sep 17 00:00:00 2001
From: Timofei Iatsenko <ty@road.travel>
Date: Tue, 13 Aug 2024 10:38:54 +0200
Subject: [PATCH 4/6] Apply suggestions from code review

Co-authored-by: Vojtech Novak <vonovak@gmail.com>
---
 website/docs/ref/macro.mdx               |  4 ++--
 website/docs/releases/migration-5.md     | 26 ++++++++++++------------
 website/docs/tutorials/javascript.md     |  2 +-
 website/docs/tutorials/react-patterns.md |  2 +-
 website/docs/tutorials/setup-react.mdx   |  2 +-
 5 files changed, 18 insertions(+), 18 deletions(-)

diff --git a/website/docs/ref/macro.mdx b/website/docs/ref/macro.mdx
index b69af4160..20892587e 100644
--- a/website/docs/ref/macro.mdx
+++ b/website/docs/ref/macro.mdx
@@ -16,7 +16,7 @@ import TabItem from "@theme/TabItem";
   <TabItem value="babel" label="Babel" default>
     Lingui macros require `@lingui/babel-plugin-lingui-macro` or [babel-plugin-macros](https://github.com/kentcdodds/babel-plugin-macros) to work.
 
-    Recommended way is to use `@lingui/babel-plugin-lingui-macro` directly, but if you use a framework which is not allowing to change babel configuration (for example GatsbyJS, Create React App > 2.0) that frameworks might support `babel-plugin-macros` out of the box.
+    The recommended way is to use `@lingui/babel-plugin-lingui-macro` directly, but if you use a framework which is does not allow to change babel configuration (for example Create React App > 2.0), that frameworks might support `babel-plugin-macros` out of the box.
 
     - Install `@lingui/babel-plugin-lingui-macro` as a dev dependency:
 
@@ -1024,7 +1024,7 @@ Use `<Select>` inside `<Trans>` macro if you want to provide `id`, `context` or
 ### `useLingui`
 
 :::note
-`useLingui` is available from lingui v5
+`useLingui` React macro is available from lingui v5
 :::
 
 Gives access to a [`t`](/docs/ref/macro.mdx#t) macro bound to the local i18n object passed from React context.
diff --git a/website/docs/releases/migration-5.md b/website/docs/releases/migration-5.md
index 8fe852d02..6ccf9d833 100644
--- a/website/docs/releases/migration-5.md
+++ b/website/docs/releases/migration-5.md
@@ -4,9 +4,9 @@
 
 TBD
 
-## React and Js Macros was split to separate packages
+## React and JS Macros were split to separate packages
 
-The current Lingui macro is tightly coupled with React, which poses problems for developers using Lingui with vanilla JavaScript or other frameworks such as Vue.
+The previous Lingui macro was tightly coupled with React, which posed problems for developers using Lingui with vanilla JavaScript or other frameworks such as Vue.
 
 The macro package has been split into two separate entrypoints from existing packages:
 
@@ -30,7 +30,7 @@ function MyComponent() {
 
 This is not a breaking change.
 
-Imports from `@lingui/macro` still work, but marked as deprecated. They would be removed in the next major release.
+Imports from `@lingui/macro` still work, but are marked as deprecated. They will be removed in the next major release.
 
 You can use an automatic [codemod](https://www.npmjs.com/package/@lingui/codemods) to convert your codebase to the new imports:
 
@@ -38,7 +38,7 @@ You can use an automatic [codemod](https://www.npmjs.com/package/@lingui/codemod
 npx @lingui/codemods split-macro-imports <path>
 ```
 
-After this codemod you can drop `@lingui/macro` from your dependencies.
+After running this codemod you can drop `@lingui/macro` from your dependencies.
 
 ## Full Vue.js support
 
@@ -61,23 +61,23 @@ Whitespace cleaning in JSX expression is unavoidable, otherwise formatting your
 // without new lines in start and end of tag
 ```
 
-Previously Lingui used some regexp based approach to normalize whitespaces in the JSX nodes processed by macro. That approach was not perfect and didn't follow JSX language grammar, that sometimes lead to unexpected results.
+Previously, Lingui used a regexp based approach to normalize whitespaces in the JSX nodes processed by macro. That approach was not perfect and didn't follow JSX language grammar, which sometimes lead to unexpected results.
 
-With this version lingui use the same set of rules to clean whitespaces as it's done in JSX. This lead to more anticipated results without unwanted cleaning of whitespaces.
+With v5, Lingui uses the same set of rules to clean whitespaces as it's done in JSX. This leads to more predictable results without unwanted cleaning of whitespaces.
 
 ### No whitespaces cleaning in `t` and other JS macros
 
-We've got a feedback which we agreed on that whitespaces cleaning in the JS macros is redundant and counterintuitive.
+Based on feedback from developers, it was agreed that whitespace cleaning in the JS macros is redundant and counterintuitive.
 
 ```js
 t`Label:◦` + value;
 ```
 
-Note the space after ":", it's expected by developer to be there, but "normalization" will remove it.
+Note the space after ":" - it's expected by developer to stay in the extracted string, but "normalization" would previously remove it.
 
-Other example would be a markdown, or just a whatever purpose developer want to have an original formatting.
+Other example would be markdown, or any reason for which developer wants to keep the original formatting.
 
-Starting from v5 cleaning whitespaces for JS macros is completely removed.
+Starting from v5, cleaning whitespaces for JS macros is completely removed.
 
 ### Migration
 
@@ -87,7 +87,7 @@ There is no way to automatically convert your catalogs to pick-up existing trans
 
 If you use TMS (such as Crowdin or Translation.io), migration should be pretty simple. Use Translation Memory feature (or analog).
 
-if you don't use TMS you will need to migrate catalogs manually.
+If you don't use a TMS you will need to migrate catalogs manually.
 
 ## Standalone `babel-plugin-lingui-macro`
 
@@ -107,7 +107,7 @@ You will benefit from a slightly faster transpiling time and more configuration
 
 The `useLingui` macro simplify working with non-jsx messages in react components.
 
-Before this macro you have to combine `t` or `msg` macro with an instance returned from `useLingui` hook:
+Before this macro you had to combine `t` or `msg` macro with the i18n instance returned from `useLingui` hook:
 
 ```jsx
 import { t, msg } from "@lingui/macro";
@@ -142,7 +142,7 @@ TBD ([#1958](https://github.com/lingui/js-lingui/pull/1958))
 
 ## Print placeholder values for better translation context
 
-If the message contains unnamed placeholders, such as `{0}` Lingui will print theirs values into PO comments, so translators and AI got more context what this placeholder is about.
+If the message contains unnamed placeholders such as `{0}`, Lingui will print their values into PO comments, so that translators and AI get more context on what the placeholder is about.
 
 ```js
 t`Hello ${user.name} ${value}`;
diff --git a/website/docs/tutorials/javascript.md b/website/docs/tutorials/javascript.md
index dfc74d9b8..90f6bae1c 100644
--- a/website/docs/tutorials/javascript.md
+++ b/website/docs/tutorials/javascript.md
@@ -25,7 +25,7 @@ Let's start with the three major packages:
 
 > Transforms messages wrapped in tagged template literals to ICU MessageFormat and validates them.
 
-1. Install `@lingui/cli`, `@lingui/babel-plugin-lingui-macro` and Babel core packages as a development dependencies and `@lingui/core` as a runtime dependency:
+1. Install `@lingui/cli`, `@lingui/babel-plugin-lingui-macro` and Babel core packages as development dependencies and `@lingui/core` as a runtime dependency:
 
 ```bash npm2yarn
 npm install --save-dev @lingui/cli @lingui/babel-plugin-lingui-macro @babel/core
diff --git a/website/docs/tutorials/react-patterns.md b/website/docs/tutorials/react-patterns.md
index e932de358..2e7e7687c 100644
--- a/website/docs/tutorials/react-patterns.md
+++ b/website/docs/tutorials/react-patterns.md
@@ -102,7 +102,7 @@ function MyComponent() {
 }
 ```
 
-Note that we import `useLingui` from `@lingui/react/macro`. There is also a runtime version of `useLingui` hook exported from `@lingui/react`. In the case above, it doesn't matter what version to choose since we use only `i18n` object which is presented in both.
+Note that we import `useLingui` from `@lingui/react/macro`. There is also a runtime version of `useLingui` hook exported from `@lingui/react`. In the case above, it doesn't matter what version to choose since we use only `i18n` object which is returned by both.
 
 :::
 
diff --git a/website/docs/tutorials/setup-react.mdx b/website/docs/tutorials/setup-react.mdx
index 97ccc140e..a92eee34f 100644
--- a/website/docs/tutorials/setup-react.mdx
+++ b/website/docs/tutorials/setup-react.mdx
@@ -29,7 +29,7 @@ import TabItem from "@theme/TabItem";
         "plugins": ["@lingui/babel-plugin-lingui-macro"]
       }
       ```
-      When using any preset, first check if it includes the `macros` plugin. Than you don't need to install and setup  `@lingui/babel-plugin-lingui-macro`. These presets already includes the `macros` plugin: `react-scripts`.
+      When using any preset, first check if it includes the `macros` plugin. If so, then you don't need to install and set up  `@lingui/babel-plugin-lingui-macro`. For example, the `react-scripts` preset is known to contain the `macros` plugin. 
 
   </TabItem>
   <TabItem value="swc" label="SWC">

From eb154d92ec10195cb3371082cd11bd155b7b95e5 Mon Sep 17 00:00:00 2001
From: Timofei Iatsenko <ty@road.travel>
Date: Wed, 14 Aug 2024 09:30:12 +0200
Subject: [PATCH 5/6] prettier

---
 website/docs/tutorials/setup-react.mdx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/website/docs/tutorials/setup-react.mdx b/website/docs/tutorials/setup-react.mdx
index a92eee34f..4f04a158f 100644
--- a/website/docs/tutorials/setup-react.mdx
+++ b/website/docs/tutorials/setup-react.mdx
@@ -29,7 +29,7 @@ import TabItem from "@theme/TabItem";
         "plugins": ["@lingui/babel-plugin-lingui-macro"]
       }
       ```
-      When using any preset, first check if it includes the `macros` plugin. If so, then you don't need to install and set up  `@lingui/babel-plugin-lingui-macro`. For example, the `react-scripts` preset is known to contain the `macros` plugin. 
+      When using any preset, first check if it includes the `macros` plugin. If so, then you don't need to install and set up  `@lingui/babel-plugin-lingui-macro`. For example, the `react-scripts` preset is known to contain the `macros` plugin.
 
   </TabItem>
   <TabItem value="swc" label="SWC">

From e7b95a87496ba26db85cbae3b135650737f40fd0 Mon Sep 17 00:00:00 2001
From: Timofei Iatsenko <ty@road.travel>
Date: Wed, 14 Aug 2024 09:35:08 +0200
Subject: [PATCH 6/6] doc fix

---
 website/docs/tutorials/setup-vite.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/website/docs/tutorials/setup-vite.md b/website/docs/tutorials/setup-vite.md
index b3449ef2e..b7ad0906a 100644
--- a/website/docs/tutorials/setup-vite.md
+++ b/website/docs/tutorials/setup-vite.md
@@ -12,7 +12,7 @@ The Lingui Vite integration:
 
 ## Setup with [@vitejs/plugin-react](https://www.npmjs.com/package/@vitejs/plugin-react) {#setup-with-vitejs-plugin-react}
 
-`@vitejs/plugin-react` uses Babel to transform your code. LinguiJS relies on `babel-plugin-macros` to compile JSX to [ICU Message Format](/docs/guides/message-format.md) and for automatic ID generation.
+`@vitejs/plugin-react` uses Babel to transform your code. LinguiJS relies on `@lingui/babel-plugin-lingui-macro` to compile JSX to [ICU Message Format](/docs/guides/message-format.md) and for automatic ID generation.
 
 1.  Install `@lingui/cli`, `@lingui/vite-plugin`, `@lingui/babel-plugin-lingui-macro` as development dependencies and `@lingui/react` as a runtime dependency: