diff --git a/website/README.md b/website/README.md new file mode 100644 index 000000000..9a3bd56ac --- /dev/null +++ b/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 +``` diff --git a/website/static/img/docs/extractor-deps-scheme.svg b/website/blog/2023-04-26-announcing-lingui-4.0/extractor-deps-scheme.svg similarity index 100% rename from website/static/img/docs/extractor-deps-scheme.svg rename to website/blog/2023-04-26-announcing-lingui-4.0/extractor-deps-scheme.svg diff --git a/website/blog/2023-04-26-announcing-lingui-4.0/index.md b/website/blog/2023-04-26-announcing-lingui-4.0/index.md index 66ffb3ca3..867b3c12d 100644 --- a/website/blog/2023-04-26-announcing-lingui-4.0/index.md +++ b/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. diff --git a/website/static/img/docs/Crowdin__js-lingui-vcs.png b/website/docs/assets/Crowdin__js-lingui-vcs.png similarity index 100% rename from website/static/img/docs/Crowdin__js-lingui-vcs.png rename to website/docs/assets/Crowdin__js-lingui-vcs.png diff --git a/website/static/img/docs/dynamic-loading-catalogs-1.png b/website/docs/assets/dynamic-loading-catalogs-1.png similarity index 100% rename from website/static/img/docs/dynamic-loading-catalogs-1.png rename to website/docs/assets/dynamic-loading-catalogs-1.png diff --git a/website/static/img/docs/dynamic-loading-catalogs-2.png b/website/docs/assets/dynamic-loading-catalogs-2.png similarity index 100% rename from website/static/img/docs/dynamic-loading-catalogs-2.png rename to website/docs/assets/dynamic-loading-catalogs-2.png diff --git a/website/docs/assets/extractor-deps-scheme.svg b/website/docs/assets/extractor-deps-scheme.svg new file mode 100644 index 000000000..169a9ca33 --- /dev/null +++ b/website/docs/assets/extractor-deps-scheme.svg @@ -0,0 +1,157 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/website/static/img/docs/extractor-glob-scheme.svg b/website/docs/assets/extractor-glob-scheme.svg similarity index 100% rename from website/static/img/docs/extractor-glob-scheme.svg rename to website/docs/assets/extractor-glob-scheme.svg diff --git a/website/static/img/docs/lingui-workflow.svg b/website/docs/assets/lingui-workflow.svg similarity index 100% rename from website/static/img/docs/lingui-workflow.svg rename to website/docs/assets/lingui-workflow.svg diff --git a/website/static/img/docs/rn-component-nesting.png b/website/docs/assets/rn-component-nesting.png similarity index 100% rename from website/static/img/docs/rn-component-nesting.png rename to website/docs/assets/rn-component-nesting.png diff --git a/website/static/img/docs/translation-lingui-plural-forms.png b/website/docs/assets/translation-lingui-plural-forms.png similarity index 100% rename from website/static/img/docs/translation-lingui-plural-forms.png rename to website/docs/assets/translation-lingui-plural-forms.png diff --git a/website/static/img/docs/with-collaboration-tool.svg b/website/docs/assets/with-collaboration-tool.svg similarity index 100% rename from website/static/img/docs/with-collaboration-tool.svg rename to website/docs/assets/with-collaboration-tool.svg diff --git a/website/static/img/docs/without-collaboration-tool.svg b/website/docs/assets/without-collaboration-tool.svg similarity index 100% rename from website/static/img/docs/without-collaboration-tool.svg rename to website/docs/assets/without-collaboration-tool.svg diff --git a/website/docs/guides/custom-formatter.md b/website/docs/guides/custom-formatter.md index 9853fe986..82a25a868 100644 --- a/website/docs/guides/custom-formatter.md +++ b/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 diff --git a/website/docs/guides/dynamic-loading-catalogs.md b/website/docs/guides/dynamic-loading-catalogs.md index 1458af664..c5b760d3c 100644 --- a/website/docs/guides/dynamic-loading-catalogs.md +++ b/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,11 +79,11 @@ 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) @@ -91,4 +91,4 @@ The Dependency Tree Extractor is an experimental feature designed to improve mes 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. diff --git a/website/docs/guides/explicit-vs-generated-ids.md b/website/docs/guides/explicit-vs-generated-ids.md index 70390c954..768b9557a 100644 --- a/website/docs/guides/explicit-vs-generated-ids.md +++ b/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) diff --git a/website/docs/guides/lazy-translations.md b/website/docs/guides/lazy-translations.md index 4d27d944a..dbc329a9f 100644 --- a/website/docs/guides/lazy-translations.md +++ b/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 `` 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. diff --git a/website/docs/guides/message-extraction.md b/website/docs/guides/message-extraction.md index c0a934d87..e8306d976 100644 --- a/website/docs/guides/message-extraction.md +++ b/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 = Hi, my name is {name}; 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) diff --git a/website/docs/guides/message-format.md b/website/docs/guides/message-format.md index de18d632b..4a6d542d3 100644 --- a/website/docs/guides/message-format.md +++ b/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) diff --git a/website/docs/guides/plurals.md b/website/docs/guides/plurals.md index b85573d61..40d2371a1 100644 --- a/website/docs/guides/plurals.md +++ b/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}} diff --git a/website/docs/guides/pseudolocalization.md b/website/docs/guides/pseudolocalization.md index 6c1527ada..abe55be0b 100644 --- a/website/docs/guides/pseudolocalization.md +++ b/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 diff --git a/website/docs/guides/testing.md b/website/docs/guides/testing.md index 921c1dd77..f1f9c5f70 100644 --- a/website/docs/guides/testing.md +++ b/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): diff --git a/website/docs/installation.mdx b/website/docs/installation.mdx index 523632205..f5da1f7c8 100644 --- a/website/docs/installation.mdx +++ b/website/docs/installation.mdx @@ -15,17 +15,17 @@ Learn how to install Lingui in your project, whether you use JavaScript, React ( ## Prerequisites - Make sure you have [Node.js](https://nodejs.org/) installed (v20 or higher). -- Install [Lingui CLI](/ref/cli) to manage your translations and catalogs. +- Install [Lingui CLI](./ref/cli.md) to manage your translations and catalogs. :::tip -Don't miss the [Lingui ESLint Plugin](/ref/eslint-plugin) which can help you find and prevent common i18n mistakes in your code. +Don't miss the [Lingui ESLint Plugin](./ref/eslint-plugin.md) which can help you find and prevent common i18n mistakes in your code. ::: ## Choosing a Transpiler > A transpiler converts code within a language, transforming newer features into older equivalents for compatibility, or expanding concise syntax into more verbose implementations. -Lingui needs a transpiler to work. It's responsible for transforming Lingui's JS/JSX components into [ICU MessageFormat](/guides/message-format) and extracting message IDs. Both Babel and SWC transpilers are supported. Follow the Babel or SWC setup depending on what transpiler your project already uses. +Lingui needs a transpiler to work. It's responsible for transforming Lingui's JS/JSX components into [ICU MessageFormat](./guides/message-format.md) and extracting message IDs. Both Babel and SWC transpilers are supported. Follow the Babel or SWC setup depending on what transpiler your project already uses. @@ -61,7 +61,7 @@ When using a preset, first check if it includes the `macros` plugin. If so, then > 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`](/ref/swc-plugin). SWC is significantly faster than Babel and is a good choice for large projects. +Lingui supports SWC with a dedicated plugin [`@lingui/swc-plugin`](./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: @@ -71,10 +71,10 @@ Follow these steps to set up Lingui with SWC: npm install --save-dev @lingui/swc-plugin ``` -2. [Add necessary configurations](/ref/swc-plugin#usage). +2. [Add necessary configurations](./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](/ref/swc-plugin#swc-compatibility) for more information. +SWC Plugin support is still experimental. Semver backwards compatibility between different `@swc/core` versions is not guaranteed. See the [SWC compatibility](./ref/swc-plugin.md#swc-compatibility) for more information. ::: @@ -103,13 +103,13 @@ export default defineConfig({ 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](/ref/conf) for a complete reference. +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](./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](/ref/catalog-formats) for other available formats. +The PO format is the default and recommended format for message catalogs. See the [Catalog Formats](./ref/catalog-formats.md) for other available formats. ## Build Tools @@ -117,7 +117,7 @@ The PO format is the default and recommended format for message catalogs. See th > 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`](/ref/vite-plugin). This plugin is responsible for extracting messages from your source code and compiling message catalogs. +Lingui supports Vite with a dedicated plugin [`@lingui/vite-plugin`](./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. @@ -194,7 +194,7 @@ The `@vitejs/plugin-react-swc` plugin uses SWC to transform your code, which is ## See Also -- [React i18n Tutorial](/tutorials/react) -- [React Server Components Tutorial](/tutorials/react-rsc) -- [React Native i18n Tutorial](/tutorials/react-native) -- [JavaScript i18n Tutorial](/tutorials/javascript) +- [React i18n Tutorial](./tutorials/react.md) +- [React Server Components Tutorial](./tutorials/react-rsc.md) +- [React Native i18n Tutorial](./tutorials/react-native.md) +- [JavaScript i18n Tutorial](./tutorials/javascript.md) diff --git a/website/docs/introduction.md b/website/docs/introduction.md index d52b0c6cf..839489e79 100644 --- a/website/docs/introduction.md +++ b/website/docs/introduction.md @@ -23,7 +23,7 @@ Keep your code clean and readable, while the library uses battle-tested and powe ### Universal -Use it everywhere. [`@lingui/core`](/ref/core) provides the essential intl functionality which works in any JavaScript project, while [`@lingui/react`](/ref/react) offers components for leveraging React rendering, including React Server Components (RSC) support. +Use it everywhere. [`@lingui/core`](./ref/core.md) provides the essential intl functionality which works in any JavaScript project, while [`@lingui/react`](./ref/react.md) offers components for leveraging React rendering, including React Server Components (RSC) support. ### Full Rich-text Support @@ -31,7 +31,7 @@ Seamlessly use React components within localized messages, without any restricti ### Powerful Tooling -Manage your intl workflow with the Lingui [CLI](/ref/cli), [Vite Plugin](/ref/vite-plugin), and [ESLint Plugin](/ref/eslint-plugin). The CLI extracts, compiles and validates messages, while the Vite plugin compiles catalogs on the fly, and the ESLint plugin helps catch common usage errors. +Manage your intl workflow with the Lingui [CLI](./ref/cli.md), [Vite Plugin](./ref/vite-plugin.md), and [ESLint Plugin](./ref/eslint-plugin.md). The CLI extracts, compiles and validates messages, while the Vite plugin compiles catalogs on the fly, and the ESLint plugin helps catch common usage errors. ### Unopinionated @@ -53,7 +53,7 @@ Join the growing [community of developers](/community) who are using Lingui to b Using Lingui for internationalization is a straightforward process. Here's a high-level overview of the workflow. -![Workflow scheme](/img/docs/lingui-workflow.svg) +![Workflow scheme](./assets/lingui-workflow.svg) ### Define Messages @@ -132,4 +132,4 @@ export default function Lingui({ numUsers, name = "You" }) { ## See Also -- [Installation and Setup](/installation) +- [Installation and Setup](./installation.mdx) diff --git a/website/docs/misc/i18next.md b/website/docs/misc/i18next.md index 6b0bc917c..eaaa4e510 100644 --- a/website/docs/misc/i18next.md +++ b/website/docs/misc/i18next.md @@ -58,7 +58,7 @@ document.getElementById("output").innerHTML = t`Hello world`; ``` :::tip -This example uses a macro for the translation. Macros are a powerful feature of Lingui that allows you to write messages directly in your code. Read more about [Macros](/ref/macro). +This example uses a macro for the translation. Macros are a powerful feature of Lingui that allows you to write messages directly in your code. Read more about [Macros](../ref/macro.mdx). ::: If you prefer to define explicit IDs for your messages, you can follow this approach: @@ -69,7 +69,7 @@ import { t } from "@lingui/core/macro"; document.getElementById("output").innerHTML = t({ id: "msg.greeting", message: `Hello World` }); ``` -Read more about [Explicit vs Generated Message IDs](/guides/explicit-vs-generated-ids). +Read more about [Explicit vs Generated Message IDs](../guides/explicit-vs-generated-ids.md). ## Interpolation @@ -181,7 +181,7 @@ i18n.date(d, { dateStyle: "medium", timeStyle: "medium" }); ## Plurals -Lingui uses the [ICU MessageFormat](/guides/message-format) syntax to handle plurals. It provides a simple and translator-friendly approach to plurals localization. +Lingui uses the [ICU MessageFormat](../guides/message-format.md) syntax to handle plurals. It provides a simple and translator-friendly approach to plurals localization. For example: @@ -192,7 +192,7 @@ plural(numBooks, { }); ``` -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._({ @@ -203,7 +203,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}} @@ -264,7 +264,7 @@ i18next can't do this from its plain JSON files. ## React Integration -Both libraries provide React components for handling translations in React applications. Lingui provides a set of [React Macros](/ref/macro#react-macros) that simplify writing messages directly in your code. i18next provides a `Trans` component to handle translations in JSX. +Both libraries provide React components for handling translations in React applications. Lingui provides a set of [React Macros](../ref/macro.mdx#react-macros) that simplify writing messages directly in your code. i18next provides a `Trans` component to handle translations in JSX. i18next sample: @@ -295,7 +295,7 @@ This is a rather brief comparison. Both libraries have quite different concepts, - Supports rich-text messages. - Provides macros to simplify writing messages directly in your code. - Provides a CLI tool for extracting and compiling messages. -- Supports a number of [Catalog Formats](/ref/catalog-formats), including [Custom Formatters](/guides/custom-formatter). +- Supports a number of [Catalog Formats](../ref/catalog-formats.md), including [Custom Formatters](../guides/custom-formatter.md). - Is small, fast and flexible. It also has a small bundle footprint by stripping unused messages and loading only necessary catalogs. - Works with vanilla JS, React (including RSC), Next.js, Node.js, Vue.js etc. - Is actively maintained. diff --git a/website/docs/misc/react-intl.md b/website/docs/misc/react-intl.md index 91e070cde..c354fe77b 100644 --- a/website/docs/misc/react-intl.md +++ b/website/docs/misc/react-intl.md @@ -65,7 +65,7 @@ The translator gets the message in one piece: `Read the documentationRead the documentation.

``` -All we need to do is to wrap the message in a [`Trans`](/ref/macro#trans) macro: +All we need to do is to wrap the message in a [`Trans`](../ref/macro.mdx#trans) macro: ```html

@@ -81,9 +81,9 @@ All we need to do is to wrap the message in a [`Trans`](/ref/macro#trans) macro:

``` -The macro will then parse the [`Trans`](/ref/macro#trans) macro children and automatically generate `message` and `components` props in the form described in the previous section. +The macro will then parse the [`Trans`](../ref/macro.mdx#trans) macro children and automatically generate `message` and `components` props in the form described in the previous section. -This is very useful when adding i18n to an existing project. All we need to do is wrap all messages in the [`Trans`](/ref/macro#trans) macro. +This is very useful when adding i18n to an existing project. All we need to do is wrap all messages in the [`Trans`](../ref/macro.mdx#trans) macro. Let's compare it to the react-intl solution to see the difference: @@ -110,7 +110,7 @@ It's also worth mentioning that the message IDs are completely optional. Lingui The message ID is `Read the <0>documentation.` instead of `msg.docs`. Both solutions have pros and cons and the library lets you choose the one which works best for you. -Read more about [Explicit vs Generated Message IDs](/guides/explicit-vs-generated-ids). +Read more about [Explicit vs Generated Message IDs](../guides/explicit-vs-generated-ids.md). ::: ## Plurals @@ -130,7 +130,7 @@ Let's take a look at the original example from react-intl docs: /> ``` -Using Lingui macros, we could combine [`Trans`](/ref/macro#trans), [`Plural`](/ref/macro#plural-1) components and [`i18n.number`](/ref/core#i18n.number) macro: +Using Lingui macros, we could combine [`Trans`](../ref/macro.mdx#trans), [`Plural`](../ref/macro.mdx#plural-1) components and [`i18n.number`](../ref/core.md#i18n.number) macro: ```jsx @@ -195,7 +195,7 @@ Custom IDs are supported as well: ``` :::note -To inject `i18n` object into props, you need to use [`useLingui`](/ref/react#uselingui) hook. It's very similar to `useIntl` from [react-intl](https://formatjs.io/docs/react-intl/api/#useintl-hook). +To inject `i18n` object into props, you need to use [`useLingui`](../ref/react.md#uselingui) hook. It's very similar to `useIntl` from [react-intl](https://formatjs.io/docs/react-intl/api/#useintl-hook). ::: ## External Message Catalog @@ -204,7 +204,7 @@ Let's say our application has been internationalized and we want to send the mes react-intl comes with the Babel plugin which extracts messages from individual files, but it's up to you to merge them into one file which you can send to translators. -Lingui provides a handy [`CLI`](/ref/cli) that extracts messages and merges them with any existing translations. It supports both the Babel and SWC ecosystems for extracting messages. +Lingui provides a handy [`CLI`](../ref/cli.md) that extracts messages and merges them with any existing translations. It supports both the Babel and SWC ecosystems for extracting messages. ## Compiling Messages diff --git a/website/docs/ref/catalog-formats.md b/website/docs/ref/catalog-formats.md index 2f2c5fd57..3088b53fb 100644 --- a/website/docs/ref/catalog-formats.md +++ b/website/docs/ref/catalog-formats.md @@ -5,7 +5,7 @@ description: Learn about the different catalog formats supported by Lingui # Catalog Formats -Catalog format (configured by the [`format`](/ref/conf#format) option) refers to the offline catalog file format. This format is never used in production, because the catalog is compiled into a JS module. +Catalog format (configured by the [`format`](./conf.md#format) option) refers to the offline catalog file format. This format is never used in production, because the catalog is compiled into a JS module. The reason for this build step is that the choice of catalog format depends on the individual internationalization workflow. On the other hand, the runtime catalog should be as simple as possible so that it can be parsed quickly without additional overhead. @@ -78,7 +78,7 @@ msgid "msg.inbox" msgstr "Message Inbox" ``` -Messages with plurals are exported in [ICU MessageFormat](/guides/message-format): +Messages with plurals are exported in [ICU MessageFormat](../guides/message-format.md): ```po msgid "{count, plural, one {Message} other {Messages}}" @@ -182,8 +182,8 @@ With this format, plural messages are exported in the following ways, depending This format comes with several caveats and should only be used when using ICU plurals in PO files is not an option: -- Nested/multiple plurals in a message as shown in [`plural`](/ref/macro#plural) are not supported because they cannot be expressed with gettext plurals. Messages containing nested/multiple formats will not be output correctly. -- The [`select`](/ref/macro#select) and [`selectOrdinal`](/ref/macro#selectordinal) cannot be expressed with gettext plurals, but the original ICU format is still stored in the `msgid`/`msgstr` properties. To disable the warning that this may not be the expected behavior, add `{ disableSelectWarning: true }` to the [`format`](/ref/conf#format) options. +- Nested/multiple plurals in a message as shown in [`plural`](./macro.mdx#plural) are not supported because they cannot be expressed with gettext plurals. Messages containing nested/multiple formats will not be output correctly. +- The [`select`](./macro.mdx#select) and [`selectOrdinal`](./macro.mdx#selectordinal) cannot be expressed with gettext plurals, but the original ICU format is still stored in the `msgid`/`msgstr` properties. To disable the warning that this may not be the expected behavior, add `{ disableSelectWarning: true }` to the [`format`](./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. @@ -293,7 +293,7 @@ msg.common,String for translation ## See Also -- [Custom Formatter](/guides/custom-formatter) +- [Custom Formatter](../guides/custom-formatter.md) [package-po]: https://www.npmjs.com/package/@lingui/format-po [package-po-gettext]: https://www.npmjs.com/package/@lingui/format-po-gettext diff --git a/website/docs/ref/cli.md b/website/docs/ref/cli.md index 84a291921..a784ff84d 100644 --- a/website/docs/ref/cli.md +++ b/website/docs/ref/cli.md @@ -43,7 +43,7 @@ If you use TypeScript, you can add the `--typescript` flag to the `compile` scri ### `--config ` -Path to the configuration file. If not set, the default file is loaded as described in the [Configuration](/ref/conf) reference. +Path to the configuration file. If not set, the default file is loaded as described in the [Configuration](./conf.md) reference. ## Commands @@ -64,13 +64,13 @@ The `extract` command scans source files to locate and extract messages, generat This process involves: -1. Extracting messages from files based on the `include` and `exclude` settings in the [`catalogs`](/ref/conf#catalogs) section of the configuration file. +1. Extracting messages from files based on the `include` and `exclude` settings in the [`catalogs`](./conf.md#catalogs) section of the configuration file. 2. Merging the newly extracted messages with any existing message catalogs. 3. Updating and saving the message catalogs. 4. Printing extraction statistics for each language, including the total number of messages and any missing translations. :::tip -Refer to the [Message Extraction](/guides/message-extraction) guide to learn more about this process and the options available. +Refer to the [Message Extraction](../guides/message-extraction.md) guide to learn more about this process and the options available. ::: #### `files` {#extract-files} @@ -103,11 +103,11 @@ However, over time, some messages may be removed from the source code. You can u #### `--overwrite` {#extract-overwrite} -Update translations for [`sourceLocale`](/ref/conf#sourcelocale) from source. +Update translations for [`sourceLocale`](./conf.md#sourcelocale) from source. #### `--format ` {#extract-format} -Extract message catalogs to the specified file format (see the [`format`](/ref/conf#format) option for more details). +Extract message catalogs to the specified file format (see the [`format`](./conf.md#format) option for more details). #### `--locale ` {#extract-locale} @@ -115,7 +115,7 @@ Extract data for the specified locales only. #### `--convert-from ` {#extract-convert-from} -Convert message catalogs from the previous format (see the [`format`](/ref/conf#format) option for more details). +Convert message catalogs from the previous format (see the [`format`](./conf.md#format) option for more details). #### `--verbose` {#extract-verbose} @@ -155,7 +155,7 @@ lingui compile [--watch [--debounce ]] ``` -Once you have all the catalogs ready and translated, you can use this command to compile all the catalogs into minified JS/TS files. It compiles message catalogs located in the [`path`](/ref/conf#catalogs) directory and generates minified JavaScript files. The resulting file is a string that is parsed into a plain JS object using `JSON.parse`. +Once you have all the catalogs ready and translated, you can use this command to compile all the catalogs into minified JS/TS files. It compiles message catalogs located in the [`path`](./conf.md#catalogs) directory and generates minified JavaScript files. The resulting file is a string that is parsed into a plain JS object using `JSON.parse`. The output looks like this: @@ -172,7 +172,7 @@ Messages added to the compiled file are collected in a specific order: 3. Translated message from default fallback locale. 4. Message key. -It is also possible to merge the translated catalogs into a single file per locale by specifying [`catalogsMergePath`](/ref/conf#catalogsmergepath) in the configuration. +It is also possible to merge the translated catalogs into a single file per locale by specifying [`catalogsMergePath`](./conf.md#catalogsmergepath) in the configuration. :::tip The compiled files can be safely ignored by your version control system, since these files must be created each time you deploy to production. We recommend you to create the compiled catalogs in CI as part of your deployment process. Always remember to **use compiled catalogs** in deployments. @@ -193,7 +193,7 @@ Fail if a catalog has missing translations. #### `--format ` {#compile-format} -Format of message catalogs (see the [`format`](/ref/conf#format) option for more details). +Format of message catalogs (see the [`format`](./conf.md#format) option for more details). #### `--verbose` {#compile-verbose} @@ -201,11 +201,11 @@ Print additional information. #### `--namespace` {#compile-namespace} -Specify the namespace for compiled message catalogs (see also [`compileNamespace`](/ref/conf#compilenamespace) for global configuration). +Specify the namespace for compiled message catalogs (see also [`compileNamespace`](./conf.md#compilenamespace) for global configuration). #### `--typescript` {#compile-typescript} -Is the same as using [`compileNamespace`](/ref/conf#compilenamespace) with the value "ts". Generates a `{compiledFile}.ts` file and the exported object is typed using TS. +Is the same as using [`compileNamespace`](./conf.md#compilenamespace) with the value "ts". Generates a `{compiledFile}.ts` file and the exported object is typed using TS. #### `--watch` {#compile-watch} @@ -217,17 +217,17 @@ Delays compilation by `` milliseconds to avoid multiple compilations for ## Configuring the Source Locale -One limitation of checking for missing translations is that the English message catalog typically does not require translations since our source code is in English. This issue can be resolved by configuring the [`sourceLocale`](/ref/conf#sourcelocale) in the configuration file. +One limitation of checking for missing translations is that the English message catalog typically does not require translations since our source code is in English. This issue can be resolved by configuring the [`sourceLocale`](./conf.md#sourcelocale) in the configuration file. ## Compiling Catalogs in CI {#compiling-catalogs-in-ci} -If you're using CI, it's a good idea to add the `compile` command to your build process. Alternatively, you can also use a [Webpack loader](/ref/loader), [Vite plugin](/ref/vite-plugin) or [Metro transformer](/ref/metro-transformer). +If you're using CI, it's a good idea to add the `compile` command to your build process. Alternatively, you can also use a [Webpack loader](./loader.md), [Vite plugin](./vite-plugin.md) or [Metro transformer](./metro-transformer.mdx). -Depending on your localization setup, you might also want to run the `extract` command in CI and upload the extracted messages to a [translation service](/tools/introduction). +Depending on your localization setup, you might also want to run the `extract` command in CI and upload the extracted messages to a [translation service](../tools/introduction.md). ## See Also -- [Lingui Configuration](/ref/conf) -- [Message Extraction](/guides/message-extraction) -- [Catalog Formats](/ref/catalog-formats) -- [Custom Extractor](/guides/custom-extractor) +- [Lingui Configuration](./conf.md) +- [Message Extraction](../guides/message-extraction.md) +- [Catalog Formats](./catalog-formats.md) +- [Custom Extractor](../guides/custom-extractor.md) diff --git a/website/docs/ref/conf.md b/website/docs/ref/conf.md index d55ea8b03..98707ea23 100644 --- a/website/docs/ref/conf.md +++ b/website/docs/ref/conf.md @@ -5,7 +5,7 @@ description: Learn how to configure Lingui for your project # Configuration -The following reference covers all supported configuration options in Lingui. To learn more about configuring Lingui, read the [Installation and Setup](/installation) guide. +The following reference covers all supported configuration options in Lingui. To learn more about configuring Lingui, read the [Installation and Setup](../installation.mdx) guide. By default, Lingui looks for the configuration in the following locations: @@ -31,7 +31,7 @@ Default value: ]; ``` -The `catalogs` configuration defines the location of message catalogs and specifies which files are included when the [`extract`](/ref/cli#extract) command scans for messages. +The `catalogs` configuration defines the location of message catalogs and specifies which files are included when the [`extract`](./cli.md#extract) command scans for messages. - `path`: the directory where the message catalogs are located. It should not end with a slash and must not include a file extension, which depends on the [`format`](#format) configuration. The `{locale}` token will be replaced by the catalog's locale. - `include` and `exclude`: these patterns specify which files to include or exclude during the extraction process. They are passed to [minimatch](https://github.com/isaacs/minimatch) for pattern matching. @@ -158,7 +158,7 @@ components/ Default value: `[]` -The locale tags used in the project. The [`extract`](/ref/cli#extract) and [`compile`](/ref/cli#compile) commands write a catalog for each locale specified. Each locale should be a valid [BCP-47 code](http://www.unicode.org/cldr/charts/latest/supplemental/language_plural_rules.html): +The locale tags used in the project. The [`extract`](./cli.md#extract) and [`compile`](./cli.md#compile) commands write a catalog for each locale specified. Each locale should be a valid [BCP-47 code](http://www.unicode.org/cldr/charts/latest/supplemental/language_plural_rules.html): ```json { @@ -217,13 +217,13 @@ Default value: `""` Locale used for pseudolocalization. For example, when you set `pseudoLocale: "en"`, all messages in the `en` catalog will be pseudo-localized. The locale must be included in the `locales` config. -Read more about [Pseudolocalization](/guides/pseudolocalization). +Read more about [Pseudolocalization](../guides/pseudolocalization.md). ## catalogsMergePath Default value: `""` -Define the path where translated catalogs are merged into a single file per locale during the [`compile`](/ref/cli#compile) process. +Define the path where translated catalogs are merged into a single file per locale during the [`compile`](./cli.md#compile) process. #### Example @@ -272,7 +272,7 @@ Using the `catalogsMergePath`, separate catalogs can be merged into a single fil Default value: `cjs` -Specify namespace for exporting compiled messages. See [`compile`](/ref/cli#compile) command. +Specify namespace for exporting compiled messages. See [`compile`](./cli.md#compile) command. #### cjs @@ -390,7 +390,7 @@ export default defineConfig({ }); ``` -Read more about available formatters in [Catalog Formats](/ref/catalog-formats) or create your own [Custom Formatter](/guides/custom-formatter). +Read more about available formatters in [Catalog Formats](./catalog-formats.md) or create your own [Custom Formatter](../guides/custom-formatter.md). ## orderBy @@ -422,9 +422,9 @@ Note that using `` as a string token in any other path-based config set Default value: `["@lingui/core", "i18n"]` -This setting specifies the module path for the exported `i18n` object. The first value in the array is the module path, and the second is the name of the import. This configuration is essential for [macros](/ref/macro) that need to reference the global `i18n` object. +This setting specifies the module path for the exported `i18n` object. The first value in the array is the module path, and the second is the name of the import. This configuration is essential for [macros](./macro.mdx) that need to reference the global `i18n` object. -You only need to set this value if you use custom object created using [`setupI18n`](/ref/core#setupi18n): +You only need to set this value if you use custom object created using [`setupI18n`](./core.md#setupi18n): For example, if you have a custom module that exports the `i18n` object: @@ -450,7 +450,7 @@ import { myI18n } from "./custom-i18n-config"; } ``` -In more advanced scenarios, you may need to change the module from which the [`Trans`](/ref/macro#trans) or [`useLingui`](/ref/macro#uselingui) macros are imported: +In more advanced scenarios, you may need to change the module from which the [`Trans`](./macro.mdx#trans) or [`useLingui`](./macro.mdx#uselingui) macros are imported: ```jsx import { Trans, useLingui } from "./custom-config"; @@ -479,7 +479,7 @@ Extractors it's the way to customize which extractor you want for your codebase. } ``` -See the [Custom Extractor](/guides/custom-extractor) guide for instructions on creating your own extractor. +See the [Custom Extractor](../guides/custom-extractor.md) guide for instructions on creating your own extractor. ## macro.corePackage diff --git a/website/docs/ref/core.md b/website/docs/ref/core.md index fc18380f2..7c5022eec 100644 --- a/website/docs/ref/core.md +++ b/website/docs/ref/core.md @@ -37,7 +37,7 @@ const translation = i18n._("Hello World"); ``` :::info Advanced -If you prefer not to use the global `i18n` instance and want to set up your own, you can utilize the [`setupI18n`](#setupi18n) method. Additionally, you'll need to configure the [`runtimeConfigModule`](/ref/conf#runtimeconfigmodule) to ensure that macros work properly. +If you prefer not to use the global `i18n` instance and want to set up your own, you can utilize the [`setupI18n`](#setupi18n) method. Additionally, you'll need to configure the [`runtimeConfigModule`](./conf.md#runtimeconfigmodule) to ensure that macros work properly. ::: ## Class `i18n()` {#i18n} @@ -99,9 +99,9 @@ i18n.load({ ``` :::tip -Don't write catalogs manually. The code above is an example of message catalogs. In real applications, messages are loaded from external message catalogs generated by the [`compile`](/ref/cli#compile) command or by using tools such as [Vite Plugin](/ref/vite-plugin), [Webpack Loader](/ref/loader), or [Metro Transformer](/ref/metro-transformer). +Don't write catalogs manually. The code above is an example of message catalogs. In real applications, messages are loaded from external message catalogs generated by the [`compile`](./cli.md#compile) command or by using tools such as [Vite Plugin](./vite-plugin.md), [Webpack Loader](./loader.md), or [Metro Transformer](./metro-transformer.mdx). -Formatting of messages as strings (e.g: `"My name is {name}"`) works in development only, when messages are parsed on the fly. In production, however, messages must be compiled using the [`compile`](/ref/cli#compile) command. +Formatting of messages as strings (e.g: `"My name is {name}"`) works in development only, when messages are parsed on the fly. In production, however, messages must be compiled using the [`compile`](./cli.md#compile) command. Here's how the same example would look in a real application: @@ -208,7 +208,7 @@ i18n._({ }); ``` -Read more about [Message Descriptor](/ref/macro#core-macros). +Read more about [Message Descriptor](./macro.mdx#core-macros). ### `i18n.t(...)` {#i18n.t} @@ -279,7 +279,7 @@ Initialize and return a new `I18n` instance. Typically, you should call this fun :::info You typically don't need to set up your own `i18n` instance. In most cases, you can use the global `i18n` object exported from `@lingui/core` directly. -However, if you need to do this, make sure to also configure the [`runtimeConfigModule`](/ref/conf#runtimeconfigmodule) to ensure macros work properly. +However, if you need to do this, make sure to also configure the [`runtimeConfigModule`](./conf.md#runtimeconfigmodule) to ensure macros work properly. ::: ```ts @@ -410,7 +410,7 @@ The `change` event is triggered **after** changing the locale or loading a new m ### `missing` -The `missing` event is triggered when a translation is requested using [`i18n._`](/ref/core#i18n._) that does not exist in the messages of the active locale.The event provides information about the locale and the missing message ID. +The `missing` event is triggered when a translation is requested using [`i18n._`](./core.md#i18n._) that does not exist in the messages of the active locale.The event provides information about the locale and the missing message ID. ```ts i18n.on("missing", (event) => { diff --git a/website/docs/ref/extractor-vue.md b/website/docs/ref/extractor-vue.md index fd3d6e9c1..b050498a7 100644 --- a/website/docs/ref/extractor-vue.md +++ b/website/docs/ref/extractor-vue.md @@ -32,5 +32,5 @@ export default defineConfig({ ## See Also -- [Message Extraction](/guides/message-extraction) -- [Custom Extractor](/guides/custom-extractor) +- [Message Extraction](../guides/message-extraction.md) +- [Custom Extractor](../guides/custom-extractor.md) diff --git a/website/docs/ref/loader.md b/website/docs/ref/loader.md index a610b9c70..f881be252 100644 --- a/website/docs/ref/loader.md +++ b/website/docs/ref/loader.md @@ -1,6 +1,6 @@ # Webpack Loader -The `@lingui/loader` is a Webpack loader for Lingui message catalogs. It offers an alternative to the [`lingui compile`](/ref/cli#compile) and compiles catalogs on the fly. +The `@lingui/loader` is a Webpack loader for Lingui message catalogs. It offers an alternative to the [`lingui compile`](./cli.md#compile) and compiles catalogs on the fly. It enables you to `import` `.po` files directly, instead of running `lingui compile` and `import`ing the resulting JavaScript (or TypeScript) files. @@ -39,5 +39,5 @@ const { messages } = (await import(`@lingui/loader!./locales/${locale}/messages. ## See Also -- [Dynamic Loading of Message Catalogs](/guides/dynamic-loading-catalogs) -- [Catalog Formats](/ref/catalog-formats) +- [Dynamic Loading of Message Catalogs](../guides/dynamic-loading-catalogs.md) +- [Catalog Formats](./catalog-formats.md) diff --git a/website/docs/ref/macro.mdx b/website/docs/ref/macro.mdx index 25f46fe37..d01b42652 100644 --- a/website/docs/ref/macro.mdx +++ b/website/docs/ref/macro.mdx @@ -5,7 +5,7 @@ description: Transform JavaScript objects and JSX elements into ICU MessageForma # Macros -Lingui Macro provides powerful macros to transform JavaScript objects and JSX elements into [ICU MessageFormat](/guides/message-format) messages at compile time. It provides a more efficient and developer-friendly way to handle internationalization in your project. +Lingui Macro provides powerful macros to transform JavaScript objects and JSX elements into [ICU MessageFormat](../guides/message-format.md) messages at compile time. It provides a more efficient and developer-friendly way to handle internationalization in your project. The benefits of using macros: @@ -19,7 +19,7 @@ There are two types of macros: [Core Macros](#core-macros) (JS) and [React Macro ## Core Macros -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._`](/ref/core#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._`](./core.md#i18n._) call: ```js import { t } from "@lingui/core/macro"; @@ -54,7 +54,7 @@ type MessageDescriptor = { The `id` is the message ID and is the only parameter required. The `id` and `message` are extracted into the message catalog. Only `id` and `values` are used at runtime, all other attributes are removed from the production code for size optimization. -You don't need to specify the ID manually. By default, Macro will automatically create a short ID from your message. However, you can explicitly specify a custom ID. Read more about [Explicit vs Generated IDs](/guides/explicit-vs-generated-ids). +You don't need to specify the ID manually. By default, Macro will automatically create a short ID from your message. However, you can explicitly specify a custom ID. Read more about [Explicit vs Generated IDs](../guides/explicit-vs-generated-ids.md). ### `t` @@ -113,7 +113,7 @@ const message = i18n._( ``` :::info -By default the `i18n` object is imported from [`@lingui/core`](/ref/core). If you are using a custom instance of the `i18n` object, you need to set [`runtimeConfigModule`](/ref/conf#runtimeconfigmodule) or pass a custom instance to [`t`](/ref/macro#t). +By default the `i18n` object is imported from [`@lingui/core`](./core.md). If you are using a custom instance of the `i18n` object, you need to set [`runtimeConfigModule`](./conf.md#runtimeconfigmodule) or pass a custom instance to [`t`](./macro.mdx#t). ::: It's also possible to pass custom `id` and `comment` for translators by calling `t` macro with a message descriptor: @@ -193,7 +193,7 @@ const message = i18n._( Choose the plural forms used in your source code based on the pluralization rules of your source locale. ::: -If you need to add variables in plural form, you can use template string literals. This time you don't need the [`t`](/ref/macro#t) macro, because template strings are transformed automatically: +If you need to add variables in plural form, you can use template string literals. This time you don't need the [`t`](./macro.mdx#t) macro, because template strings are transformed automatically: ```js import { plural } from "@lingui/core/macro"; @@ -368,7 +368,7 @@ const message = t({ ### `defineMessage` / `msg` {#definemessage} -The `defineMessage` (alias: `msg`) macro allows to define a message for later use. It has the same signature as `t` and returns a `MessageDescriptor` that you can pass to `i18n._` to get a translated string at any time later. This is useful for [Lazy Translations](/guides/lazy-translations). +The `defineMessage` (alias: `msg`) macro allows to define a message for later use. It has the same signature as `t` and returns a `MessageDescriptor` that you can pass to `i18n._` to get a translated string at any time later. This is useful for [Lazy Translations](../guides/lazy-translations.md). In other words, `t` returns a translated string at the time when it's called, while `msg` returns a `MessageDescriptor` that can produce translated strings later: @@ -420,7 +420,7 @@ type MacroMessageDescriptor = { }; ``` -Either the `id` or `message` property is required. `id` is a custom message ID. If it isn't set, the `message` (and `context` if present) will be used to generate an ID. Read more about [Explicit vs Generated IDs](/guides/explicit-vs-generated-ids). +Either the `id` or `message` property is required. `id` is a custom message ID. If it isn't set, the `message` (and `context` if present) will be used to generate an ID. Read more about [Explicit vs Generated IDs](../guides/explicit-vs-generated-ids.md). ```js import { defineMessage } from "@lingui/core/macro"; @@ -501,7 +501,7 @@ const message = /*i18n*/ { ## React Macros -React (JSX) Macros are used in JSX elements and are transformed into the [`Trans`](/ref/react#trans) component imported from the [`@lingui/react`](/ref/react) package. +React (JSX) Macros are used in JSX elements and are transformed into the [`Trans`](./react.md#trans) component imported from the [`@lingui/react`](./react.md) package. ### `Trans` @@ -528,7 +528,7 @@ Available Props: #### `id` -Each message in the catalog is identified by a message ID. While macro uses message (and `context` property if provided) to generate the ID, it's possible to provide custom ID. Read more about [Explicit vs Generated IDs](/guides/explicit-vs-generated-ids). +Each message in the catalog is identified by a message ID. While macro uses message (and `context` property if provided) to generate the ID, it's possible to provide custom ID. Read more about [Explicit vs Generated IDs](../guides/explicit-vs-generated-ids.md). ```jsx import { Trans } from "@lingui/react/macro"; @@ -542,11 +542,11 @@ import { Trans } from "@lingui/react"; #### `comment` -Comment for translators to give them additional information about the message. It will be visible in the [TMS](/tools/introduction) if it is supported, and in the [catalog format](/ref/catalog-formats). It will be removed from production code. +Comment for translators to give them additional information about the message. It will be visible in the [TMS](../tools/introduction.md) if it is supported, and in the [catalog format](./catalog-formats.md). It will be removed from production code. #### `context` -Allows to extract the same messages with different IDs. It is useful when the same message has different meanings in different contexts. See [Context](/guides/explicit-vs-generated-ids#context) for more details. +Allows to extract the same messages with different IDs. It is useful when the same message has different meanings in different contexts. See [Context](../guides/explicit-vs-generated-ids.md#context) for more details. Similarly to [`comment`](#comment), it will be added to the message catalog, visible in TMS and will be removed from the production code: @@ -585,7 +585,7 @@ Components and HTML tags are replaced by dummy indexed tags (`<0>`) which ha #### `render` -Custom render callback to render translation. This prop is passed directly to the [`Trans`](/ref/react#trans) component from the [`@lingui/react`](/ref/react) package. +Custom render callback to render translation. This prop is passed directly to the [`Trans`](./react.md#trans) component from the [`@lingui/react`](./react.md) package. ### `Plural` @@ -706,7 +706,7 @@ The select cases except `other` should be prefixed with underscore: `_male` or ` ### `useLingui` -The `useLingui` React macro gives access to a [`t`](/ref/macro#t) macro that is bound to the local `i18n` object passed from the React context. +The `useLingui` React macro gives access to a [`t`](./macro.mdx#t) macro that is bound to the local `i18n` object passed from the React context. It returns an object with the following content: @@ -767,14 +767,14 @@ function getColors() { ``` :::tip -There is an [ESLint Plugin](/ref/eslint-plugin) rule designed to check for this misuse: [`t-call-in-function`](https://github.com/lingui/eslint-plugin/blob/main/docs/rules/t-call-in-function.md). +There is an [ESLint Plugin](./eslint-plugin.md) rule designed to check for this misuse: [`t-call-in-function`](https://github.com/lingui/eslint-plugin/blob/main/docs/rules/t-call-in-function.md). ::: -A better option would be to use the [Lazy Translations](/guides/lazy-translations) pattern. +A better option would be to use the [Lazy Translations](../guides/lazy-translations.md) pattern. ### Global `i18n` Instance -When you use the [`t`](#t) macro (or [`plural`](#plural), [`select`](#select), [`selectOrdinal`](#selectordinal)), it uses a global [`i18n`](/ref/core#i18n) instance. While this generally works, there are situations, such as server-side rendering (SSR) applications, where it may not be the best solution. +When you use the [`t`](#t) macro (or [`plural`](#plural), [`select`](#select), [`selectOrdinal`](#selectordinal)), it uses a global [`i18n`](./core.md#i18n) instance. While this generally works, there are situations, such as server-side rendering (SSR) applications, where it may not be the best solution. 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: diff --git a/website/docs/ref/metro-transformer.mdx b/website/docs/ref/metro-transformer.mdx index 1ba30f49f..e6933d687 100644 --- a/website/docs/ref/metro-transformer.mdx +++ b/website/docs/ref/metro-transformer.mdx @@ -5,7 +5,7 @@ description: Use Lingui with React Native and compile your message catalogs on t # Metro Transformer -[Metro bundler](https://metrobundler.dev/) is a JavaScript bundler used in React Native apps. The `@lingui/metro-transformer` offers an alternative to the [`lingui compile`](/ref/cli#compile) command: a transformer that enables Metro to compile `.po` files on the fly. +[Metro bundler](https://metrobundler.dev/) is a JavaScript bundler used in React Native apps. The `@lingui/metro-transformer` offers an alternative to the [`lingui compile`](./cli.md#compile) command: a transformer that enables Metro to compile `.po` files on the fly. The transformer enables you to `import` `.po` files directly, instead of running `lingui compile` and `import`ing the resulting JavaScript (or TypeScript) files. @@ -111,5 +111,5 @@ Whenever you make a change to the Lingui config file (this should not happen oft ## See Also -- [React Native i18n Tutorial](/tutorials/react-native) +- [React Native i18n Tutorial](../tutorials/react-native.md) - [Lingui React Native Example App](https://github.com/lingui/js-lingui/tree/main/examples/react-native) diff --git a/website/docs/ref/react.md b/website/docs/ref/react.md index 1d03bf3f0..7a331fd86 100644 --- a/website/docs/ref/react.md +++ b/website/docs/ref/react.md @@ -132,12 +132,12 @@ The `useLingui` hook provides access to the Lingui context. It returns an object | Key | Type | Description | | ------------------ | --------------------- | ----------------------------------------------------------------------- | | `i18n` | `I18n` | The `I18n` object instance that you passed to `I18nProvider` | -| `_` | `I18n[_]` | Reference to the [`i18n._`](/ref/core#i18n._) function, explained below | +| `_` | `I18n[_]` | Reference to the [`i18n._`](./core.md#i18n._) function, explained below | | `defaultComponent` | `React.ComponentType` | The same `defaultComponent` you passed to `I18nProvider`, if provided | -Components that use `useLingui` hook will re-render when locale and / or catalogs change. However, the reference to the `i18n` object is stable and doesn't change between re-renders. This can lead to unexpected behavior with memoization (see [memoization pitfall](/guides/lazy-translations#memoization-pitfall)). +Components that use `useLingui` hook will re-render when locale and / or catalogs change. However, the reference to the `i18n` object is stable and doesn't change between re-renders. This can lead to unexpected behavior with memoization (see [memoization pitfall](../guides/lazy-translations.md#memoization-pitfall)). -To alleviate the issue, `useLingui` provides the `_` function, which is the same as [`i18n._`](/ref/core#i18n._) but _its reference changes_ with each update of the Lingui context. Thanks to that, you can safely use this `_` function as a hook dependency: +To alleviate the issue, `useLingui` provides the `_` function, which is the same as [`i18n._`](./core.md#i18n._) but _its reference changes_ with each update of the Lingui context. Thanks to that, you can safely use this `_` function as a hook dependency: ```jsx import React from "react"; @@ -156,7 +156,7 @@ const CurrentLocale = () => { ``` :::tip -There is a [macro version](/ref/macro#uselingui) of the `useLingui` hook which supports all features of the [`t` macro](/ref/macro#t) and uses the runtime `useLingui` hook (from `@lingui/react`) under the hood: +There is a [macro version](./macro.mdx#uselingui) of the `useLingui` hook which supports all features of the [`t` macro](./macro.mdx#t) and uses the runtime `useLingui` hook (from `@lingui/react`) under the hood: ```jsx import { useLingui } from "@lingui/react/macro"; @@ -177,7 +177,7 @@ You also can safely use the returned `t` function in a dependency array of React The `@lingui/react` package provides the `Trans` component for rendering translations in your application. It is a low-level component that allows you to render translations with dynamic values and components. :::caution -While this component is available, you will likely find [Macros](/ref/macro) to be more convenient and developer-friendly. Macros simplify the translation process and reduce boilerplate code. +While this component is available, you will likely find [Macros](./macro.mdx) to be more convenient and developer-friendly. Macros simplify the translation process and reduce boilerplate code. ::: This section serves as a reference for those who prefer to use the components directly. @@ -193,7 +193,7 @@ This section serves as a reference for those who prefer to use the components di The `values` and `components` props allow to pass dynamic values and components used for formatting the translation. In addition, the `comment` prop provides context to translators, helping them to understand the intent behind the message. :::tip -Import the [`Trans`](/ref/macro#trans) macro instead if you use macros. It will be transformed into the runtime `Trans` component automatically: +Import the [`Trans`](./macro.mdx#trans) macro instead if you use macros. It will be transformed into the runtime `Trans` component automatically: ```jsx import { Trans } from "@lingui/react/macro"; @@ -240,7 +240,7 @@ const MyComponent = () => { #### Plurals -If for some reason you cannot use [Macros](/ref/macro), you can render plurals using the simple `Trans` component by passing the [ICU MessageFormat](/guides/message-format) string as the `message` prop: +If for some reason you cannot use [Macros](./macro.mdx), you can render plurals using the simple `Trans` component by passing the [ICU MessageFormat](../guides/message-format.md) string as the `message` prop: ```jsx import React from "react"; diff --git a/website/docs/ref/swc-plugin.md b/website/docs/ref/swc-plugin.md index 6626a07f1..604112b87 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 [Lingui Macros](/ref/macro). +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](./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) @@ -105,7 +105,7 @@ You can configure the plugin by passing the `runtimeModules` option. This option ] ``` -For more details, refer to the [Runtime Configuration](/ref/conf#runtimeconfigmodule) section of the documentation. +For more details, refer to the [Runtime Configuration](./conf.md#runtimeconfigmodule) section of the documentation. ### Strip Non-Essential Fields diff --git a/website/docs/ref/vite-plugin.md b/website/docs/ref/vite-plugin.md index e806e5bfb..9bf616e86 100644 --- a/website/docs/ref/vite-plugin.md +++ b/website/docs/ref/vite-plugin.md @@ -20,7 +20,7 @@ Install `@lingui/vite-plugin` as a development dependency: npm install --save-dev @lingui/vite-plugin ``` -For a complete installation guide, see [Installation and Setup](/installation#vite). +For a complete installation guide, see [Installation and Setup](../installation.mdx#vite). ## Usage @@ -59,5 +59,5 @@ const { messages } = await import(`./locales/${language}.json?lingui`); ## See Also -- [Dynamic Loading](/guides/dynamic-loading-catalogs) +- [Dynamic Loading](../guides/dynamic-loading-catalogs.md) - [Dynamic Import in Vite](https://vitejs.dev/guide/features.html#dynamic-import) diff --git a/website/docs/releases/migration-3.md b/website/docs/releases/migration-3.md index f55c42a55..d0fbf563a 100644 --- a/website/docs/releases/migration-3.md +++ b/website/docs/releases/migration-3.md @@ -14,24 +14,24 @@ Minimal required versions are: ### `@lingui/react` -- `` render-prop component was removed in favor of [`useLingui`](/ref/react#uselingui) hook. -- In [`I18nProvider`](/ref/react#i18nprovider), `defaultRender` prop was renamed to `defaultComponent`, and now only accepts Custom Components -- In [`Trans`](/ref/react#trans), `defaults` prop was renamed to `message` and `description` to `comment`. -- In [`Trans`](/ref/react#trans), `render` prop only accepts render-prop function which is used to render translation. -- In [`Trans`](/ref/react#trans), new prop `component` accepts React component which is used to render translation. -- In [`Trans`](/ref/react#trans), `components` is now an object, not an array. When using the low level API, it allows to name the component placeholders: +- `` render-prop component was removed in favor of [`useLingui`](../ref/react.md#uselingui) hook. +- In [`I18nProvider`](../ref/react.md#i18nprovider), `defaultRender` prop was renamed to `defaultComponent`, and now only accepts Custom Components +- In [`Trans`](../ref/react.md#trans), `defaults` prop was renamed to `message` and `description` to `comment`. +- In [`Trans`](../ref/react.md#trans), `render` prop only accepts render-prop function which is used to render translation. +- In [`Trans`](../ref/react.md#trans), new prop `component` accepts React component which is used to render translation. +- In [`Trans`](../ref/react.md#trans), `components` is now an object, not an array. When using the low level API, it allows to name the component placeholders: ```jsx }} /> ``` -- `NumberFormat` and `DateFormat` components were removed. Import `i18n` from `@lingui/core` package and use [`i18n.date()`](/ref/core#i18n.date) and [`i18n.number()`](/ref/core#i18n.number) instead. +- `NumberFormat` and `DateFormat` components were removed. Import `i18n` from `@lingui/core` package and use [`i18n.date()`](../ref/core.md#i18n.date) and [`i18n.number()`](../ref/core.md#i18n.number) instead. #### Removed `I18nProvider` declarative API -LinguiJS started as a React library. After `@lingui/core` package was introduced, there were two ways how to switch active locales and manage catalogs in React: either using [`I18nProvider`](/ref/react#i18nprovider) declarative API or using `setupI18n` imperative API. +LinguiJS started as a React library. After `@lingui/core` package was introduced, there were two ways how to switch active locales and manage catalogs in React: either using [`I18nProvider`](../ref/react.md#i18nprovider) declarative API or using `setupI18n` imperative API. -In the same spirit as `@apollo/react` and `react-redux`, the [`I18nProvider`](/ref/react#i18nprovider) is simplified and accepts `i18n` manager, which must be created manually: +In the same spirit as `@apollo/react` and `react-redux`, the [`I18nProvider`](../ref/react.md#i18nprovider) is simplified and accepts `i18n` manager, which must be created manually: ```diff import { I18nProvider } from '@lingui/react' @@ -66,21 +66,21 @@ In the same spirit as `@apollo/react` and `react-redux`, the [`I18nProvider`](/r ``` :::caution Note - If you decide to use custom `i18n` instance, you also need to set [`runtimeConfigModule`](/ref/conf#runtimeconfigmodule). Macros automatically import `i18n` instance and must be aware of correct import path. + If you decide to use custom `i18n` instance, you also need to set [`runtimeConfigModule`](../ref/conf.md#runtimeconfigmodule). Macros automatically import `i18n` instance and must be aware of correct import path. ::: - `i18n.t`, `i18n.plural`, `i18n.select` and `i18n.selectOrdinal` methods were removed in favor of macros. - `i18n.use` was removed. Using two locales at the same time isn't common use-case and can be solved in user land by having two instances of `i18n` object. -- Signature of [`i18n._`](/ref/core#i18n._) method has changed. The third parameter now accepts default message in `message` prop, instead of `defaults`: +- Signature of [`i18n._`](../ref/core.md#i18n._) method has changed. The third parameter now accepts default message in `message` prop, instead of `defaults`: ```diff - i18n._('Welcome / Greetings', { name: 'Joe' }, { defaults: "Hello {name}" }) + i18n._('Welcome / Greetings', { name: 'Joe' }, { message: "Hello {name}" }) ``` -- [`i18n._`](/ref/core#i18n._) also accepts a message descriptor as a first parameter: +- [`i18n._`](../ref/core.md#i18n._) also accepts a message descriptor as a first parameter: ```diff i18n._({ @@ -90,9 +90,9 @@ In the same spirit as `@apollo/react` and `react-redux`, the [`I18nProvider`](/r }) ``` -#### [`i18n.load`](/ref/core#i18n.load) loads a catalog for a single locale +#### [`i18n.load`](../ref/core.md#i18n.load) loads a catalog for a single locale -`i18n` manager is the single source of truth and there's no need to keep all catalogs loaded outside this object. To make loading easier, [`i18n.load`](/ref/core#i18n.load) now accepts catalog for a single locale or multiple catalogs at once. +`i18n` manager is the single source of truth and there's no need to keep all catalogs loaded outside this object. To make loading easier, [`i18n.load`](../ref/core.md#i18n.load) now accepts catalog for a single locale or multiple catalogs at once. ```diff import { i18n } from "@lingui/core" @@ -103,7 +103,7 @@ In the same spirit as `@apollo/react` and `react-redux`, the [`I18nProvider`](/r ``` :::caution Note -You can still use [`i18n.load`](/ref/core#i18n.load) to load all catalogs at once: +You can still use [`i18n.load`](../ref/core.md#i18n.load) to load all catalogs at once: ```jsx // i18n.js @@ -121,7 +121,7 @@ i18n.load({ ### `@lingui/macro` -- [`plural`](/ref/macro#plural), [`select`](/ref/macro#select) and [`selectOrdinal`](/ref/macro#selectordinal) accepts value as a first parameter: +- [`plural`](../ref/macro.mdx#plural), [`select`](../ref/macro.mdx#select) and [`selectOrdinal`](../ref/macro.mdx#selectordinal) accepts value as a first parameter: ```diff - plural({ value, one: "# book", other: "# books" }) @@ -135,7 +135,7 @@ i18n.load({ ### Whitespace -Whitespace handling in plugins had few bugs. By fixing them, there might be few backward incompatible changes. It's advised to run [`extract`](/ref/cli#extract) and inspect changes in catalogs (if any). +Whitespace handling in plugins had few bugs. By fixing them, there might be few backward incompatible changes. It's advised to run [`extract`](../ref/cli.md#extract) and inspect changes in catalogs (if any). 1. Spaces before `{variables}` in JSX aren't preserved. This is how React handles whitespaces in JSX. Leading whitespace is always removed: @@ -182,7 +182,7 @@ Plugins are replaced with macros. Presets are removed completely because they ar } ``` -2. Import [`Trans`](/ref/macro#trans), [`Plural`](/ref/macro#plural-1), [`Select`](/ref/macro#select-1) and [`SelectOrdinal`](/ref/macro#selectordinal-1) from `@lingui/macro`: +2. Import [`Trans`](../ref/macro.mdx#trans), [`Plural`](../ref/macro.mdx#plural-1), [`Select`](../ref/macro.mdx#select-1) and [`SelectOrdinal`](../ref/macro.mdx#selectordinal-1) from `@lingui/macro`: ```diff - import { Trans } from "@lingui/react" @@ -190,7 +190,7 @@ Plugins are replaced with macros. Presets are removed completely because they ar ``` :::caution Note - If you used [`Trans`](/ref/macro#trans) component without children, then keep the import from `@lingui/react`: + If you used [`Trans`](../ref/macro.mdx#trans) component without children, then keep the import from `@lingui/react`: ```jsx import { Trans } from "@lingui/react"; @@ -215,9 +215,9 @@ Plugins are replaced with macros. Presets are removed completely because they ar ## New features -### [`i18n.load`](/ref/core#i18n.load) +### [`i18n.load`](../ref/core.md#i18n.load) -[`i18n.load`](/ref/core#i18n.load) can now accept one catalog for specific locale. Useful for incremental loading of catalogs. +[`i18n.load`](../ref/core.md#i18n.load) can now accept one catalog for specific locale. Useful for incremental loading of catalogs. ```jsx import { i18n } from "@lingui/core"; @@ -235,7 +235,7 @@ i18n.load("cs", require("./locale/cs/messages")); ### `i18n.on('change', callback)` -Event [`change`](/ref/core#change) is fired anytime new catalogs are loaded or when locale is activated. +Event [`change`](../ref/core.md#change) is fired anytime new catalogs are loaded or when locale is activated. ### Native TypeScript support diff --git a/website/docs/releases/migration-4.md b/website/docs/releases/migration-4.md index 84549105f..7a6fc5a45 100644 --- a/website/docs/releases/migration-4.md +++ b/website/docs/releases/migration-4.md @@ -37,7 +37,7 @@ This includes components provided by Lingui, such as `Trans` or `Plural` and als If the changes to the `I18nProvider` pose a problem to you, please open an issue and explain what the problem is. Additionally, you can keep using the [v3 implementation](https://github.com/lingui/js-lingui/blob/31dcab5a9a8f88bfa8b3a2c7cd12aa2d908a1d80/packages/react/src/I18nProvider.tsx#L58) by copying it into your code base and using that instead. -No migration steps are necessary for components provided by Lingui, such as `Trans` or `Plural`. However, if you rendered translations in React components using the `t` macro, you need to be sure that the `useLingui` hook is called in the component, as seen [here](/ref/react#uselingui). +No migration steps are necessary for components provided by Lingui, such as `Trans` or `Plural`. However, if you rendered translations in React components using the `t` macro, you need to be sure that the `useLingui` hook is called in the component, as seen [here](../ref/react.md#uselingui). ### Hash-based message ID generation and Context feature @@ -87,7 +87,7 @@ Enabling this mode will swap the logic, and the formatter will treat all message You can read more about the motivation behind this change in the [original RFC](https://github.com/lingui/js-lingui/issues/1360) -Also, we've added a possibility to provide a context for the message. For more details, see the [Providing a context for a message](/guides/explicit-vs-generated-ids#context). +Also, we've added a possibility to provide a context for the message. For more details, see the [Providing a context for a message](../guides/explicit-vs-generated-ids.md#context). The context feature affects the message ID generation and adds the `msgctxt` parameter in case of the PO catalog format extraction. @@ -117,7 +117,7 @@ You will need to make some changes as this is a misuse of the library that actua Due to the changes caused by hash-based message ID feature described earlier, this approach will no longer work. -Instead, please use [recommended](/guides/lazy-translations) pattern for such translations: +Instead, please use [recommended](../guides/lazy-translations.md) pattern for such translations: ```tsx import { msg } from "@lingui/macro"; @@ -202,7 +202,7 @@ declare type ExtractorType = { } ``` -Read more about custom extractors on the [Advanced: Custom Extractor](/guides/custom-extractor) page. +Read more about custom extractors on the [Advanced: Custom Extractor](../guides/custom-extractor.md) page. ### Configuration migrations for deprecated options were deleted diff --git a/website/docs/releases/migration-5.md b/website/docs/releases/migration-5.md index 05716c247..24ad3a2e3 100644 --- a/website/docs/releases/migration-5.md +++ b/website/docs/releases/migration-5.md @@ -2,7 +2,7 @@ This guide will help you migrate from Lingui 4.x to 5.x. It covers the most important changes and breaking changes. -Need to upgrade an older project to v4 first? See our [older migration guide](/releases/migration-4). +Need to upgrade an older project to v4 first? See our [older migration guide](./migration-4.md). If you're looking for 4.x documentation, you can find it [here](https://js-lingui-m3z8jlqt6-crowdin.vercel.app/). @@ -134,9 +134,9 @@ Simply add `babel-plugin-lingui-macro` to your Babel configuration to get starte ## Introducing `useLingui` Macro -The new [`useLingui`](/ref/macro#uselingui) macro simplifies handling non-JSX messages within React components. +The new [`useLingui`](../ref/macro.mdx#uselingui) macro simplifies handling non-JSX messages within React components. -Previously, you had to combine the `t` or `msg` macro with the `i18n` instance returned by the [`useLingui`](/ref/react#uselingui) hook: +Previously, you had to combine the `t` or `msg` macro with the `i18n` instance returned by the [`useLingui`](../ref/react.md#uselingui) hook: ```jsx import { t, msg } from "@lingui/macro"; @@ -196,7 +196,7 @@ Now: msgid "Hello {0} {value}" ``` -This feature is enabled by default and can be disabled by setting `printPlaceholdersInComments` to `false` in the [configuration](/ref/catalog-formats#po). +This feature is enabled by default and can be disabled by setting `printPlaceholdersInComments` to `false` in the [configuration](../ref/catalog-formats.md#po). ## Compiled Messages Structure Changes @@ -229,7 +229,7 @@ The structure of compiled messages has been changed to make them more predictabl ### Migration -You'll need to re-[`compile`](/ref/cli#compile) your messages in the new format. +You'll need to re-[`compile`](../ref/cli.md#compile) your messages in the new format. :::info Read more about the motivation and discuss the changes in the related [issue](https://github.com/lingui/js-lingui/issues/2043). diff --git a/website/docs/tools/crowdin.md b/website/docs/tools/crowdin.md index fdfe9aa6e..22ced8376 100644 --- a/website/docs/tools/crowdin.md +++ b/website/docs/tools/crowdin.md @@ -53,7 +53,7 @@ Decide who will translate your content: Source strings are pulled automatically and are always up to date for your translators. Translated content is automatically pushed to your repository as a request. -![Automatically pull source strings to Crowdin and push translated content to your repository](/img/docs/Crowdin__js-lingui-vcs.png) +![Automatically pull source strings to Crowdin and push translated content to your repository](../assets/Crowdin__js-lingui-vcs.png) ## CLI diff --git a/website/docs/tools/introduction.md b/website/docs/tools/introduction.md index 411dd4270..a697bc29e 100644 --- a/website/docs/tools/introduction.md +++ b/website/docs/tools/introduction.md @@ -14,7 +14,7 @@ It becomes increasingly difficult and time-consuming to manage the back-and-fort ### Regular Workflow -![Translation workflow *without* sync and collaboration tool](/img/docs/without-collaboration-tool.svg) +![Translation workflow *without* sync and collaboration tool](../assets/without-collaboration-tool.svg) This is the most basic workflow which involves sending the `.po` files to your translators (usually by email) and syncing them back manually into your application. @@ -22,7 +22,7 @@ This workflow is manageable when your application is still quite small, doesn't ### Sync & Collaboration Tool Workflow -![Translation workflow *with* sync and collaboration tool](/img/docs/with-collaboration-tool.svg) +![Translation workflow *with* sync and collaboration tool](../assets/with-collaboration-tool.svg) When the amount of text to translate increases, and the number of target languages grows, it becomes more efficient to use a sync and collaboration tool to assist you with the management of your team of translators, and co-evolution between your code and the translated files. @@ -39,5 +39,5 @@ Instead of manually sending and receiving many emails and fixing the inconsisten ## Available Tools -- [Crowdin](/tools/crowdin) -- [Translation.io](/tools/translation-io) +- [Crowdin](./crowdin.md) +- [Translation.io](./translation-io.md) diff --git a/website/docs/tools/translation-io.md b/website/docs/tools/translation-io.md index 838a7be04..26d2a1322 100644 --- a/website/docs/tools/translation-io.md +++ b/website/docs/tools/translation-io.md @@ -48,7 +48,7 @@ Sometimes you have no choice but to confront your translators with HTML or inter ### Smart Plural Management -Lingui allows to write plurals using the [ICU MessageFormat](/guides/message-format) syntax that looks like this: +Lingui allows to write plurals using the [ICU MessageFormat](../guides/message-format.md) syntax that looks like this: ```icu-message-format {count, plural, =0 {No messages} @@ -62,7 +62,7 @@ That's why plural syntaxes are deconstructed to make translation easier, and the If the target language has more plural forms than the source language, examples are also provided to the translator, as it may be unclear which plural form the `few` or `other` keyword refers to in that specific target language (for instance, Czech has three plural forms). -![Smart Plural Management on Translation.io](/img/docs/translation-lingui-plural-forms.png) +![Smart Plural Management on Translation.io](../assets/translation-lingui-plural-forms.png) ### Efficient Search @@ -108,7 +108,7 @@ The configuration file looks like this: } ``` -The synchronization will then be part of the [`extract`](/ref/cli#extract) command. +The synchronization will then be part of the [`extract`](../ref/cli.md#extract) command. ### Add the following scripts diff --git a/website/docs/tutorials/javascript.md b/website/docs/tutorials/javascript.md index 81b9c01c0..936e20069 100644 --- a/website/docs/tutorials/javascript.md +++ b/website/docs/tutorials/javascript.md @@ -13,8 +13,8 @@ If you're looking for a working solution, check out the [Vanilla JS example](htt ## Installing Lingui -1. Follow the [Installation and Setup](/installation) page for initial setup. -2. Install the [`@lingui/core`](/ref/core) package, which is responsible for translation and message catalog handling. +1. Follow the [Installation and Setup](../installation.mdx) page for initial setup. +2. Install the [`@lingui/core`](../ref/core.md) package, which is responsible for translation and message catalog handling. ## Setting up i18n @@ -31,14 +31,14 @@ i18n.activate("en"); The `messages.js` is generated by the Lingui CLI and contains compiled message catalogs. :::tip -Alternatively, you can load catalogs dynamically using the [`@lingui/loader`](/ref/loader) or [`@lingui/vite-plugin`](/ref/vite-plugin) without the need to import compiled messages manually. +Alternatively, you can load catalogs dynamically using the [`@lingui/loader`](../ref/loader.md) or [`@lingui/vite-plugin`](../ref/vite-plugin.md) without the need to import compiled messages manually. ::: ## Localizing Your App -To localize your application, you need to wrap your localizable texts in [Macros](/ref/macro). Lingui provides a set of Core Macros that transform tagged template literals and can be used in any JavaScript context. +To localize your application, you need to wrap your localizable texts in [Macros](../ref/macro.mdx). Lingui provides a set of Core Macros that transform tagged template literals and can be used in any JavaScript context. -Let's wrap our text in the [`t`](/ref/macro#t) macro: +Let's wrap our text in the [`t`](../ref/macro.mdx#t) macro: ```js import { t } from "@lingui/core/macro"; @@ -51,7 +51,7 @@ t`My name is ${name}`; // becomes "Je m'appelle Fred" ``` -Plurals and selections are possible using [`plural`](/ref/macro#plural) and [`select`](/ref/macro#select) macros: +Plurals and selections are possible using [`plural`](../ref/macro.mdx#plural) and [`select`](../ref/macro.mdx#select) macros: ```js import { plural } from "@lingui/core/macro"; @@ -85,12 +85,12 @@ select(gender, { ``` :::caution -All Core Macros cannot be used at the module level. They must be used within a component or function. See the [Macros](/ref/macro#using-macros) documentation for more information. +All Core Macros cannot be used at the module level. They must be used within a component or function. See the [Macros](../ref/macro.mdx#using-macros) documentation for more information. ::: ## See Also -- [Message Extraction Guide](/guides/message-extraction) -- [Pluralization Guide](/guides/plurals) -- [Dynamic Loading of Message Catalogs](/guides/dynamic-loading-catalogs) -- [Lingui CLI Reference](/ref/cli) +- [Message Extraction Guide](../guides/message-extraction.md) +- [Pluralization Guide](../guides/plurals.md) +- [Dynamic Loading of Message Catalogs](../guides/dynamic-loading-catalogs.md) +- [Lingui CLI Reference](../ref/cli.md) diff --git a/website/docs/tutorials/react-native.md b/website/docs/tutorials/react-native.md index 86b4a2117..eebbf4bbc 100644 --- a/website/docs/tutorials/react-native.md +++ b/website/docs/tutorials/react-native.md @@ -7,7 +7,7 @@ description: Learn how to add internationalization to a React Native application In this tutorial, we'll learn how to add internationalization to an existing application in React Native. -The React Native tutorial is similar to the one for [React](/tutorials/react) 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. +The React Native tutorial is similar to the one for [React](./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. :::tip Example If you're looking for a working solution, check out the [React Native example](https://github.com/lingui/js-lingui/tree/main/examples/react-native). This example application shows a complete setup using Lingui and React Native. @@ -20,9 +20,9 @@ If some `Intl` feature is not supported by your runtime, you can [polyfill it](# ## Installing Lingui -1. Follow the [Installation and Setup](/installation?transpiler=babel) page for initial setup (for Babel). -2. Install the [`@lingui/core`](/ref/core) and [`@lingui/react`](/ref/react) packages. -3. _(optional)_ Install and configure the [`@lingui/metro-transformer`](/ref/metro-transformer) package that enables Metro to compile `.po` files on the fly. +1. Follow the [Installation and Setup](../installation.mdx) page for initial setup (for Babel). +2. Install the [`@lingui/core`](../ref/core.md) and [`@lingui/react`](../ref/react.md) packages. +3. _(optional)_ Install and configure the [`@lingui/metro-transformer`](../ref/metro-transformer.mdx) package that enables Metro to compile `.po` files on the fly. :::caution Warning With the dependencies installed and set up, before running your app, please clear your Metro bundler cache with `npx expo start -c` or `npx react-native start --reset-cache` (if you do not use Expo). @@ -94,12 +94,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`](/ref/react#trans) component or the [`useLingui`](/ref/react#uselingui) hook together with the [`t`](/ref/macro#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`](/ref/react#i18nprovider) will re-render, making sure the UI shows the correct translations. +There are several ways to render translations: You may use the [`Trans`](../ref/react.md#trans) component or the [`useLingui`](../ref/react.md#uselingui) hook together with the [`t`](../ref/macro.mdx#t) or [`msg`](../ref/macro.mdx#definemessage) macros. When you change the active locale or load new messages, all components that consume the Lingui context provided by [`I18nProvider`](../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](/tutorials/react). +Not surprisingly, this part isn't too different from the [React tutorial](./react.md). -First, we need to wrap our app with [`I18nProvider`](/ref/react#i18nprovider) and then we can use the [`Trans`](/ref/macro#trans) macro to translate the screen heading: +First, we need to wrap our app with [`I18nProvider`](../ref/react.md#i18nprovider) and then we can use the [`Trans`](../ref/macro.mdx#trans) macro to translate the screen heading: ```tsx import { I18nProvider, TransRenderProps } from "@lingui/react"; @@ -122,10 +122,10 @@ const DefaultComponent = (props: TransRenderProps) => { ``` :::tip Hint -We're importing the default `i18n` object from `@lingui/core`. Read more about the `i18n` object in the [reference](/ref/core). +We're importing the default `i18n` object from `@lingui/core`. Read more about the `i18n` object in the [reference](../ref/core.md). ::: -Translating the heading is done. Now, let's translate the `title` prop in the `