diff --git a/website/docs/guides/message-extraction.md b/website/docs/guides/message-extraction.md
index c024cbf17..c7b9e15e7 100644
--- a/website/docs/guides/message-extraction.md
+++ b/website/docs/guides/message-extraction.md
@@ -28,7 +28,7 @@ t({
const jsx = Hi, my name is {name};
```
-For more usage examples, refer to the [macro documentation](/docs/ref/macro.md).
+For more usage examples, refer to the [macro documentation](/docs/ref/macro.mdx).
### Non-Macro usages
diff --git a/website/docs/guides/plurals.md b/website/docs/guides/plurals.md
index 79d660de4..e01493414 100644
--- a/website/docs/guides/plurals.md
+++ b/website/docs/guides/plurals.md
@@ -40,7 +40,7 @@ If you want to specify a message for an exact number, use [`exact matches`](/gui
> Funny fact for non-English speakers: In English, 0 uses plural form too, _0 books_.
-Under the hood, [`plural`](/docs/ref/macro.md#plural) is replaced with low-level [`i18n._`](/docs/ref/core.md#i18n._). For production, the above example will become:
+Under the hood, [`plural`](/docs/ref/macro.mdx#plural) is replaced with low-level [`i18n._`](/docs/ref/core.md#i18n._). For production, the above example will become:
```js
i18n._({
diff --git a/website/docs/misc/react-intl.md b/website/docs/misc/react-intl.md
index 52d645283..1c700029e 100644
--- a/website/docs/misc/react-intl.md
+++ b/website/docs/misc/react-intl.md
@@ -67,7 +67,7 @@ However, let's go yet another level deeper.
## Macros for component-based message syntax
-[Lingui](https://github.com/lingui/js-lingui) provides macros [`@lingui/macro`](/docs/ref/macro.md) which automatically generates a message syntax.
+[Lingui](https://github.com/lingui/js-lingui) provides macros [`@lingui/macro`](/docs/ref/macro.mdx) which automatically generates a message syntax.
Let's go back to the previous example:
@@ -75,7 +75,7 @@ Let's go back to the previous example:
```
-All we need to do is to wrap the message in a [`Trans`](/docs/ref/macro.md#trans) macro:
+All we need to do is to wrap the message in a [`Trans`](/docs/ref/macro.mdx#trans) macro:
```html
@@ -83,9 +83,9 @@ All we need to do is to wrap the message in a [`Trans`](/docs/ref/macro.md#trans
```
-The macro then parses the [`Trans`](/docs/ref/macro.md#trans) macro children and generates `message` and `components` props automatically in the form described in the previous section.
+The macro then parses the [`Trans`](/docs/ref/macro.mdx#trans) macro children and generates `message` and `components` props automatically in the form described in the previous section.
-This is extremely useful when adding i18n to an existing project. All we need is to wrap all messages in [`Trans`](/docs/ref/macro.md#trans) macro.
+This is extremely useful when adding i18n to an existing project. All we need is to wrap all messages in [`Trans`](/docs/ref/macro.mdx#trans) macro.
Let's compare it with react-intl solution to see the difference:
@@ -130,7 +130,7 @@ Let's take a look at the original example from react-intl docs:
/>
```
-Using [Lingui](https://github.com/lingui/js-lingui) macros, we could combine [`Trans`](/docs/ref/macro.md#trans), [`Plural`](/docs/ref/macro.md#plural-1) components and [`i18n.number`](/docs/ref/core.md#i18n.number) macro:
+Using [Lingui](https://github.com/lingui/js-lingui) macros, we could combine [`Trans`](/docs/ref/macro.mdx#trans), [`Plural`](/docs/ref/macro.mdx#plural-1) components and [`i18n.number`](/docs/ref/core.md#i18n.number) macro:
```jsx
diff --git a/website/docs/ref/catalog-formats.md b/website/docs/ref/catalog-formats.md
index 3b0e7ccab..08d46b1f7 100644
--- a/website/docs/ref/catalog-formats.md
+++ b/website/docs/ref/catalog-formats.md
@@ -81,8 +81,8 @@ msgstr[1] "Case number {anotherCount}"
Note that this format comes with several caveats and should therefore only be used if using ICU plurals in PO files is not an option:
-- Nested/multiple plurals in one message as shown in [`plural`](/docs/ref/macro.md#plural) are not supported as it cannot be expressed with gettext plurals. Messages containing nested/multiple formats will not be output correctly.
-- [`select`](/docs/ref/macro.md#select) and [`selectOrdinal`](/docs/ref/macro.md#selectordinal) cannot be expressed with gettext plurals, but the original ICU format is still saved to the `msgid`/`msgstr` properties. To disable the warning that this might not be the expected behavior, include `{ disableSelectWarning: true }` in the [`format`](/docs/ref/conf.md#format) options.
+- Nested/multiple plurals in one message as shown in [`plural`](/docs/ref/macro.mdx#plural) are not supported as it cannot be expressed with gettext plurals. Messages containing nested/multiple formats will not be output correctly.
+- [`select`](/docs/ref/macro.mdx#select) and [`selectOrdinal`](/docs/ref/macro.mdx#selectordinal) cannot be expressed with gettext plurals, but the original ICU format is still saved to the `msgid`/`msgstr` properties. To disable the warning that this might not be the expected behavior, include `{ disableSelectWarning: true }` in the [`format`](/docs/ref/conf.md#format) options.
- Source/development languages with more than two plurals could experience difficulties when no custom IDs are used, as gettext cannot have more than two plurals cases identifying an item (`msgid` and `msgid_plural`).
- Gettext doesn't support plurals for negative and fractional numbers even though some languages have special rules for these cases.
diff --git a/website/docs/ref/conf.md b/website/docs/ref/conf.md
index 70d00a8d1..435ca6654 100644
--- a/website/docs/ref/conf.md
+++ b/website/docs/ref/conf.md
@@ -403,7 +403,7 @@ import { myI18n } from "./custom-i18n-config";
// "runtimeConfigModule": ["./custom-i18n-config", "myI18n"]
```
-In some advanced cases you may also need to change the module from which [Trans](/docs/ref/macro.md#trans) is imported. To do that, pass an object to `runtimeConfigModule`:
+In some advanced cases you may also need to change the module from which [Trans](/docs/ref/macro.mdx#trans) is imported. To do that, pass an object to `runtimeConfigModule`:
```jsx
// If you import `i18n` object from custom module like this:
diff --git a/website/docs/ref/macro.md b/website/docs/ref/macro.mdx
similarity index 93%
rename from website/docs/ref/macro.md
rename to website/docs/ref/macro.mdx
index 9377c9495..b9c5bc4c4 100644
--- a/website/docs/ref/macro.md
+++ b/website/docs/ref/macro.mdx
@@ -5,48 +5,55 @@ description: Transform JavaScript objects and JSX elements into ICU MessageForma
# Macros
-The `@lingui/macro` package transforms JavaScript objects and JSX elements into ICU MessageFormat messages. You can use [Babel macros](#babel) or [SWC plugin](#swc) for this transformation.
+The `@lingui/macro` package transforms JavaScript objects and JSX elements into ICU MessageFormat messages. You can use Babel macros or SWC plugin for this transformation.
## Installation
-Installing `@lingui/macro` can be done in two ways, depending on whether you use Babel or SWC as your compiler.
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
-### Babel
+
+
+ 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:
-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:
+ ```bash npm2yarn
+ npm install --save-dev babel-plugin-macros
+ npm install --save @lingui/macro
+ ```
-1. Install `babel-plugin-macros` as a dev dependency and `@lingui/macro` as dependency:
+ - Add `macros` to the top of plugins section in your Babel config:
-```bash npm2yarn
-npm install --save-dev babel-plugin-macros
-npm install --save @lingui/macro
-```
-
-2. Add `macros` to the top of plugins section in your Babel config:
-
-```json
-{
- "plugins": ["macros"]
-}
-```
+ ```json
+ {
+ "plugins": ["macros"]
+ }
+ ```
-### SWC
+ When using any preset, first check if it includes the `macros` plugin. These presets already includes the `macros` plugin: `react-scripts`.
-For those who prefer not to use Babel, Lingui offers the [SWC Plugin](/docs/ref/swc-plugin.md) as an alternative.
+
+
+ - Install `@lingui/swc-plugin` as a dev dependency and `@lingui/macro` as dependency:
-1. Install `@lingui/swc-plugin` as a dev dependency and `@lingui/macro` as dependency:
+ ```bash npm2yarn
+ npm install --save-dev @lingui/swc-plugin
+ npm install --save @lingui/macro
+ ```
-```bash npm2yarn
-npm install --save-dev @lingui/swc-plugin
-npm install --save @lingui/macro
-```
+ - [Add necessary configurations](/docs/ref/swc-plugin.md#usage).
-2. [Add necessary configurations](/docs/ref/swc-plugin.md#usage).
+
+
:::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.
+:::
+
## Overview
The advantages of using macros are:
@@ -89,10 +96,10 @@ i18n._(
```
:::note
-By default, the `i18n` object is imported from `@lingui/core`. If you use a custom instance of `i18n` object, you need to set [`runtimeConfigModule`](/docs/ref/conf.md#runtimeconfigmodule) or pass a custom instance to [`t`](/docs/ref/macro.md#t).
+By default, the `i18n` object is imported from `@lingui/core`. If you use a custom instance of `i18n` object, you need to set [`runtimeConfigModule`](/docs/ref/conf.md#runtimeconfigmodule) or pass a custom instance to [`t`](/docs/ref/macro.mdx#t).
:::
-The only exception is [`defineMessage`](/docs/ref/macro.md#definemessage) which is transformed into message descriptor. In other words, the message isn't translated directly and can be used anytime later:
+The only exception is [`defineMessage`](/docs/ref/macro.mdx#definemessage) which is transformed into message descriptor. In other words, the message isn't translated directly and can be used anytime later:
```jsx
import { i18n } from "@lingui/core"
@@ -311,7 +318,7 @@ const msg = /*i18n*/ {
These macros can be used in any context (e.g. outside JSX). All JS macros are transformed into a _Message Descriptor_ wrapped inside of [`i18n._`](/docs/ref/core.md#i18n._) call.
:::note
-By default, the `i18n` object is imported from `@lingui/core`. If you use a custom instance of `i18n` object, you need to set [`runtimeConfigModule`](/docs/ref/conf.md#runtimeconfigmodule) or pass a custom instance to [`t`](/docs/ref/macro.md#t).
+By default, the `i18n` object is imported from `@lingui/core`. If you use a custom instance of `i18n` object, you need to set [`runtimeConfigModule`](/docs/ref/conf.md#runtimeconfigmodule) or pass a custom instance to [`t`](/docs/ref/macro.mdx#t).
:::
_Message Descriptor_ is an object with message ID, default message and other parameters. [`i18n._`](/docs/ref/core.md#i18n._) accepts message descriptors and performs translation and formatting:
@@ -482,7 +489,7 @@ const message = i18n._(
);
```
-If you need to add variables to plural form, you can use template string literals. This time [`t`](/docs/ref/macro.md#t) macro isn't required as template strings are transformed automatically:
+If you need to add variables to plural form, you can use template string literals. This time [`t`](/docs/ref/macro.mdx#t) macro isn't required as template strings are transformed automatically:
```js
import { plural } from "@lingui/macro";
@@ -897,7 +904,7 @@ Components and HTML tags are replaced with dummy indexed tags (`<0>0>`) which
> MessageFormat: `{arg, plural, ...forms}`
-Props of [`Plural`](/docs/ref/macro.md#plural-1) macro are transformed into [`plural`](/docs/guides/message-format.md) format.
+Props of [`Plural`](/docs/ref/macro.mdx#plural-1) macro are transformed into [`plural`](/docs/guides/message-format.md) format.
```jsx
import { Plural } from "@lingui/macro";
diff --git a/website/docs/ref/react.md b/website/docs/ref/react.md
index 62642d316..c0603c0b2 100644
--- a/website/docs/ref/react.md
+++ b/website/docs/ref/react.md
@@ -137,7 +137,7 @@ const CurrentLocale = () => {
## Components
-The `@lingui/react` package provides `Trans` component to render translations. However, you're more likely to use [macros](/docs/ref/macro.md) instead because they are more convenient and easier to use.
+The `@lingui/react` package provides `Trans` component to render translations. However, you're more likely to use [macros](/docs/ref/macro.mdx) instead because they are more convenient and easier to use.
This section is intended for reference purposes.
@@ -149,7 +149,7 @@ This section is intended for reference purposes.
:::important
-Import [`Trans`](/docs/ref/macro.md#trans) macro instead of [`Trans`](#trans) component if you use macros:
+Import [`Trans`](/docs/ref/macro.mdx#trans) macro instead of [`Trans`](#trans) component if you use macros:
```jsx
import { Trans } from "@lingui/macro";
@@ -189,7 +189,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.md) for some reason, you can render plurals using the plain Trans component like this:
+If you cannot use [@lingui/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/ref/swc-plugin.md b/website/docs/ref/swc-plugin.md
index f821502c7..e044ed240 100644
--- a/website/docs/ref/swc-plugin.md
+++ b/website/docs/ref/swc-plugin.md
@@ -7,7 +7,7 @@ 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.md).
+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).
[![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)
diff --git a/website/docs/ref/vite-plugin.md b/website/docs/ref/vite-plugin.md
index 995b015e7..54e94cdc9 100644
--- a/website/docs/ref/vite-plugin.md
+++ b/website/docs/ref/vite-plugin.md
@@ -60,5 +60,5 @@ See the [guide about dynamic loading catalogs](/docs/guides/dynamic-loading-cata
See [Vite's official documentation](https://vitejs.dev/guide/features.html#dynamic-import) for more info about Vite dynamic imports.
:::note
-You also need to set up [babel-plugin-macros](https://github.com/kentcdodds/babel-plugin-macros) to support [macros](/docs/ref/macro.md).
+You also need to set up [babel-plugin-macros](https://github.com/kentcdodds/babel-plugin-macros) to support [macros](/docs/ref/macro.mdx).
:::
diff --git a/website/docs/releases/migration-3.md b/website/docs/releases/migration-3.md
index 7d688f43d..d6c269c74 100644
--- a/website/docs/releases/migration-3.md
+++ b/website/docs/releases/migration-3.md
@@ -121,7 +121,7 @@ i18n.load({
### `@lingui/macro`
-- [`plural`](/docs/ref/macro.md#plural), [`select`](/docs/ref/macro.md#select) and [`selectOrdinal`](/docs/ref/macro.md#selectordinal) accepts value as a first parameter:
+- [`plural`](/docs/ref/macro.mdx#plural), [`select`](/docs/ref/macro.mdx#select) and [`selectOrdinal`](/docs/ref/macro.mdx#selectordinal) accepts value as a first parameter:
```diff
- plural({ value, one: "# book", other: "# books" })
@@ -182,7 +182,7 @@ npm install --dev @lingui/macro babel-plugin-macros
}
```
-2. Import [`Trans`](/docs/ref/macro.md#trans), [`Plural`](/docs/ref/macro.md#plural-1), [`Select`](/docs/ref/macro.md#select-1) and [`SelectOrdinal`](/docs/ref/macro.md#selectordinal-1) from `@lingui/macro`:
+2. Import [`Trans`](/docs/ref/macro.mdx#trans), [`Plural`](/docs/ref/macro.mdx#plural-1), [`Select`](/docs/ref/macro.mdx#select-1) and [`SelectOrdinal`](/docs/ref/macro.mdx#selectordinal-1) from `@lingui/macro`:
```diff
- import { Trans } from "@lingui/react"
@@ -190,7 +190,7 @@ npm install --dev @lingui/macro babel-plugin-macros
```
:::caution Note
- If you used [`Trans`](/docs/ref/macro.md#trans) component without children, then keep the import from `@lingui/react`:
+ If you used [`Trans`](/docs/ref/macro.mdx#trans) component without children, then keep the import from `@lingui/react`:
```jsx
import { Trans } from "@lingui/react";
diff --git a/website/docs/tutorials/explicit-vs-generated-ids.md b/website/docs/tutorials/explicit-vs-generated-ids.md
index 89794a074..5f4f0e6e9 100644
--- a/website/docs/tutorials/explicit-vs-generated-ids.md
+++ b/website/docs/tutorials/explicit-vs-generated-ids.md
@@ -71,7 +71,7 @@ msgstr "LinguiJS przyklad"
## Using ID generated from a message
-### With [`Trans`](/docs/ref/macro.md#trans) macro
+### With [`Trans`](/docs/ref/macro.mdx#trans) macro
```jsx
import { Trans } from "@lingui/macro";
@@ -92,7 +92,7 @@ function render() {
}
```
-In the example code above, the content of [`Trans`](/docs/ref/macro.md#trans) is transformed into a message in MessageFormat syntax. By default, this message is used for generating the ID. Considering the example above, the catalog would contain these entries:
+In the example code above, the content of [`Trans`](/docs/ref/macro.mdx#trans) is transformed into a message in MessageFormat syntax. By default, this message is used for generating the ID. Considering the example above, the catalog would contain these entries:
```js
const catalog = [
@@ -170,7 +170,7 @@ const ex2 = {
## Using custom ID
-### With [`Trans`](/docs/ref/macro.md#trans)
+### With [`Trans`](/docs/ref/macro.mdx#trans)
If you're using custom IDs in your project, add `id` prop to i18n components:
@@ -197,7 +197,7 @@ The messages with IDs `msg.header` and `msg.hello` will be extracted with their
### With non-JSX macro
-If you're using custom IDs in your project, call the [`msg`](/docs/ref/macro.md#definemessage) function with a message descriptor object, passing the ID using the `id` property:
+If you're using custom IDs in your project, call the [`msg`](/docs/ref/macro.mdx#definemessage) function with a message descriptor object, passing the ID using the `id` property:
```jsx
import { msg } from "@lingui/macro";
@@ -207,7 +207,7 @@ msg({ id: "msg.greeting", message: `Hello World` });
Message `msg.greeting` will be extracted with default value `Hello World`.
-For all other js macros ([`plural`](/docs/ref/macro.md#plural), [`select`](/docs/ref/macro.md#select), [`selectOrdinal`](/docs/ref/macro.md#selectordinal), use them inside [`msg`](/docs/ref/macro.md#definemessage) macro to pass ID (in this case, `'msg.caption'`).
+For all other js macros ([`plural`](/docs/ref/macro.mdx#plural), [`select`](/docs/ref/macro.mdx#select), [`selectOrdinal`](/docs/ref/macro.mdx#selectordinal), use them inside [`msg`](/docs/ref/macro.mdx#definemessage) macro to pass ID (in this case, `'msg.caption'`).
```jsx
import { msg, plural } from "@lingui/macro";
diff --git a/website/docs/tutorials/javascript.md b/website/docs/tutorials/javascript.md
index 33df358d9..e58e298ee 100644
--- a/website/docs/tutorials/javascript.md
+++ b/website/docs/tutorials/javascript.md
@@ -58,7 +58,7 @@ i18n.activate("en");
## Localizing your app
-Once that is done, we can go ahead and use it! Wrap you text in [`t`](/docs/ref/macro.md#t) macro and pass it to [`i18n._()`](/docs/ref/core.md#i18n._) method:
+Once that is done, we can go ahead and use it! Wrap you text in [`t`](/docs/ref/macro.mdx#t) macro and pass it to [`i18n._()`](/docs/ref/core.md#i18n._) method:
```js
import { t } from "@lingui/macro";
diff --git a/website/docs/tutorials/react-native.md b/website/docs/tutorials/react-native.md
index 72830f5c3..ac0045fb6 100644
--- a/website/docs/tutorials/react-native.md
+++ b/website/docs/tutorials/react-native.md
@@ -5,7 +5,7 @@ description: Learn how to add internationalization to a React Native application
# Internationalization of React Native apps
-In this tutorial, we'll learn how to add internationalization to an existing application in React Native. Before going further, please follow the [setup guide](/docs/tutorials/setup-react.md) for installation and setup instructions.
+In this tutorial, we'll learn how to add internationalization to an existing application in React Native. Before going further, please follow the [setup guide](/docs/tutorials/setup-react.mdx) for installation and setup instructions.
The React Native tutorial is similar to the one for [React](/docs/tutorials/react.md) and we highly recommend you read that one first because it goes into greater detail on many topics. Here, we will only cover parts that are relevant for React Native.
@@ -88,12 +88,12 @@ As you can see, it's a simple mailbox application with only one screen.
## Internationalization in React (Native)
:::tip TL;DR
-There are several ways to render translations: You may use the [`Trans`](/docs/ref/react.md#trans) component or the [`useLingui`](/docs/ref/react.md#uselingui) hook together with the [`t`](/docs/ref/macro.md#t) or [`msg`](/ref/macro#definemessage) macros. When you change the active locale or load new messages, all components that consume the Lingui context provided by [`I18nProvider`](/docs/ref/react.md#i18nprovider) will re-render, making sure the UI shows the correct translations.
+There are several ways to render translations: You may use the [`Trans`](/docs/ref/react.md#trans) component or the [`useLingui`](/docs/ref/react.md#uselingui) hook together with the [`t`](/docs/ref/macro.mdx#t) or [`msg`](/ref/macro#definemessage) macros. When you change the active locale or load new messages, all components that consume the Lingui context provided by [`I18nProvider`](/docs/ref/react.md#i18nprovider) will re-render, making sure the UI shows the correct translations.
:::
Not surprisingly, this part isn't too different from the [React tutorial](/docs/tutorials/react.md).
-First, we need to wrap our app with [`I18nProvider`](/docs/ref/react.md#i18nprovider) and then we can use the [`Trans`](/docs/ref/macro.md#trans) macro to translate the screen heading:
+First, we need to wrap our app with [`I18nProvider`](/docs/ref/react.md#i18nprovider) and then we can use the [`Trans`](/docs/ref/macro.mdx#trans) macro to translate the screen heading:
```tsx
import { I18nProvider } from '@lingui/react'
@@ -115,7 +115,7 @@ i18n.loadAndActivate({ locale: "en", messages });
We're importing the default `i18n` object from `@lingui/core`. Read more about the `i18n` object in the [reference](/ref/core).
:::
-Translating the heading is done. Now, let's translate the `title` prop in the `` element. In this case, `Button` expects to receive a `string`, so we cannot use the [`Trans`](/docs/ref/macro.md#trans) macro here!
+Translating the heading is done. Now, let's translate the `title` prop in the `` element. In this case, `Button` expects to receive a `string`, so we cannot use the [`Trans`](/docs/ref/macro.mdx#trans) macro here!
The solution is to use the `t` macro together with the `i18n` object which we can obtain from the `useLingui` hook. We use the two like this to get a translated string:
diff --git a/website/docs/tutorials/react-patterns.md b/website/docs/tutorials/react-patterns.md
index db46314f0..9b572ded7 100644
--- a/website/docs/tutorials/react-patterns.md
+++ b/website/docs/tutorials/react-patterns.md
@@ -11,7 +11,7 @@ This page describes the most common i18n patterns in React. It's a follow-up to
Using jsx macros is the most straightforward way to translate your React components.
-[`Trans`](/docs/ref/macro.md#trans) handles translations of messages including variables and other React components:
+[`Trans`](/docs/ref/macro.mdx#trans) handles translations of messages including variables and other React components:
```jsx
import { Trans } from "@lingui/macro";
@@ -32,17 +32,17 @@ function render() {
}
```
-You don't need anything special to use [`Trans`](/docs/ref/macro.md#trans) inside your app (except of wrapping the root component in [`I18nProvider`](/docs/ref/react.md#i18nprovider)).
+You don't need anything special to use [`Trans`](/docs/ref/macro.mdx#trans) inside your app (except of wrapping the root component in [`I18nProvider`](/docs/ref/react.md#i18nprovider)).
## Element attributes and string-only translations
-Sometimes you can't use [`Trans`](/docs/ref/macro.md#trans) component, for example when translating element attributes:
+Sometimes you can't use [`Trans`](/docs/ref/macro.mdx#trans) component, for example when translating element attributes:
```html
```
-In such case you need to use the [`useLingui()`](/docs/ref/react.md#uselingui) hook with the [`msg`](/docs/ref/macro.md#definemessage) macro.
+In such case you need to use the [`useLingui()`](/docs/ref/react.md#uselingui) hook with the [`msg`](/docs/ref/macro.mdx#definemessage) macro.
```jsx
import { msg } from "@lingui/macro";
@@ -57,7 +57,7 @@ export default function ImageWithCaption() {
## Translations outside React components
-Sometimes, you may need to access translations outside React components, which is another common pattern. You can use [`t`](/docs/ref/macro.md#t) macro outside React context as usual:
+Sometimes, you may need to access translations outside React components, which is another common pattern. You can use [`t`](/docs/ref/macro.mdx#t) macro outside React context as usual:
```jsx
import { t } from "@lingui/macro";
@@ -68,7 +68,7 @@ export function showAlert() {
```
:::caution
-When you use [`t`](/docs/ref/macro.md#t) macro (and [`plural`](/docs/ref/macro.md#plural), [`select`](/docs/ref/macro.md#select), [`selectOrdinal`](/docs/ref/macro.md#selectordinal)), it uses a global `i18n` instance. While this generally works, there are situations, like in server-side rendering (SSR) applications, where it may not be the best fit.
+When you use [`t`](/docs/ref/macro.mdx#t) macro (and [`plural`](/docs/ref/macro.mdx#plural), [`select`](/docs/ref/macro.mdx#select), [`selectOrdinal`](/docs/ref/macro.mdx#selectordinal)), it uses a global `i18n` instance. While this generally works, there are situations, like in server-side rendering (SSR) applications, where it may not be the best fit.
For better control and flexibility, it's a good idea to avoid the global `i18n` instance and instead use a specific instance tailored to your needs.
@@ -92,7 +92,7 @@ function MyComponent() {
:::
:::note
-All js macros such as [`t`](/docs/ref/macro.md#t) [`plural`](/docs/ref/macro.md#plural), [`select`](/docs/ref/macro.md#select), [`selectOrdinal`](/docs/ref/macro.md#selectordinal) cannot be used on the module level.
+All js macros such as [`t`](/docs/ref/macro.mdx#t) [`plural`](/docs/ref/macro.mdx#plural), [`select`](/docs/ref/macro.mdx#select), [`selectOrdinal`](/docs/ref/macro.mdx#selectordinal) cannot be used on the module level.
```jsx
import { t } from "@lingui/macro";
@@ -115,7 +115,7 @@ A better option would be to use the Lazy Translations pattern described in the f
## Lazy Translations
-You don't need to declare messages at the same code location where they are displayed. Tag a string with the [`msg`](/docs/ref/macro.md#definemessage) macro, and you've created a "message descriptor", which can then be passed around as a variable, and can be displayed as a translated string by passing its `id` to [`Trans`](/docs/ref/macro.md#trans) as its `id` prop:
+You don't need to declare messages at the same code location where they are displayed. Tag a string with the [`msg`](/docs/ref/macro.mdx#definemessage) macro, and you've created a "message descriptor", which can then be passed around as a variable, and can be displayed as a translated string by passing its `id` to [`Trans`](/docs/ref/macro.mdx#trans) as its `id` prop:
```jsx
import { msg } from "@lingui/macro";
@@ -155,7 +155,7 @@ export function getTranslatedColorNames() {
### Passing messages as props
-It's often convenient to pass messages around as component props, for example as a "label" prop on a button. The easiest way to do this is to pass a [`Trans`](/docs/ref/macro.md#trans) element as the prop:
+It's often convenient to pass messages around as component props, for example as a "label" prop on a button. The easiest way to do this is to pass a [`Trans`](/docs/ref/macro.mdx#trans) element as the prop:
```jsx
import { Trans } from "@lingui/macro";
@@ -174,7 +174,7 @@ export function LoginLogoutButtons(props) {
}
```
-If you need the prop to be displayed as a string-only translation, you can pass a message tagged with the [`msg`](/docs/ref/macro.md#definemessage) macro:
+If you need the prop to be displayed as a string-only translation, you can pass a message tagged with the [`msg`](/docs/ref/macro.mdx#definemessage) macro:
```jsx
import { msg } from "@lingui/macro";
@@ -200,7 +200,7 @@ export function HappySad(props) {
Sometimes you need to pick between different messages to display, depending on the value of a variable. For example, imagine you have a numeric "status" code that comes from an API, and you need to display a message representing the current status.
-A simple way to do this is to create an object that maps the possible values of "status" to message descriptors (tagged with the [`msg`](/docs/ref/macro.md#definemessage) macro), and render them as needed with deferred translation:
+A simple way to do this is to create an object that maps the possible values of "status" to message descriptors (tagged with the [`msg`](/docs/ref/macro.mdx#definemessage) macro), and render them as needed with deferred translation:
```jsx
import { msg } from "@lingui/macro";
diff --git a/website/docs/tutorials/react.md b/website/docs/tutorials/react.md
index 1031d8608..ae42f5961 100644
--- a/website/docs/tutorials/react.md
+++ b/website/docs/tutorials/react.md
@@ -58,7 +58,7 @@ As you can see, it's a simple mailbox application with only one page.
## Installing LinguiJS
-Follow the [React projects](/docs/tutorials/setup-react.md) setup guide.
+Follow the [React projects](/docs/tutorials/setup-react.mdx) setup guide.
## Setup
@@ -111,7 +111,7 @@ Let's start with the basics - static messages. These messages don't have any var
Message Inbox
```
-All we need to make this heading translatable is wrap it in [`Trans`](/docs/ref/macro.md#trans) macro:
+All we need to make this heading translatable is wrap it in [`Trans`](/docs/ref/macro.mdx#trans) macro:
```jsx
import { Trans } from "@lingui/macro";
@@ -220,7 +220,7 @@ msgid "Message Inbox"
msgstr ""
```
-That's the message we've wrapped inside [`Trans`](/docs/ref/macro.md#trans) macro!
+That's the message we've wrapped inside [`Trans`](/docs/ref/macro.mdx#trans) macro!
Let's add the Czech translation:
@@ -296,7 +296,7 @@ When we run the app, we see the inbox header is translated into Czech.
Let's go through the workflow again:
1. Add an [`I18nProvider`](/docs/ref/react.md#i18nprovider), this component provides the active language and catalog(s) to other components
-2. Wrap messages in [`Trans`](/docs/ref/macro.md#trans) macro
+2. Wrap messages in [`Trans`](/docs/ref/macro.mdx#trans) macro
3. Run [`extract`](/docs/ref/cli.md#extract) command to generate message catalogs
4. Translate message catalogs (send them to translators usually)
5. Run [`compile`](/docs/ref/cli.md#compile) to create runtime catalogs
@@ -321,7 +321,7 @@ Let's move on to another paragraph in our project. This paragraph has some varia
```
-Although it looks complex, there's really nothing special here. Just wrap the content of the paragraph in [`Trans`](/docs/ref/macro.md#trans) and let the macro do the magic:
+Although it looks complex, there's really nothing special here. Just wrap the content of the paragraph in [`Trans`](/docs/ref/macro.mdx#trans) and let the macro do the magic:
```jsx
@@ -343,7 +343,7 @@ You may notice that components and html tags are replaced with indexed tags (`<0
### JSX to MessageFormat transformations
-It may look a bit _hackish_ at first sight, but these transformations are actually very easy, intuitive and feel very _Reactish_. We don't have to think about the MessageFormat, because it's created by the library. We write our components in the same way as we're used to and simply wrap text in the [`Trans`](/docs/ref/macro.md#trans) macro.
+It may look a bit _hackish_ at first sight, but these transformations are actually very easy, intuitive and feel very _Reactish_. We don't have to think about the MessageFormat, because it's created by the library. We write our components in the same way as we're used to and simply wrap text in the [`Trans`](/docs/ref/macro.mdx#trans) macro.
Let's see some examples with MessageFormat equivalents:
@@ -433,7 +433,7 @@ Here's an example of a simple message catalog in **Czech** language:
| Tuesday | Mardi |
| Wednesday | Mercredi |
-The message ID is _what all catalogs have in common_ – Lundi and Pondělí represent the same message in different languages. It's also the same as the `id` prop in [`Trans`](/docs/ref/macro.md#trans) macro.
+The message ID is _what all catalogs have in common_ – Lundi and Pondělí represent the same message in different languages. It's also the same as the `id` prop in [`Trans`](/docs/ref/macro.mdx#trans) macro.
There are two approaches to how a message ID can be created:
@@ -442,7 +442,7 @@ There are two approaches to how a message ID can be created:
Both approaches have their pros and cons and it's not in the scope of this tutorial to compare them.
-By default, [LinguiJS](https://github.com/lingui/js-lingui) generates message ID from the content of [`Trans`](/docs/ref/macro.md#trans) macro, which means it uses the source language. However, we can easily override it by setting the `id` prop manually:
+By default, [LinguiJS](https://github.com/lingui/js-lingui) generates message ID from the content of [`Trans`](/docs/ref/macro.mdx#trans) macro, which means it uses the source language. However, we can easily override it by setting the `id` prop manually:
```jsx
@@ -494,7 +494,7 @@ How do we know which plural form we should use? It's very simple: we, as develop
> Plural form
-We don't need to select these forms manually. We'll use [`Plural`](/docs/ref/macro.md#plural-1) component, which takes a `value` prop and based on the active language, selects the right plural form:
+We don't need to select these forms manually. We'll use [`Plural`](/docs/ref/macro.mdx#plural-1) component, which takes a `value` prop and based on the active language, selects the right plural form:
```jsx
import { Trans, Plural } from "@lingui/macro";
@@ -516,7 +516,7 @@ Cool! Curious how this component is transformed under the hood and how the messa
In the catalog, you'll see the message in one line. Here we wrapped it to make it more readable.
-The [`Plural`](/docs/ref/macro.md#plural-1) is gone and replaced with [`Trans`](/docs/ref/react.md#trans) again! The sole purpose of [`Plural`](/docs/ref/macro.md#plural-1) is to generate proper syntax in message.
+The [`Plural`](/docs/ref/macro.mdx#plural-1) is gone and replaced with [`Trans`](/docs/ref/react.md#trans) again! The sole purpose of [`Plural`](/docs/ref/macro.mdx#plural-1) is to generate proper syntax in message.
Things are getting a bit more complicated, but i18n is a complex process. At least we don't have to write this message manually!
@@ -592,7 +592,7 @@ Let's go back to our original pluralized message:
```
-What if we want to use variables or components inside messages? Easy! Either wrap messages in [`Trans`](/docs/ref/macro.md#trans) macro or use template literals (suppose we have a variable `name`):
+What if we want to use variables or components inside messages? Easy! Either wrap messages in [`Trans`](/docs/ref/macro.mdx#trans) macro or use template literals (suppose we have a variable `name`):
```jsx
@@ -614,7 +614,7 @@ This gives us enough flexibility for all usecases.
### Custom message ID
-Let's finish this with a short example of plurals with custom ID. We can pass an `id` prop to [`Plural`](/docs/ref/macro.md#plural-1) as we would to [`Trans`](/docs/ref/macro.md#trans):
+Let's finish this with a short example of plurals with custom ID. We can pass an `id` prop to [`Plural`](/docs/ref/macro.mdx#plural-1) as we would to [`Trans`](/docs/ref/macro.mdx#trans):
```jsx
diff --git a/website/docs/tutorials/setup-react.md b/website/docs/tutorials/setup-react.mdx
similarity index 67%
rename from website/docs/tutorials/setup-react.md
rename to website/docs/tutorials/setup-react.mdx
index a897d56ce..0e2687634 100644
--- a/website/docs/tutorials/setup-react.md
+++ b/website/docs/tutorials/setup-react.mdx
@@ -9,30 +9,52 @@ Learn how to add internationalization to a React application using Lingui. This
## Installation
-1. Install `@lingui/cli`, `@lingui/macro`, `babel-plugin-macros` and Babel [^1] core packages as a development dependencies and `@lingui/react` as a runtime dependency.
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
- ```bash npm2yarn
- npm install --save-dev @lingui/cli @babel/core
- npm install --save-dev @lingui/macro babel-plugin-macros
- npm install --save @lingui/react
- ```
+
+
+ - Install `@lingui/cli`, `@lingui/macro`, `babel-plugin-macros` and Babel core packages as a development dependencies, and `@lingui/react` as a runtime dependency:
- :::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.
- :::
+ ```bash npm2yarn
+ npm install --save-dev @lingui/cli @babel/core
+ npm install --save-dev @lingui/macro babel-plugin-macros
+ npm install --save @lingui/react
+ ```
-2. Add `macros` plugin to Babel config (e.g: `.babelrc`):
+ - Add `macros` plugin to Babel config (e.g: `.babelrc`):
- ```json
- {
- "plugins": ["macros"]
- }
- ```
+ ```json
+ {
+ "plugins": ["macros"]
+ }
+ ```
- If you use any preset, check first if it contains `macros` plugin. These presets already includes `macros` plugin: `react-scripts`.
+ When using any preset, first check if it includes the `macros` plugin. These presets already includes the `macros` plugin: `react-scripts`.
-:::info
-For those who prefer not to use Babel, Lingui offers the [SWC Plugin](/docs/ref/swc-plugin.md) as an alternative.
+
+
+ - Install `@lingui/cli`, `@lingui/macro`, 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:
+
+ ```bash npm2yarn
+ npm install --save-dev @lingui/swc-plugin
+ ```
+
+ - [Add necessary configurations](/docs/ref/swc-plugin.md#usage).
+
+
+
+
+:::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
@@ -113,5 +135,3 @@ Congratulations! You've successfully set up project with Lingui. Now it's good t
- [CLI reference](/docs/ref/cli.md)
- [Configuration reference](/docs/ref/conf.md)
- [ICU Message Format](/docs/guides/message-format.md)
-
-[^1]: For those who prefer not to use Babel, Lingui offers the [SWC Plugin](/docs/ref/swc-plugin.md) as an alternative.