docs: docusaurus versioning setup

website/README.md

@@ -0,0 +1,58 @@
+# Lingui Documentation Website
+
+This website is built using [Docusaurus](https://docusaurus.io/) and includes versioned documentation.
+
+## Development
+
+```bash
+# Install dependencies
+yarn install
+
+# Start development server
+yarn start
+
+# Build for production
+yarn build
+
+# Serve production build
+yarn serve
+```
+
+## Versioning
+
+```bash
+# Create version from current docs/
+yarn docusaurus docs:version VERSION_NUMBER
+```
+
+## Structure
+
+```text
+website/
+├── docs/                           # Current version documentation
+│   ├── assets/                     # Current version images
+│   └── ...                         # Other documentation files
+├── versioned_docs/
+│   └── version-x.x/                # Legacy documentation for x.x (unmaintained)
+│       └── ...                     # Same structure as docs/
+├── versioned_sidebars/
+│   └── version-x.x-sidebars.json   # Legacy navigation for x.x
+├── blog/                           # Blog posts
+│   ├──  ...
+│   └── authors.yml                 # Blog authors
+├── src/
+│   ├── pages/                      # Non-versioned static pages
+│   │   ├── examples.md             # Examples page
+│   │   ├── community.md            # Community page
+│   │   └── index.tsx               # Homepage
+│   ├── components/                 # React components
+│   └── css/                        # Custom styles
+├── static/
+│   ├── img/
+│   │   ├── features/               # Feature section images
+│   │   └── ...                     # Global assets (logos, favicons)
+│   └── ...
+├── docusaurus.config.ts            # Main configuration
+├── sidebars.ts                     # Current documentation navigation
+└── versions.json                   # Available versions list
+```

website/blog/2023-04-26-announcing-lingui-4.0/index.md

@@ -92,7 +92,7 @@ By doing so, it creates a more optimized catalog that only contains the messages
 
 The catalogs would still contain duplicate messages for common components, but it would be much better than the current approach.
 
-![Scheme of discovering by dependencies](/img/docs/extractor-deps-scheme.svg)
+![Scheme of discovering by dependencies](./extractor-deps-scheme.svg)
 
 :::tip
 See the [Message Extraction](https://lingui.dev/guides/message-extraction) guide to learn more about how message extraction works.

website/docs/guides/custom-formatter.md

@@ -5,7 +5,7 @@ description: Learn how to write a custom localization message formatter for your
 
 # Custom Formatter
 
-If your project requires a message catalog format that Lingui doesn't [natively support](/ref/catalog-formats), you can create a custom formatter to handle it. A custom formatter allows you to define how extracted strings are formatted into a custom catalog format, providing flexibility for specialized workflows and integration with unique file structures.
+If your project requires a message catalog format that Lingui doesn't [natively support](../ref/catalog-formats.md), you can create a custom formatter to handle it. A custom formatter allows you to define how extracted strings are formatted into a custom catalog format, providing flexibility for specialized workflows and integration with unique file structures.
 
 ## Overview
 

website/docs/guides/dynamic-loading-catalogs.md

@@ -5,9 +5,9 @@ description: Learn how to set up dynamic loading of message catalogs in Lingui t
 
 # Dynamic Loading of Message Catalogs
 
-Internationalization in modern applications requires careful handling of localized messages to avoid bloating the initial bundle size. By default, Lingui makes it easy to load all strings for a single active locale. For even greater efficiency, developers can selectively load only the messages needed on demand using [`i18n.load`](/ref/core#i18n.load), ensuring minimal resource usage.
+Internationalization in modern applications requires careful handling of localized messages to avoid bloating the initial bundle size. By default, Lingui makes it easy to load all strings for a single active locale. For even greater efficiency, developers can selectively load only the messages needed on demand using [`i18n.load`](../ref/core.md#i18n.load), ensuring minimal resource usage.
 
-The [`I18nProvider`](/ref/react#i18nprovider) component doesn't make assumptions about your app's structure, giving you the freedom to load only the necessary messages for the currently selected language.
+The [`I18nProvider`](../ref/react.md#i18nprovider) component doesn't make assumptions about your app's structure, giving you the freedom to load only the necessary messages for the currently selected language.
 
 This guide shows how to set up dynamic loading of message catalogs, ensuring only the needed catalogs are loaded, which reduces bundle size and improves performance.
 
@@ -79,16 +79,16 @@ main.ab4626ef.js
 
 When the page is first loaded, only the main bundle and the bundle for the first language are loaded:
 
-![Requests during the first render](/img/docs/dynamic-loading-catalogs-1.png)
+![Requests during the first render](../assets/dynamic-loading-catalogs-1.png)
 
 After changing the language in the UI, the second language bundle is loaded:
 
-![Requests during the second render](/img/docs/dynamic-loading-catalogs-2.png)
+![Requests during the second render](../assets/dynamic-loading-catalogs-2.png)
 
 ## Dependency Tree Extractor (experimental)
 
 The Dependency Tree Extractor is an experimental feature designed to improve message extraction by analyzing the dependency tree of your application. This tool improves the efficiency of loading localized messages by identifying only the necessary messages for each component or page, rather than extracting all messages into a single catalog.
 
 This allows for a more granular extraction process, resulting in smaller and more relevant message catalogs.
 
-For detailed guidance on message extraction, refer to the [Message Extraction](/guides/message-extraction) guide.
+For detailed guidance on message extraction, refer to the [Message Extraction](./message-extraction.md) guide.

website/docs/guides/explicit-vs-generated-ids.md

@@ -148,7 +148,7 @@ function render() {
 }
 ```
 
-In the example code above, the content of [`Trans`](/ref/macro#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`](../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 = [
@@ -202,7 +202,7 @@ The messages with IDs `msg.header` and `msg.hello` will be extracted with their
 
 ### With Core Macro
 
-To use custom IDs in non-JSX macros, call the [`msg`](/ref/macro#definemessage) function with a message descriptor object, passing the ID using the `id` property:
+To use custom IDs in non-JSX macros, call the [`msg`](../ref/macro.mdx#definemessage) function with a message descriptor object, passing the ID using the `id` property:
 
 ```jsx
 import { msg } from "@lingui/core/macro";
@@ -212,7 +212,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`](/ref/macro#plural), [`select`](/ref/macro#select), [`selectOrdinal`](/ref/macro#selectordinal), use them inside [`msg`](/ref/macro#definemessage) macro to pass ID (in this case, `'msg.caption'`).
+For all other js macros ([`plural`](../ref/macro.mdx#plural), [`select`](../ref/macro.mdx#select), [`selectOrdinal`](../ref/macro.mdx#selectordinal), use them inside [`msg`](../ref/macro.mdx#definemessage) macro to pass ID (in this case, `'msg.caption'`).
 
 ```jsx
 import { msg, plural } from "@lingui/core/macro";
@@ -228,5 +228,5 @@ msg({
 
 ## See Also
 
-- [Message Extraction](/guides/message-extraction)
-- [Macros Reference](/ref/macro)
+- [Message Extraction](./message-extraction.md)
+- [Macros Reference](../ref/macro.mdx)

website/docs/guides/lazy-translations.md

@@ -5,11 +5,11 @@ description: Lazy translations allow you to defer translation of a message until
 
 # Lazy Translations
 
-Lazy translation allows you to defer translation of a message until it's rendered, giving you flexibility in how and where you define messages in your code. With lazy translation, you can tag a string with the [`msg`](/ref/macro#definemessage) macro to create a _message descriptor_ that can be saved, passed around as a variable, and rendered later.
+Lazy translation allows you to defer translation of a message until it's rendered, giving you flexibility in how and where you define messages in your code. With lazy translation, you can tag a string with the [`msg`](../ref/macro.mdx#definemessage) macro to create a _message descriptor_ that can be saved, passed around as a variable, and rendered later.
 
 ## Usage Example
 
-To render the message descriptor as a string-only translation, pass it to the [`i18n._()`](/ref/core#i18n._) method:
+To render the message descriptor as a string-only translation, pass it to the [`i18n._()`](../ref/core.md#i18n._) method:
 
 ```jsx
 import { msg } from "@lingui/core/macro";
@@ -24,7 +24,7 @@ export function getTranslatedColorNames() {
 
 ## Usage in React
 
-To render the message descriptor in a React component, pass its `id` to the [`Trans`](/ref/react#trans) component as a value of the `id` prop:
+To render the message descriptor in a React component, pass its `id` to the [`Trans`](../ref/react.md#trans) component as a value of the `id` prop:
 
 ```jsx
 import { msg } from "@lingui/core/macro";
@@ -53,7 +53,7 @@ Please note that we import the `<Trans>` component from `@lingui/react` to use t
 
 Sometimes you need to choose 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 that represents the current status.
 
-An easy way to do this is to create an object that maps the possible values of "status" to message descriptors (tagged with the [`msg`](/ref/macro#definemessage) macro) and render them as needed with deferred translation:
+An easy way to do this is to create an object that maps the possible values of "status" to message descriptors (tagged with the [`msg`](../ref/macro.mdx#definemessage) macro) and render them as needed with deferred translation:
 
 ```jsx
 import { msg } from "@lingui/core/macro";
@@ -76,7 +76,7 @@ export default function StatusDisplay({ statusCode }) {
 
 In the following contrived example, we document how a welcome message will or will not be updated when locale changes. The documented behavior may not be intuitive at first, but it is expected, because of the way the `useMemo` dependencies work.
 
-To avoid bugs with stale translations, use the `t` function returned from the [`useLingui`](/ref/macro#uselingui) macro: it is safe to use with memoization because its reference changes whenever the Lingui context updates.
+To avoid bugs with stale translations, use the `t` function returned from the [`useLingui`](../ref/macro.mdx#uselingui) macro: it is safe to use with memoization because its reference changes whenever the Lingui context updates.
 
 Keep in mind that `useMemo` is primarily a performance optimization tool in React. Because of this, there might be no need to memoize your translations. Additionally, this issue is not present when using the `Trans` component, which we recommend using whenever possible.
 

website/docs/guides/message-extraction.md

@@ -9,7 +9,7 @@ Message extraction is a key part of the internationalization process. It involve
 
 In practice, developers define messages directly in the source code, and the extraction tool automatically collects these messages and stores them in a message catalog for translation.
 
-Read more about the [`lingui extract`](/ref/cli#extract) command.
+Read more about the [`lingui extract`](../ref/cli.md#extract) command.
 
 ## Supported Patterns
 
@@ -19,7 +19,7 @@ The extractor operates at a static level, meaning that it analyzes the source co
 
 > Macros are JavaScript transformers that run at build time. The value returned by a macro is inlined into the bundle instead of the original function call.
 
-The Lingui Macro provides powerful macros to transform JavaScript objects and JSX elements into [ICU MessageFormat](/guides/message-format) messages at compile time.
+The Lingui Macro provides powerful macros to transform JavaScript objects and JSX elements into [ICU MessageFormat](./message-format.md) messages at compile time.
 
 Extractor supports all macro usage, such as the following examples:
 
@@ -39,7 +39,7 @@ const jsx = <Trans>Hi, my name is {name}</Trans>;
 
 The extractor matches the `t` and `Trans` macro calls and extracts the messages from them.
 
-For more usage examples, see to the [Macros](/ref/macro) reference.
+For more usage examples, see to the [Macros](../ref/macro.mdx) reference.
 
 ### Non-Macros Usage
 
@@ -108,9 +108,9 @@ The extractor can locate source files in two ways: by specifying a glob pattern
 
 By default, `lingui extract` uses a glob pattern to search for source files containing messages.
 
-The pattern is defined in the [`catalogs`](/ref/conf#catalogs) property of the Lingui configuration file in your project's root directory.
+The pattern is defined in the [`catalogs`](../ref/conf.md#catalogs) property of the Lingui configuration file in your project's root directory.
 
-![Scheme of discovering by glob pattern](/img/docs/extractor-glob-scheme.svg)
+![Scheme of discovering by glob pattern](../assets/extractor-glob-scheme.svg)
 
 ### Dependency Tree Crawling
 
@@ -130,7 +130,7 @@ By doing so, it creates a more optimized catalog that only contains the messages
 
 The catalogs would still contain duplicate messages for common components, but it would be much better than the current approach.
 
-![Scheme of discovering by dependencies](/img/docs/extractor-deps-scheme.svg)
+![Scheme of discovering by dependencies](../assets/extractor-deps-scheme.svg)
 
 To start using `experimental-extractor`, add the following section to your Lingui configuration:
 
@@ -206,10 +206,10 @@ The extractor supports TypeScript, Flow, and JavaScript (Stage 3) out of the box
 
 If you are using some experimental features (Stage 0 - Stage 2) or frameworks with custom syntax such as Vue.js or Svelte, you may want to implement your own custom extractor.
 
-Visit [Custom Extractor](/guides/custom-extractor) to learn how to create a custom extractor.
+Visit [Custom Extractor](./custom-extractor.md) to learn how to create a custom extractor.
 
 ## See Also
 
-- [Lingui CLI Reference](/ref/cli)
-- [Macros Reference](/ref/macro)
-- [Catalog Formats](/ref/catalog-formats)
+- [Lingui CLI Reference](../ref/cli.md)
+- [Macros Reference](../ref/macro.mdx)
+- [Catalog Formats](../ref/catalog-formats.md)

website/docs/guides/message-format.md

@@ -57,5 +57,5 @@ Example: `Attachment {name} saved`
 
 ## See Also
 
-- [Pluralization](/guides/plurals)
+- [Pluralization](./plurals.md)
 - [ICU Playground](https://format-message.github.io/icu-message-format-for-translators/editor.html)

website/docs/guides/plurals.md

@@ -39,7 +39,7 @@ plural(numBooks, {
 
 When `numBooks == 1`, this will render as _1 book_ and for `numBook == 2` it will be _2 books_. Interestingly, for `numBooks == -1`, it will be _-1 book_. This is because the "one" plural form also applies to -1. It is therefore important to remember that the plural forms (such as "one" or "two") do not represent the numbers themselves, but rather _categories_ of numbers.
 
-Under the hood, the [`plural`](/ref/macro#plural) macro is replaced with a low-level [`i18n._`](/ref/core#i18n._) call. In production, the example will look like this:
+Under the hood, the [`plural`](../ref/macro.mdx#plural) macro is replaced with a low-level [`i18n._`](../ref/core.md#i18n._) call. In production, the example will look like this:
 
 ```js
 i18n._({
@@ -50,7 +50,7 @@ i18n._({
 });
 ```
 
-When we extract messages from the source code using the [Lingui CLI](/ref/cli), we get:
+When we extract messages from the source code using the [Lingui CLI](../ref/cli.md), we get:
 
 ```icu-message-format
 {numBooks, plural, one {# book} other {# books}}

website/docs/guides/pseudolocalization.md

@@ -13,7 +13,7 @@ It also makes it easy to identify hard-coded strings and improperly concatenated
 
 ## Configuration
 
-To configure pseudolocalization, add the [`pseudoLocale`](/ref/conf#pseudolocale) property to your Lingui configuration file:
+To configure pseudolocalization, add the [`pseudoLocale`](../ref/conf.md#pseudolocale) property to your Lingui configuration file:
 
 ```ts title="lingui.config.{ts,js}"
 import { defineConfig } from "@lingui/cli";
@@ -27,15 +27,15 @@ export default defineConfig({
 });
 ```
 
-The `pseudoLocale` option must be set to any string that matches a value in the [`locales`](/ref/conf#locales) configuration. If this is not set correctly, no folder or pseudolocalization will be created.
+The `pseudoLocale` option must be set to any string that matches a value in the [`locales`](../ref/conf.md#locales) configuration. If this is not set correctly, no folder or pseudolocalization will be created.
 
 If the `fallbackLocales` is configured, the pseudolocalization will be generated from the translated fallback locale instead.
 
 ## Generate Pseudolocalization
 
-After running the [`extract`](/ref/cli#extract) command, verify that the folder for the pseudolocale has been created.
+After running the [`extract`](../ref/cli.md#extract) command, verify that the folder for the pseudolocale has been created.
 
-Pseudolocalization is automatically generated during the [`compile`](/ref/cli#compile) process, using the messages.
+Pseudolocalization is automatically generated during the [`compile`](../ref/cli.md#compile) process, using the messages.
 
 ## Switch Browser Into Specified Pseudolocale
 

website/docs/guides/testing.md

@@ -1,6 +1,6 @@
 # Testing
 
-In a React application, components that use [`Trans`](/ref/react#trans) or [`useLingui`](/ref/react#uselingui) need access to the context provided by [`I18nProvider`](/ref/react#i18nprovider). How you wrap your component with the I18nProvider depends on the testing library you're using.
+In a React application, components that use [`Trans`](../ref/react.md#trans) or [`useLingui`](../ref/react.md#uselingui) need access to the context provided by [`I18nProvider`](../ref/react.md#i18nprovider). How you wrap your component with the I18nProvider depends on the testing library you're using.
 
 Below is an example using [react-testing-library](https://testing-library.com/docs/react-testing-library/intro/) and its [wrapper-property](https://testing-library.com/docs/react-testing-library/api#wrapper):