docs: refactor installation instructions

vercel.json

@@ -8,6 +8,8 @@
     { "source": "/tutorials/cli", "destination": "/ref/cli", "permanent": true},
     { "source": "/guides/flow", "destination": "/ref/conf#flow", "permanent": true},
     { "source": "/guides/excluding-build-files", "destination": "/ref/cli#compile", "permanent": true},
-    { "source": "/tutorials/explicit-vs-generated-ids", "destination": "/guides/explicit-vs-generated-ids", "permanent": true}
+    { "source": "/tutorials/explicit-vs-generated-ids", "destination": "/guides/explicit-vs-generated-ids", "permanent": true},
+    { "source": "/tutorials/setup-vite", "destination": "/installation#vite", "permanent": true },
+    { "source": "/tutorials/setup-react", "destination": "/installation", "permanent": true }
   ]
 }

website/docs/installation.mdx

@@ -0,0 +1,192 @@
+---
+title: Installation and Setup
+description: Learn how to install Lingui in your project
+---
+
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
+
+# Installation and Setup
+
+Lingui is more than just a package; it's a comprehensive suite of tools designed to simplify internationalization. You have the flexibility to choose the specific tools that best fit your project's needs.
+
+Learn how to install Lingui in your project, whether you use JavaScript, React or React Native. Lingui also supports various transpilers and build tools, such as Babel, SWC, and Vite.
+
+## Prerequisites
+
+- Make sure you have [Node.js](https://nodejs.org/) installed (v20 or higher).
+- Install [Lingui CLI](/docs/ref/cli.md) to manage your translations and catalogs.
+
+:::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.
+:::
+
+## Choosing Transpiler
+
+> A transpiler converts code within a language, transforming newer features into older equivalents for compatibility, or expanding concise syntax into more detailed implementations.
+
+Lingui needs a transpiler to work. It's responsible for transforming Lingui's JS/JSX components into [ICU Message Format](/docs/guides/message-format.md) and extracting message IDs. Both Babel and SWC transpilers are supported. Depending on your project setup, you can choose the one that suits your needs.
+
+<Tabs groupId="transpiler" queryString>
+<TabItem value="babel" label="Babel" default>
+
+> Babel is a JavaScript transpiler that converts modern code into backward-compatible versions and allows custom syntax transformations.
+
+Lingui requires `@lingui/babel-plugin-lingui-macro` (recommended) or [`babel-plugin-macros`](https://github.com/kentcdodds/babel-plugin-macros) to perform the transformation.
+
+If you are using a framework that doesn't allow you to change the Babel configuration (e.g. Create React App > 2.0), these frameworks may support `babel-plugin-macros` out of the box.
+
+Follow these steps to set up Lingui with Babel:
+
+1.  Install the `@lingui/babel-plugin-lingui-macro` package as a development dependency:
+
+    ```bash npm2yarn
+    npm install --save-dev @lingui/babel-plugin-lingui-macro
+    ```
+
+2.  Add `@lingui/babel-plugin-lingui-macro` to the top of the `plugins` section of your Babel config (e.g. `.babelrc`):
+
+    ```json
+    {
+      "plugins": ["@lingui/babel-plugin-lingui-macro"]
+    }
+    ```
+
+:::tip
+When using a 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, `react-scripts` already includes the `macros` plugin.
+:::
+
+</TabItem>
+<TabItem value="swc" label="SWC">
+
+> SWC is an extensible Rust-based platform for the next generation of fast developer tools.
+
+Lingui supports SWC with a dedicated plugin [`@lingui/swc-plugin`](/docs/ref/swc-plugin.md). SWC is significantly faster than Babel and is a good choice for large projects.
+
+Follow these steps to set up Lingui with SWC:
+
+1.  Install `@lingui/swc-plugin` as a development dependency:
+
+    ```bash npm2yarn
+    npm install --save-dev @lingui/swc-plugin
+    ```
+
+2.  [Add necessary configurations](/docs/ref/swc-plugin.md#usage).
+
+:::caution
+SWC Plugin support is still experimental. Semver backwards compatibility between different `@swc/core` versions is not guaranteed. See the [SWC compatibility](/docs/ref/swc-plugin.md#swc-compatibility) for more information.
+:::
+
+</TabItem>
+</Tabs>
+
+## Basic Configuration
+
+Lingui needs a configuration file to work. The configuration file specifies the source files, message catalogs, and other settings.
+
+Let's create a basic configuration file in the root of your project (next to `package.json`):
+
+```js title="lingui.config.js"
+/** @type {import('@lingui/conf').LinguiConfig} */
+module.exports = {
+  sourceLocale: "en",
+  locales: ["cs", "en"],
+  catalogs: [
+    {
+      path: "<rootDir>/src/locales/{locale}/messages",
+      include: ["src"],
+    },
+  ],
+};
+```
+
+The configuration above specifies the source locale as English and the target locales as Czech and English.
+
+According to this configuration, Lingui will extract messages from source files in the `src` directory and write them to message catalogs in `src/locales` (the English catalog would be in `src/locales/en/messages.po`, for example). See [Configuration](/docs/ref/conf.md) for a complete reference.
+
+:::note
+Replace `src` with the name of the directory where you have the source files.
+:::
+
+The PO format is the default and recommended format for message catalogs. See the [Catalog Formats](/docs/ref/catalog-formats.md) for other available formats.
+
+## Build Tools
+
+### Vite
+
+> Vite is a blazing fast frontend build tool powering the next generation of web applications.
+
+Lingui supports Vite with a dedicated plugin [`@lingui/vite-plugin`](/docs/ref/vite-plugin.md). This plugin is responsible for extracting messages from your source code and compiling message catalogs.
+
+There are two ways to set up Lingui with Vite by using the [`@vitejs/plugin-react`](https://www.npmjs.com/package/@vitejs/plugin-react) or [`@vitejs/plugin-react-swc`](https://www.npmjs.com/package/@vitejs/plugin-react-swc). You need to choose the one that fits your project setup.
+
+<Tabs groupId="transpiler" queryString>
+<TabItem value="babel" label="Babel (plugin-react)" default>
+
+The `@vitejs/plugin-react` plugin uses Babel to transform your code. To use Lingui with Vite and Babel, follow these steps:
+
+1.  Follow the [Choosing Transpiler](#choosing-transpiler) instructions.
+
+2.  Install `@lingui/vite-plugin` as a development dependency and `@lingui/react` as a runtime dependency:
+
+    ```bash npm2yarn
+    npm install --save-dev @lingui/vite-plugin
+    npm install --save @lingui/react
+    ```
+
+3.  Setup Lingui in `vite.config.ts`:
+
+    ```ts title="vite.config.ts"
+    import { defineConfig } from "vite";
+    import react from "@vitejs/plugin-react";
+    import { lingui } from "@lingui/vite-plugin";
+
+    export default defineConfig({
+      plugins: [
+        react({
+          babel: {
+            plugins: ["@lingui/babel-plugin-lingui-macro"],
+          },
+        }),
+        lingui(),
+      ],
+    });
+    ```
+
+:::info
+The `@vitejs/plugin-react` does not use babel config (e.g. `babel.rc`) from your project by default. You have to enable it manually or specify Babel options directly in `vite.config.ts`.
+:::
+
+</TabItem>
+<TabItem value="swc" label="SWC (plugin-react-swc)">
+
+The `@vitejs/plugin-react-swc` plugin uses SWC to transform your code, which is significantly faster than Babel. To use Lingui with Vite and SWC, follow these steps:
+
+1.  Follow the [Choosing Transpiler](#choosing-transpiler) instructions.
+
+2.  Install `@lingui/vite-plugin`, `@lingui/swc-plugin` as development dependencies and `@lingui/react` as a runtime dependency:
+
+    ```bash npm2yarn
+    npm install --save-dev @lingui/vite-plugin @lingui/swc-plugin
+    npm install --save @lingui/react
+    ```
+
+3.  Setup Lingui in `vite.config.ts`:
+
+    ```ts title="vite.config.ts"
+    import { defineConfig } from "vite";
+    import react from "@vitejs/plugin-react-swc";
+    import { lingui } from "@lingui/vite-plugin";
+
+    export default defineConfig({
+      plugins: [
+        react({
+          plugins: [["@lingui/swc-plugin", {}]],
+        }),
+        lingui(),
+      ],
+    });
+    ```
+
+</TabItem>
+</Tabs>

website/docs/ref/cli.md

@@ -7,7 +7,7 @@ description: Learn how to set up and use Lingui CLI to extract, merge and compil
 
 The `@lingui/cli` tool provides the `lingui` command, which allows the extraction of messages from source files into message catalogs and the compilation of message catalogs for production use.
 
-## Install
+## Installation
 
 1. Install `@lingui/cli` as a development dependency:
 

website/docs/ref/conf.md

@@ -1,47 +1,21 @@
 ---
-title: Lingui Configuration
+title: Configuration
 description: Learn how to configure Lingui for your project
 ---
 
-# Lingui Configuration
+# Configuration
 
-Configuration is read from 4 different sources (the first found wins):
+The following reference covers all supported configuration options in Lingui. To learn more about configuring Lingui, read the [Installation and Setup](/docs/installation.mdx) guide.
 
-- from `lingui` section in `package.json`
-- from `.linguirc`
-- from `lingui.config.js`
-- from `lingui.config.ts` _(since 3.4.0)_
+By default, Lingui looks for the configuration in the following locations:
 
-You can also define environment variable `LINGUI_CONFIG` with path to your config file.
+- `lingui.config.js` or `lingui.config.ts` file exporting a configuration object (recommended).
+- `.linguirc` file in JSON format.
+- `lingui` section in `package.json`.
 
-In the case of TypeScript based config you can use ESM format and _export default_.
-
-Default config:
+You can also define the environment variable `LINGUI_CONFIG` with the path to your config file.
 
-```json
-{
-  "catalogs": [
-    {
-      "path": "<rootDir>/locale/{locale}/messages",
-      "include": ["<rootDir>"],
-      "exclude": ["**/node_modules/**"]
-    }
-  ],
-  "catalogsMergePath": "",
-  "compileNamespace": "cjs",
-  "extractorParserOptions": {},
-  "compilerBabelOptions": {},
-  "fallbackLocales": {},
-  "format": "po",
-  "locales": [],
-  "extractors": ["babel"],
-  "orderBy": "messageId",
-  "pseudoLocale": "",
-  "rootDir": ".",
-  "runtimeConfigModule": ["@lingui/core", "i18n"],
-  "sourceLocale": ""
-}
-```
+In the case of TypeScript based config you can use ESM format and _export default_.
 
 ## catalogs
 

website/docs/ref/core.md

@@ -1,11 +1,11 @@
 ---
-title: Lingui Core package
+title: Lingui Core API
 description: The package provides the main i18n object, which manages message catalogs, active locale, and message translation and formatting
 ---
 
-# The core i18n functionality
+# Core API Reference
 
-`@lingui/core` package provides the main i18n object which manages message catalogs, active locale as well as translation and formatting of messages.
+The `@lingui/core` package provides the main i18n object which manages message catalogs, active locale as well as translation and formatting of messages.
 
 ## Installation
 

website/docs/ref/macro.mdx

@@ -17,56 +17,9 @@ The benefits of using macros:
 
 There are two types of macros: [Core Macros](#core-macros) (JS) and [React Macros](#react-macros) (JSX).
 
-## Installation
-
-import Tabs from "@theme/Tabs";
-import TabItem from "@theme/TabItem";
-
-<Tabs groupId="babel-swc">
-<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.
-
-The recommended way is to use `@lingui/babel-plugin-lingui-macro` directly. If you are using a framework that doesn't allow you to change the Babel configuration (e.g. Create React App > 2.0), these frameworks may support `babel-plugin-macros` out of the box.
-
-1.  Install `@lingui/babel-plugin-lingui-macro` as a dev dependency:
-
-    ```bash npm2yarn
-    npm install --save-dev @lingui/babel-plugin-lingui-macro
-    ```
-
-2.  Add `@lingui/babel-plugin-lingui-macro` to the top of the plugins section in your Babel config:
-
-    ```json
-    {
-      "plugins": ["@lingui/babel-plugin-lingui-macro"]
-    }
-    ```
-
-When using a preset, first check if it includes the `macros` plugin. For example, `react-scripts` already includes the `macros` plugin.
-
-</TabItem>
-<TabItem value="swc" label="SWC">
-
-1.  Install `@lingui/swc-plugin` as a dev dependency and `@lingui/macro` as production dependency:
-
-    ```bash npm2yarn
-    npm install --save-dev @lingui/swc-plugin
-    npm install --save @lingui/macro
-    ```
-
-2.  [Add necessary configurations](/docs/ref/swc-plugin.md#usage).
-
-</TabItem>
-</Tabs>
-
-:::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.
-:::
-
 ## Core Macros
 
-Core (JS) Macros can be used in any JavaScript context (e.g. outside of JSX). All JS macros are transformed into a _Message Descriptor_ wrapped inside of [`i18n._`](/docs/ref/core.md#i18n._) call:
+Core (JS) Macros can be used in any JavaScript context (e.g. outside JSX). All JS macros are transformed into a _Message Descriptor_ wrapped inside of [`i18n._`](/docs/ref/core.md#i18n._) call:
 
 ```js
 import { t } from "@lingui/core/macro";

website/docs/ref/react.md

@@ -7,6 +7,12 @@ description: Reference for the Lingui React API and components
 
 Components from `@lingui/react` wrap the vanilla JS API from `@lingui/core`. React components handle changes of active language or interpolated variables better than low-level API and also take care of re-rendering when locale or messages change.
 
+## Installation
+
+```bash npm2yarn
+npm install --save @lingui/react
+```
+
 ## Rendering of Translations {#rendering-translations}
 
 All i18n components render translation as text without a wrapping tag. This can be customized in two different ways:

website/docs/ref/swc-plugin.md

@@ -7,16 +7,14 @@ description: Use Lingui Macros in your SWC project
 
 [SWC](https://swc.rs/) is an extensible Rust-based platform for the next generation of fast developer tools.
 
-If you're using SWC in your project, you can opt for the `@lingui/swc-plugin`. This plugin, designed for SWC, is a Rust version of [LinguiJS Macro](/docs/ref/macro.mdx).
+If you're using SWC in your project, you can opt for the `@lingui/swc-plugin`. This plugin, designed for SWC, is a Rust version of [Lingui Macros](/docs/ref/macro.mdx).
 
 [![npm-version](https://img.shields.io/npm/v/@lingui/swc-plugin?logo=npm&cacheSeconds=1800)](https://www.npmjs.com/package/@lingui/swc-plugin)
 [![npm-downloads](https://img.shields.io/npm/dt/@lingui/swc-plugin?cacheSeconds=500)](https://www.npmjs.com/package/@lingui/swc-plugin)
 
 ## SWC Compatibility
 
-SWC Plugin support is still experimental. Semver backwards compatibility between different `@swc/core` versions is not guaranteed.
-
-Therefore, you need to select an appropriate version of `@lingui/swc-plugin` to match the compatible `@swc/core` version.
+SWC Plugin support is still experimental. Semver backwards compatibility between different `@swc/core` versions [is not guaranteed](https://github.com/swc-project/swc/issues/5060). You need to choose an appropriate version of the `@lingui/swc-plugin` to match the compatible `@swc/core` version.
 
 :::tip
 It is recommended to check the [plugins.swc.rs](https://plugins.swc.rs/) site to find the compatible version.
@@ -30,6 +28,22 @@ Install `@lingui/swc-plugin` as a development dependency:
 npm install --save-dev @lingui/swc-plugin
 ```
 
+To ensure that the resolved version of `@swc/core` is one of the supported versions, you can use the `resolutions` field in the `package.json` file, which is supported by Yarn:
+
+```json
+"resolutions": {
+  "@swc/core": "1.3.56"
+},
+```
+
+or `overrides` for >npm@8.3
+
+```json
+"overrides": {
+  "@swc/core": "1.3.56"
+},
+```
+
 ## Usage
 
 Add the following configuration to your [`.swcrc`](https://swc.rs/docs/configuration/swcrc) file: