diff --git a/website/docs/guides/message-extraction.md b/website/docs/guides/message-extraction.md index c024cbf17..c7b9e15e7 100644 --- a/website/docs/guides/message-extraction.md +++ b/website/docs/guides/message-extraction.md @@ -28,7 +28,7 @@ t({ const jsx = Hi, my name is {name}; ``` -For more usage examples, refer to the [macro documentation](/docs/ref/macro.md). +For more usage examples, refer to the [macro documentation](/docs/ref/macro.mdx). ### Non-Macro usages diff --git a/website/docs/guides/plurals.md b/website/docs/guides/plurals.md index 79d660de4..e01493414 100644 --- a/website/docs/guides/plurals.md +++ b/website/docs/guides/plurals.md @@ -40,7 +40,7 @@ If you want to specify a message for an exact number, use [`exact matches`](/gui > Funny fact for non-English speakers: In English, 0 uses plural form too, _0 books_. -Under the hood, [`plural`](/docs/ref/macro.md#plural) is replaced with low-level [`i18n._`](/docs/ref/core.md#i18n._). For production, the above example will become: +Under the hood, [`plural`](/docs/ref/macro.mdx#plural) is replaced with low-level [`i18n._`](/docs/ref/core.md#i18n._). For production, the above example will become: ```js i18n._({ diff --git a/website/docs/misc/react-intl.md b/website/docs/misc/react-intl.md index 52d645283..1c700029e 100644 --- a/website/docs/misc/react-intl.md +++ b/website/docs/misc/react-intl.md @@ -67,7 +67,7 @@ However, let's go yet another level deeper. ## Macros for component-based message syntax -[Lingui](https://github.com/lingui/js-lingui) provides macros [`@lingui/macro`](/docs/ref/macro.md) which automatically generates a message syntax. +[Lingui](https://github.com/lingui/js-lingui) provides macros [`@lingui/macro`](/docs/ref/macro.mdx) which automatically generates a message syntax. Let's go back to the previous example: @@ -75,7 +75,7 @@ Let's go back to the previous example:

Read the documentation.

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

@@ -83,9 +83,9 @@ All we need to do is to wrap the message in a [`Trans`](/docs/ref/macro.md#trans

``` -The macro then parses the [`Trans`](/docs/ref/macro.md#trans) macro children and generates `message` and `components` props automatically in the form described in the previous section. +The macro then parses the [`Trans`](/docs/ref/macro.mdx#trans) macro children and generates `message` and `components` props automatically in the form described in the previous section. -This is extremely useful when adding i18n to an existing project. All we need is to wrap all messages in [`Trans`](/docs/ref/macro.md#trans) macro. +This is extremely useful when adding i18n to an existing project. All we need is to wrap all messages in [`Trans`](/docs/ref/macro.mdx#trans) macro. Let's compare it with react-intl solution to see the difference: @@ -130,7 +130,7 @@ Let's take a look at the original example from react-intl docs: /> ``` -Using [Lingui](https://github.com/lingui/js-lingui) macros, we could combine [`Trans`](/docs/ref/macro.md#trans), [`Plural`](/docs/ref/macro.md#plural-1) components and [`i18n.number`](/docs/ref/core.md#i18n.number) macro: +Using [Lingui](https://github.com/lingui/js-lingui) macros, we could combine [`Trans`](/docs/ref/macro.mdx#trans), [`Plural`](/docs/ref/macro.mdx#plural-1) components and [`i18n.number`](/docs/ref/core.md#i18n.number) macro: ```jsx diff --git a/website/docs/ref/catalog-formats.md b/website/docs/ref/catalog-formats.md index 3b0e7ccab..08d46b1f7 100644 --- a/website/docs/ref/catalog-formats.md +++ b/website/docs/ref/catalog-formats.md @@ -81,8 +81,8 @@ msgstr[1] "Case number {anotherCount}" Note that this format comes with several caveats and should therefore only be used if using ICU plurals in PO files is not an option: -- Nested/multiple plurals in one message as shown in [`plural`](/docs/ref/macro.md#plural) are not supported as it cannot be expressed with gettext plurals. Messages containing nested/multiple formats will not be output correctly. -- [`select`](/docs/ref/macro.md#select) and [`selectOrdinal`](/docs/ref/macro.md#selectordinal) cannot be expressed with gettext plurals, but the original ICU format is still saved to the `msgid`/`msgstr` properties. To disable the warning that this might not be the expected behavior, include `{ disableSelectWarning: true }` in the [`format`](/docs/ref/conf.md#format) options. +- Nested/multiple plurals in one message as shown in [`plural`](/docs/ref/macro.mdx#plural) are not supported as it cannot be expressed with gettext plurals. Messages containing nested/multiple formats will not be output correctly. +- [`select`](/docs/ref/macro.mdx#select) and [`selectOrdinal`](/docs/ref/macro.mdx#selectordinal) cannot be expressed with gettext plurals, but the original ICU format is still saved to the `msgid`/`msgstr` properties. To disable the warning that this might not be the expected behavior, include `{ disableSelectWarning: true }` in the [`format`](/docs/ref/conf.md#format) options. - Source/development languages with more than two plurals could experience difficulties when no custom IDs are used, as gettext cannot have more than two plurals cases identifying an item (`msgid` and `msgid_plural`). - Gettext doesn't support plurals for negative and fractional numbers even though some languages have special rules for these cases. diff --git a/website/docs/ref/conf.md b/website/docs/ref/conf.md index 70d00a8d1..435ca6654 100644 --- a/website/docs/ref/conf.md +++ b/website/docs/ref/conf.md @@ -403,7 +403,7 @@ import { myI18n } from "./custom-i18n-config"; // "runtimeConfigModule": ["./custom-i18n-config", "myI18n"] ``` -In some advanced cases you may also need to change the module from which [Trans](/docs/ref/macro.md#trans) is imported. To do that, pass an object to `runtimeConfigModule`: +In some advanced cases you may also need to change the module from which [Trans](/docs/ref/macro.mdx#trans) is imported. To do that, pass an object to `runtimeConfigModule`: ```jsx // If you import `i18n` object from custom module like this: diff --git a/website/docs/ref/macro.md b/website/docs/ref/macro.mdx similarity index 93% rename from website/docs/ref/macro.md rename to website/docs/ref/macro.mdx index 9377c9495..b9c5bc4c4 100644 --- a/website/docs/ref/macro.md +++ b/website/docs/ref/macro.mdx @@ -5,48 +5,55 @@ description: Transform JavaScript objects and JSX elements into ICU MessageForma # Macros -The `@lingui/macro` package transforms JavaScript objects and JSX elements into ICU MessageFormat messages. You can use [Babel macros](#babel) or [SWC plugin](#swc) for this transformation. +The `@lingui/macro` package transforms JavaScript objects and JSX elements into ICU MessageFormat messages. You can use Babel macros or SWC plugin for this transformation. ## Installation -Installing `@lingui/macro` can be done in two ways, depending on whether you use Babel or SWC as your compiler. +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; -### Babel + + + Babel macros require [babel-plugin-macros](https://github.com/kentcdodds/babel-plugin-macros) to work. If you use a framework (for example GatsbyJS, Create React App > 2.0) you might already have macros enabled. Otherwise, install it as any other Babel plugin: + - Install `babel-plugin-macros` as a dev dependency and `@lingui/macro` as dependency: -Babel macros require [babel-plugin-macros](https://github.com/kentcdodds/babel-plugin-macros) to work. If you use a framework (for example GatsbyJS, Create React App > 2.0) you might already have macros enabled. Otherwise, install it as any other Babel plugin: + ```bash npm2yarn + npm install --save-dev babel-plugin-macros + npm install --save @lingui/macro + ``` -1. Install `babel-plugin-macros` as a dev dependency and `@lingui/macro` as dependency: + - Add `macros` to the top of plugins section in your Babel config: -```bash npm2yarn -npm install --save-dev babel-plugin-macros -npm install --save @lingui/macro -``` - -2. Add `macros` to the top of plugins section in your Babel config: - -```json -{ - "plugins": ["macros"] -} -``` + ```json + { + "plugins": ["macros"] + } + ``` -### SWC + When using any preset, first check if it includes the `macros` plugin. These presets already includes the `macros` plugin: `react-scripts`. -For those who prefer not to use Babel, Lingui offers the [SWC Plugin](/docs/ref/swc-plugin.md) as an alternative. + + + - Install `@lingui/swc-plugin` as a dev dependency and `@lingui/macro` as dependency: -1. Install `@lingui/swc-plugin` as a dev dependency and `@lingui/macro` as dependency: + ```bash npm2yarn + npm install --save-dev @lingui/swc-plugin + npm install --save @lingui/macro + ``` -```bash npm2yarn -npm install --save-dev @lingui/swc-plugin -npm install --save @lingui/macro -``` + - [Add necessary configurations](/docs/ref/swc-plugin.md#usage). -2. [Add necessary configurations](/docs/ref/swc-plugin.md#usage). + + :::note It's recommended to install `@lingui/macro` package as a production dependency rather than development one to avoid `import/no-extraneous-dependencies` errors in ESLint. ::: +:::tip +Don't miss the [Lingui ESLint Plugin](/docs/ref/eslint-plugin.md) which can help you find and prevent common l10n mistakes in your code. +::: + ## Overview The advantages of using macros are: @@ -89,10 +96,10 @@ i18n._( ``` :::note -By default, the `i18n` object is imported from `@lingui/core`. If you use a custom instance of `i18n` object, you need to set [`runtimeConfigModule`](/docs/ref/conf.md#runtimeconfigmodule) or pass a custom instance to [`t`](/docs/ref/macro.md#t). +By default, the `i18n` object is imported from `@lingui/core`. If you use a custom instance of `i18n` object, you need to set [`runtimeConfigModule`](/docs/ref/conf.md#runtimeconfigmodule) or pass a custom instance to [`t`](/docs/ref/macro.mdx#t). ::: -The only exception is [`defineMessage`](/docs/ref/macro.md#definemessage) which is transformed into message descriptor. In other words, the message isn't translated directly and can be used anytime later: +The only exception is [`defineMessage`](/docs/ref/macro.mdx#definemessage) which is transformed into message descriptor. In other words, the message isn't translated directly and can be used anytime later: ```jsx import { i18n } from "@lingui/core" @@ -311,7 +318,7 @@ const msg = /*i18n*/ { These macros can be used in any context (e.g. outside JSX). All JS macros are transformed into a _Message Descriptor_ wrapped inside of [`i18n._`](/docs/ref/core.md#i18n._) call. :::note -By default, the `i18n` object is imported from `@lingui/core`. If you use a custom instance of `i18n` object, you need to set [`runtimeConfigModule`](/docs/ref/conf.md#runtimeconfigmodule) or pass a custom instance to [`t`](/docs/ref/macro.md#t). +By default, the `i18n` object is imported from `@lingui/core`. If you use a custom instance of `i18n` object, you need to set [`runtimeConfigModule`](/docs/ref/conf.md#runtimeconfigmodule) or pass a custom instance to [`t`](/docs/ref/macro.mdx#t). ::: _Message Descriptor_ is an object with message ID, default message and other parameters. [`i18n._`](/docs/ref/core.md#i18n._) accepts message descriptors and performs translation and formatting: @@ -482,7 +489,7 @@ const message = i18n._( ); ``` -If you need to add variables to plural form, you can use template string literals. This time [`t`](/docs/ref/macro.md#t) macro isn't required as template strings are transformed automatically: +If you need to add variables to plural form, you can use template string literals. This time [`t`](/docs/ref/macro.mdx#t) macro isn't required as template strings are transformed automatically: ```js import { plural } from "@lingui/macro"; @@ -897,7 +904,7 @@ Components and HTML tags are replaced with dummy indexed tags (`<0>`) which > MessageFormat: `{arg, plural, ...forms}` -Props of [`Plural`](/docs/ref/macro.md#plural-1) macro are transformed into [`plural`](/docs/guides/message-format.md) format. +Props of [`Plural`](/docs/ref/macro.mdx#plural-1) macro are transformed into [`plural`](/docs/guides/message-format.md) format. ```jsx import { Plural } from "@lingui/macro"; diff --git a/website/docs/ref/react.md b/website/docs/ref/react.md index 62642d316..c0603c0b2 100644 --- a/website/docs/ref/react.md +++ b/website/docs/ref/react.md @@ -137,7 +137,7 @@ const CurrentLocale = () => { ## Components -The `@lingui/react` package provides `Trans` component to render translations. However, you're more likely to use [macros](/docs/ref/macro.md) instead because they are more convenient and easier to use. +The `@lingui/react` package provides `Trans` component to render translations. However, you're more likely to use [macros](/docs/ref/macro.mdx) instead because they are more convenient and easier to use. This section is intended for reference purposes. @@ -149,7 +149,7 @@ This section is intended for reference purposes. :::important -Import [`Trans`](/docs/ref/macro.md#trans) macro instead of [`Trans`](#trans) component if you use macros: +Import [`Trans`](/docs/ref/macro.mdx#trans) macro instead of [`Trans`](#trans) component if you use macros: ```jsx import { Trans } from "@lingui/macro"; @@ -189,7 +189,7 @@ It's also possible to use `Trans` component directly without macros. In that cas ### Plurals -If you cannot use [@lingui/macro](/docs/ref/macro.md) for some reason, you can render plurals using the plain Trans component like this: +If you cannot use [@lingui/macro](/docs/ref/macro.mdx) for some reason, you can render plurals using the plain Trans component like this: ```jsx import React from "react"; diff --git a/website/docs/ref/swc-plugin.md b/website/docs/ref/swc-plugin.md index f821502c7..e044ed240 100644 --- a/website/docs/ref/swc-plugin.md +++ b/website/docs/ref/swc-plugin.md @@ -7,7 +7,7 @@ description: Use Lingui Macros in your SWC project [SWC](https://swc.rs/) is an extensible Rust-based platform for the next generation of fast developer tools. -If you're using SWC in your project, you can opt for the `@lingui/swc-plugin`. This plugin, designed for SWC, is a Rust version of [LinguiJS Macro](/docs/ref/macro.md). +If you're using SWC in your project, you can opt for the `@lingui/swc-plugin`. This plugin, designed for SWC, is a Rust version of [LinguiJS Macro](/docs/ref/macro.mdx). [![npm-version](https://img.shields.io/npm/v/@lingui/swc-plugin?logo=npm&cacheSeconds=1800)](https://www.npmjs.com/package/@lingui/swc-plugin) [![npm-downloads](https://img.shields.io/npm/dt/@lingui/swc-plugin?cacheSeconds=500)](https://www.npmjs.com/package/@lingui/swc-plugin) diff --git a/website/docs/ref/vite-plugin.md b/website/docs/ref/vite-plugin.md index 995b015e7..54e94cdc9 100644 --- a/website/docs/ref/vite-plugin.md +++ b/website/docs/ref/vite-plugin.md @@ -60,5 +60,5 @@ See the [guide about dynamic loading catalogs](/docs/guides/dynamic-loading-cata See [Vite's official documentation](https://vitejs.dev/guide/features.html#dynamic-import) for more info about Vite dynamic imports. :::note -You also need to set up [babel-plugin-macros](https://github.com/kentcdodds/babel-plugin-macros) to support [macros](/docs/ref/macro.md). +You also need to set up [babel-plugin-macros](https://github.com/kentcdodds/babel-plugin-macros) to support [macros](/docs/ref/macro.mdx). ::: diff --git a/website/docs/releases/migration-3.md b/website/docs/releases/migration-3.md index 7d688f43d..d6c269c74 100644 --- a/website/docs/releases/migration-3.md +++ b/website/docs/releases/migration-3.md @@ -121,7 +121,7 @@ i18n.load({ ### `@lingui/macro` -- [`plural`](/docs/ref/macro.md#plural), [`select`](/docs/ref/macro.md#select) and [`selectOrdinal`](/docs/ref/macro.md#selectordinal) accepts value as a first parameter: +- [`plural`](/docs/ref/macro.mdx#plural), [`select`](/docs/ref/macro.mdx#select) and [`selectOrdinal`](/docs/ref/macro.mdx#selectordinal) accepts value as a first parameter: ```diff - plural({ value, one: "# book", other: "# books" }) @@ -182,7 +182,7 @@ npm install --dev @lingui/macro babel-plugin-macros } ``` -2. Import [`Trans`](/docs/ref/macro.md#trans), [`Plural`](/docs/ref/macro.md#plural-1), [`Select`](/docs/ref/macro.md#select-1) and [`SelectOrdinal`](/docs/ref/macro.md#selectordinal-1) from `@lingui/macro`: +2. Import [`Trans`](/docs/ref/macro.mdx#trans), [`Plural`](/docs/ref/macro.mdx#plural-1), [`Select`](/docs/ref/macro.mdx#select-1) and [`SelectOrdinal`](/docs/ref/macro.mdx#selectordinal-1) from `@lingui/macro`: ```diff - import { Trans } from "@lingui/react" @@ -190,7 +190,7 @@ npm install --dev @lingui/macro babel-plugin-macros ``` :::caution Note - If you used [`Trans`](/docs/ref/macro.md#trans) component without children, then keep the import from `@lingui/react`: + If you used [`Trans`](/docs/ref/macro.mdx#trans) component without children, then keep the import from `@lingui/react`: ```jsx import { Trans } from "@lingui/react"; diff --git a/website/docs/tutorials/explicit-vs-generated-ids.md b/website/docs/tutorials/explicit-vs-generated-ids.md index 89794a074..5f4f0e6e9 100644 --- a/website/docs/tutorials/explicit-vs-generated-ids.md +++ b/website/docs/tutorials/explicit-vs-generated-ids.md @@ -71,7 +71,7 @@ msgstr "LinguiJS przyklad" ## Using ID generated from a message -### With [`Trans`](/docs/ref/macro.md#trans) macro +### With [`Trans`](/docs/ref/macro.mdx#trans) macro ```jsx import { Trans } from "@lingui/macro"; @@ -92,7 +92,7 @@ function render() { } ``` -In the example code above, the content of [`Trans`](/docs/ref/macro.md#trans) is transformed into a message in MessageFormat syntax. By default, this message is used for generating the ID. Considering the example above, the catalog would contain these entries: +In the example code above, the content of [`Trans`](/docs/ref/macro.mdx#trans) is transformed into a message in MessageFormat syntax. By default, this message is used for generating the ID. Considering the example above, the catalog would contain these entries: ```js const catalog = [ @@ -170,7 +170,7 @@ const ex2 = { ## Using custom ID -### With [`Trans`](/docs/ref/macro.md#trans) +### With [`Trans`](/docs/ref/macro.mdx#trans) If you're using custom IDs in your project, add `id` prop to i18n components: @@ -197,7 +197,7 @@ The messages with IDs `msg.header` and `msg.hello` will be extracted with their ### With non-JSX macro -If you're using custom IDs in your project, call the [`msg`](/docs/ref/macro.md#definemessage) function with a message descriptor object, passing the ID using the `id` property: +If you're using custom IDs in your project, call the [`msg`](/docs/ref/macro.mdx#definemessage) function with a message descriptor object, passing the ID using the `id` property: ```jsx import { msg } from "@lingui/macro"; @@ -207,7 +207,7 @@ msg({ id: "msg.greeting", message: `Hello World` }); Message `msg.greeting` will be extracted with default value `Hello World`. -For all other js macros ([`plural`](/docs/ref/macro.md#plural), [`select`](/docs/ref/macro.md#select), [`selectOrdinal`](/docs/ref/macro.md#selectordinal), use them inside [`msg`](/docs/ref/macro.md#definemessage) macro to pass ID (in this case, `'msg.caption'`). +For all other js macros ([`plural`](/docs/ref/macro.mdx#plural), [`select`](/docs/ref/macro.mdx#select), [`selectOrdinal`](/docs/ref/macro.mdx#selectordinal), use them inside [`msg`](/docs/ref/macro.mdx#definemessage) macro to pass ID (in this case, `'msg.caption'`). ```jsx import { msg, plural } from "@lingui/macro"; diff --git a/website/docs/tutorials/javascript.md b/website/docs/tutorials/javascript.md index 33df358d9..e58e298ee 100644 --- a/website/docs/tutorials/javascript.md +++ b/website/docs/tutorials/javascript.md @@ -58,7 +58,7 @@ i18n.activate("en"); ## Localizing your app -Once that is done, we can go ahead and use it! Wrap you text in [`t`](/docs/ref/macro.md#t) macro and pass it to [`i18n._()`](/docs/ref/core.md#i18n._) method: +Once that is done, we can go ahead and use it! Wrap you text in [`t`](/docs/ref/macro.mdx#t) macro and pass it to [`i18n._()`](/docs/ref/core.md#i18n._) method: ```js import { t } from "@lingui/macro"; diff --git a/website/docs/tutorials/react-native.md b/website/docs/tutorials/react-native.md index 72830f5c3..ac0045fb6 100644 --- a/website/docs/tutorials/react-native.md +++ b/website/docs/tutorials/react-native.md @@ -5,7 +5,7 @@ description: Learn how to add internationalization to a React Native application # Internationalization of React Native apps -In this tutorial, we'll learn how to add internationalization to an existing application in React Native. Before going further, please follow the [setup guide](/docs/tutorials/setup-react.md) for installation and setup instructions. +In this tutorial, we'll learn how to add internationalization to an existing application in React Native. Before going further, please follow the [setup guide](/docs/tutorials/setup-react.mdx) for installation and setup instructions. The React Native tutorial is similar to the one for [React](/docs/tutorials/react.md) and we highly recommend you read that one first because it goes into greater detail on many topics. Here, we will only cover parts that are relevant for React Native. @@ -88,12 +88,12 @@ As you can see, it's a simple mailbox application with only one screen. ## Internationalization in React (Native) :::tip TL;DR -There are several ways to render translations: You may use the [`Trans`](/docs/ref/react.md#trans) component or the [`useLingui`](/docs/ref/react.md#uselingui) hook together with the [`t`](/docs/ref/macro.md#t) or [`msg`](/ref/macro#definemessage) macros. When you change the active locale or load new messages, all components that consume the Lingui context provided by [`I18nProvider`](/docs/ref/react.md#i18nprovider) will re-render, making sure the UI shows the correct translations. +There are several ways to render translations: You may use the [`Trans`](/docs/ref/react.md#trans) component or the [`useLingui`](/docs/ref/react.md#uselingui) hook together with the [`t`](/docs/ref/macro.mdx#t) or [`msg`](/ref/macro#definemessage) macros. When you change the active locale or load new messages, all components that consume the Lingui context provided by [`I18nProvider`](/docs/ref/react.md#i18nprovider) will re-render, making sure the UI shows the correct translations. ::: Not surprisingly, this part isn't too different from the [React tutorial](/docs/tutorials/react.md). -First, we need to wrap our app with [`I18nProvider`](/docs/ref/react.md#i18nprovider) and then we can use the [`Trans`](/docs/ref/macro.md#trans) macro to translate the screen heading: +First, we need to wrap our app with [`I18nProvider`](/docs/ref/react.md#i18nprovider) and then we can use the [`Trans`](/docs/ref/macro.mdx#trans) macro to translate the screen heading: ```tsx import { I18nProvider } from '@lingui/react' @@ -115,7 +115,7 @@ i18n.loadAndActivate({ locale: "en", messages }); We're importing the default `i18n` object from `@lingui/core`. Read more about the `i18n` object in the [reference](/ref/core). ::: -Translating the heading is done. Now, let's translate the `title` prop in the `