diff --git a/website/docs/ref/macro.mdx b/website/docs/ref/macro.mdx index 62ea98b74..7d3de28fa 100644 --- a/website/docs/ref/macro.mdx +++ b/website/docs/ref/macro.mdx @@ -1,11 +1,21 @@ --- -title: Lingui Macro package +title: Lingui Macros description: Transform JavaScript objects and JSX elements into ICU MessageFormat messages --- # Macros -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. +Lingui Macro provides powerful macros to transform JavaScript objects and JSX elements into [ICU MessageFormat](/docs/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: + +- You don't have to learn ICU MessageFormat syntax. You always use familiar JS and JSX code. +- Components and functions are type checked. +- Short IDs are generated for your messages. +- Additional validation of plural rules is performed during transformation. +- Non-essential data is removed from the production build (e.g. comments and default messages) to save a few bytes. + +There are two types of macros: [Core Macros](#core-macros) (JS) and [React Macros](#react-macros) (JSX). ## Installation @@ -17,35 +27,35 @@ import TabItem from "@theme/TabItem"; Lingui macros require `@lingui/babel-plugin-lingui-macro` or [babel-plugin-macros](https://github.com/kentcdodds/babel-plugin-macros) to work. -The recommended way is to use `@lingui/babel-plugin-lingui-macro` directly, but if you use a framework which is does not allow to change babel configuration (for example Create React App > 2.0), that frameworks might support `babel-plugin-macros` out of the box. +The recommended way is to use `@lingui/babel-plugin-lingui-macro` directly. If you are using a framework that doesn't allow you to change the Babel configuration (e.g. Create React App > 2.0), these frameworks may support `babel-plugin-macros` out of the box. -- Install `@lingui/babel-plugin-lingui-macro` as a dev dependency: +1. Install `@lingui/babel-plugin-lingui-macro` as a dev dependency: - ```bash npm2yarn - npm install --save-dev babel-plugin-macros - ``` + ```bash npm2yarn + npm install --save-dev @lingui/babel-plugin-lingui-macro + ``` -- Add `@lingui/babel-plugin-lingui-macro` to the top of plugins section in your Babel config: +2. Add `@lingui/babel-plugin-lingui-macro` to the top of the plugins section in your Babel config: - ```json - { - "plugins": ["@lingui/babel-plugin-lingui-macro"] - } - ``` + ```json + { + "plugins": ["@lingui/babel-plugin-lingui-macro"] + } + ``` -When using any preset, first check if it includes the `macros` plugin. These presets already includes the `macros` plugin: `react-scripts`. +When using a preset, first check if it includes the `macros` plugin. For example, `react-scripts` already includes the `macros` plugin. -- 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 production 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). @@ -54,94 +64,17 @@ When using any preset, first check if it includes the `macros` plugin. These pre 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: - -- You don't need to learn ICU MessageFormat syntax. You always use familiar JS and JSX code. -- Components and functions are type checked. -- Short ID generated for your messages. -- Additional validation of plural rules is performed during transformation. -- Non-essential data are removed from the production build (e.g. comments and default messages) to shave a few bytes. - -**JSX macros** are transformed to [`Trans`](/docs/ref/react.md#trans) component from [`@lingui/react`](/docs/ref/react.md): - -```jsx -import { Trans } from "@lingui/react/macro"; -Attachment {name} saved; - -// ↓ ↓ ↓ ↓ ↓ ↓ - -import { Trans } from "@lingui/react"; -; -``` +## Core Macros -**JS macros** (i.e. macros that looks like a simple JavaScript functions) are transformed into [`i18n._`](/docs/ref/core.md#i18n._) call. +Core (JS) Macros can be used in any JavaScript context (e.g. outside of JSX). All JS macros are transformed into a _Message Descriptor_ wrapped inside of [`i18n._`](/docs/ref/core.md#i18n._) call: -```jsx +```js import { t } from "@lingui/core/macro"; t`Attachment ${name} saved`; // ↓ ↓ ↓ ↓ ↓ ↓ import { i18n } from "@lingui/core"; - -i18n._( - /*i18n*/ { - id: "nwR43V", - message: "Attachment {name} saved", - values: { name }, - } -); -``` - -:::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.mdx#t). -::: - -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" -import { defineMessage } from "@lingui/core/macro" - -// define message -const message = defineMessage({ message: `Attachment ${name} saved` }) - -// translate it -i18n._(message) - -// ↓ ↓ ↓ ↓ ↓ ↓ - -import { i18n } from "@lingui/core" - -// define message -const message = /*i18n*/{ id: "nwR43V", message: "Attachment {name} saved", values: { name }}) - -// translate it -i18n._(message) -``` - -### Examples of JS macros - -```js -t`Refresh inbox`; - -// ↓ ↓ ↓ ↓ ↓ ↓ - -i18n._( - /*i18n*/ { - id: "EsCV2T", - message: "Refresh inbox", - } -); -``` - -```js -t`Attachment ${name} saved`; - -// ↓ ↓ ↓ ↓ ↓ ↓ - i18n._( /*i18n*/ { id: "nwR43V", @@ -151,177 +84,11 @@ i18n._( ); ``` -```js -t(customI18n)`Refresh inbox`; - -// ↓ ↓ ↓ ↓ ↓ ↓ - -customI18n._( - /*i18n*/ { - id: "EsCV2T", - message: "Refresh inbox", - } -); -``` - -```js -t(customI18n)`Attachment ${name} saved`; - -// ↓ ↓ ↓ ↓ ↓ ↓ - -customI18n._( - /*i18n*/ { - id: "nwR43V", - message: "Attachment {name} saved", - values: { name }, - } -); -``` - -```js -plural(count, { - one: "# Message", - other: "# Messages", -}); - -// ↓ ↓ ↓ ↓ ↓ ↓ - -i18n._( - /*i18n*/ { - id: "4w2nim", - message: "{count, plural, one {# Message} other {# Messages}}", - values: { count }, - } -); -``` - -```js -t({ - id: "msg.refresh", - message: "Refresh inbox", -}); - -// ↓ ↓ ↓ ↓ ↓ ↓ - -i18n._( - /*i18n*/ { - id: "msg.refresh", - message: "Refresh inbox", - } -); -``` - -```js -t(customI18n)({ - id: "msg.refresh", - message: "Refresh inbox", -}); - -// ↓ ↓ ↓ ↓ ↓ ↓ - -customI18n._( - /*i18n*/ { - id: "msg.refresh", - message: "Refresh inbox", - } -); -``` - -```js -const msg = defineMessage`Refresh inbox`; - -// ↓ ↓ ↓ ↓ ↓ ↓ - -const msg = /*i18n*/ { - id: "EsCV2T", - message: "Refresh inbox", -}; -``` - -```js -const msg = defineMessage({ - id: "msg.refresh", - message: "Refresh inbox", -}); - -// ↓ ↓ ↓ ↓ ↓ ↓ - -const msg = /*i18n*/ { - id: "msg.refresh", - message: "Refresh inbox", -}; -``` - -```js -const msg = defineMessage({ - id: "msg.plural", - message: plural(count, { - one: "# Message", - other: "# Messages", - }), -}); - -// ↓ ↓ ↓ ↓ ↓ ↓ - -const msg = /*i18n*/ { - id: "msg.plural", - message: "{count, plural, one {# Message} other {# Messages}}", - values: { count }, -}; -``` - -### Examples of JSX macros - -```jsx -Attachment {name} saved - -// ↓ ↓ ↓ ↓ ↓ ↓ - - -``` - -```jsx - - -// ↓ ↓ ↓ ↓ ↓ ↓ - - -``` - -```jsx - - Refresh inbox - - -// ↓ ↓ ↓ ↓ ↓ ↓ - - -``` - -## Core macros - -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.mdx#t). +:::info `/*i18n*/` comment +In the example above you may notice the `/*i18n*/` comment in the macro output. This comment tells the extract plugin that the following object should be collected into the message catalog. ::: -_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: +_Message Descriptor_ is an object with a message ID, default message and other parameters: ```ts type MessageDescriptor = { @@ -332,15 +99,9 @@ type MessageDescriptor = { }; ``` -`id` is the message ID and the only required parameter. `id` and `message` are extracted to the message catalog. Only `id` and `values` are used at runtime, all other attributes are removed from production code for size optimization. +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 provide your ID manually. Macro will automatically create a short ID from your message. - -:::info Note -i18n comment - -In the examples below you might notice `/*i18n*/` comment in macro output. This comment tells the extract plugin that following object should be collected to message catalog. -::: +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](/docs/guides/explicit-vs-generated-ids.md). ### `t` @@ -379,7 +140,7 @@ const message = i18n._( ); ``` -In fact, any expression can be used inside template literal. However, only simple variables are referenced by name in a transformed message. All other expressions are referenced by numeric index: +In fact, any expression can be used inside template literal. However, only simple variables are referenced by name in a transformed message. All other expressions are referenced by their numeric index: ```js import { t } from "@lingui/core/macro"; @@ -408,8 +169,6 @@ const message = t(i18nCustom)`Hello World`; // ↓ ↓ ↓ ↓ ↓ ↓ import { i18nCustom } from "./lingui"; - -import { i18n } from "@lingui/core"; const message = i18nCustom._( /*i18n*/ { id: "mY42CM", @@ -418,6 +177,10 @@ const message = i18nCustom._( ); ``` +:::info +By default the `i18n` object is imported from [`@lingui/core`](/docs/ref/core.md). If you are using a custom instance of the `i18n` object, you need to set [`runtimeConfigModule`](/docs/ref/conf.md#runtimeconfigmodule) or pass a custom instance to [`t`](/docs/ref/macro.mdx#t). +::: + It's also possible to pass custom `id` and `comment` for translators by calling `t` macro with a message descriptor: ```jsx @@ -441,7 +204,7 @@ const message = i18n._( ); ``` -In this case the `message` is used as a default message and it's transformed as if it were wrapped in `t` macro. `message` also accepts any other macros: +In this case, `message` is used as the default message, and it's transformed as if it were wrapped in a `t` macro. `message` also accepts any other macros: ```js import { t } from "@lingui/core/macro"; @@ -464,11 +227,13 @@ const message = i18n._( ### `plural` +Pluralization is a common problem in i18n. Different languages have different rules for plural form (e.g. English has only `one` and `other`, while Czech has `one`, `few`, `many` and `other`). The `plural` macro is used to handle this. + ```ts plural(value: string | number, options: Object) ``` -`plural` macro is used for pluralization, e.g: messages which has different form based on counter. The first argument `value` determines the plural form. The second argument is an object with available plural forms. Plural form used in the source code depends on your source locale (e.g. English has only `one` and `other`). +The `value` specifies the plural form or cardinal number. The second argument, `options`, is an object with available plural forms: ```js import { plural } from "@lingui/core/macro"; @@ -489,7 +254,11 @@ const message = i18n._( ); ``` -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: +:::tip +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`](/docs/ref/macro.mdx#t) macro, because template strings are transformed automatically: ```js import { plural } from "@lingui/core/macro"; @@ -547,9 +316,7 @@ const message = i18n._( ); ``` -:::tip -This is just an example how macros can be combined to create a complex messages. However, simple is better because in the end it's the translator who's gonna have to translate these long and complex strings. -::: +This is just one example of how macros can be combined to create a complex message. However, simple is better, because in the end it's the translator who has to translate these long and complex strings. :::tip Use `plural` inside [`t`](#t) or [`defineMessage`](#definemessage) macro if you want to add custom `id`, `context` or `comment` for translators. @@ -569,11 +336,13 @@ const message = t({ ### `selectOrdinal` +SelectOrdinal is a variation of the [`plural`](#plural) macro. It's used to handle ordinal numbers (e.g. 1st, 2nd, 3rd, 4th, etc.). + ```ts selectOrdinal(value: string | number, options: Object) ``` -`selectOrdinal` macro is similar to [`plural`](#plural) but instead of using cardinal plural forms it uses ordinal forms: +The `value` specifies the ordinal number. The second argument, `options`, is an object with available ordinal forms: ```js import { selectOrdinal } from "@lingui/core/macro"; @@ -616,11 +385,13 @@ const message = t({ ### `select` +The `select` macro is used to handle different forms of a message based on a value. + ```ts select(value: string | number, options: Object) ``` -`select` macro works as a switch statement — it select one of the forms provided in `options` object which key matches exactly `value`: +It works like a switch statement - it selects one of the forms provided in the `options` object based on the `value`: ```js import { select } from "@lingui/core/macro"; @@ -660,25 +431,36 @@ const message = t({ ::: -### `defineMessage` alias: `msg` {#definemessage} +### `defineMessage` / `msg` {#definemessage} -`defineMessage` 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](/tutorials/react-patterns#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](/tutorials/react-patterns#lazy-translations). -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. +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: ```ts +import { i18n } from "@lingui/core"; import { defineMessage } from "@lingui/core/macro"; + +// define message const message = defineMessage`Hello World`; +// use it later +i18n._(message); + // ↓ ↓ ↓ ↓ ↓ ↓ +import { i18n } from "@lingui/core"; + const message = /*i18n*/ { id: "mY42CM", message: "Hello World", }; + +// use it later +i18n._(message); ``` -You also can use shorter alias of `defineMessage` macro: +You can also use a shorter alias of the `defineMessage` macro: ```ts import { msg } from "@lingui/core/macro"; @@ -692,7 +474,7 @@ const message = /*i18n*/ { }; ``` -`defineMessage` macro also supports `MacroMessageDescriptor` object as input. That can be used to provide additional information for message such as comment or context. +The `defineMessage` macro also supports a `MacroMessageDescriptor` object as input. This can be used to provide additional information for the message such as comment or context: ```ts type MacroMessageDescriptor = { @@ -703,7 +485,7 @@ type MacroMessageDescriptor = { }; ``` -Either `id` or `message` property is required. `id` is a custom message ID. If it isn't set, the `message` (and `context` if provided) are used for generating an ID. +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](/docs/guides/explicit-vs-generated-ids.md). ```js import { defineMessage } from "@lingui/core/macro"; @@ -720,15 +502,12 @@ const message = /*i18n*/ { }; ``` -`message` is the default message. Any JS macro can be used here. Template string literals don't need to be tagged with [`t`](#t). +The `message` is a default message. Any JS macro can be used here. Template string literals don't need to be tagged with [`t`](#t). ```js import { defineMessage } from "@lingui/core/macro"; - const name = "Joe"; - const message = defineMessage({ - comment: "Greetings on the welcome page", message: `Welcome, ${name}!`, }); @@ -736,7 +515,6 @@ const message = defineMessage({ const message = /*i18n*/ { id: "dgJjNB", - comment: "Greetings on the welcome page", message: "Welcome, {name}", values: { name, @@ -744,7 +522,7 @@ const message = /*i18n*/ { }; ``` -`comment` is a comment for translators. It's extracted to the message catalog and it gives translators extra information about the message. It's removed from the production code: +The `comment` is a comment for translators. It's extracted into the message catalog, and it gives translators additional information about the message. It's removed from the production code: ```js import { defineMessage } from "@lingui/core/macro"; @@ -763,7 +541,7 @@ const message = /*i18n*/ { ``` :::caution Note -In production build, the macro is stripped of `message`, `comment` and `context` properties: +In the production build, the macro is stripped of `message`, `comment` and `context` properties: ```js import { defineMessage } from "@lingui/core/macro"; @@ -788,85 +566,68 @@ const message = /*i18n*/ { ## React Macros -### `Trans` - -| Prop name | Type | Description | -| --------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------- | -| `id` | string | Custom message ID | -| `comment` | string | Comment for translators | -| `context` | string | Allows to extract the same messages with different IDs. See [Context](/docs/guides/explicit-vs-generated-ids.md#context) for more detail | - -[`Trans`](/docs/ref/react.md#trans) is the basic macro for static messages, messages with variables, but also for messages with inline markup: - -#### `id` +React (JSX) Macros are used in JSX elements and are transformed into the [`Trans`](/docs/ref/react.md#trans) component imported from the [`@lingui/react`](/docs/ref/react.md) package. -Each message in catalog is identified by **message ID**. +### `Trans` -While macro uses message (and `context` property if provided) to generate ID, it's possible to override it. +The `Trans` macro is used to translate static messages, messages with variables and messages with inline markup: ```jsx import { Trans } from "@lingui/react/macro"; -Attachment {name} saved.; +Refresh inbox; // ↓ ↓ ↓ ↓ ↓ ↓ import { Trans } from "@lingui/react"; -; +; ``` -#### `render` +Available Props: -Render prop function used to render translation. This prop is directly passed to [`Trans`](/docs/ref/react.md#trans) component from [`@lingui/react`](/docs/ref/react.md). See [rendering of translations](/docs/ref/react.md#rendering-translations) for more info. +| Prop Name | Type | Description | +| --------- | ------ | ------------------------------------------------------ | +| `id` | string | Custom message ID | +| `comment` | string | Comment for translators | +| `context` | string | Allows to extract the same messages with different IDs | +| `render` | func | Render prop function used to render translation | -#### `comment` - -Comment for translators to give them additional information about the message. It will be visible in the [TMS](/tools/introduction) if supported by it, and the [catalog format](/ref/catalog-formats). - -It's removed from the production code. - -#### `context` {#context-prop} - -Contextual information for translators. Similar to [`comment`](#comment) but also allows to extract the same messages with different IDs. It will be visible in the [TMS](/tools/introduction) if supported by it, and the [catalog format](/ref/catalog-formats). +#### `id` -It's removed from the production code. See [Context](/docs/guides/explicit-vs-generated-ids.md#context) for more details. +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](/docs/guides/explicit-vs-generated-ids.md). ```jsx import { Trans } from "@lingui/react/macro"; -Refresh inbox; +Attachment {name} saved.; // ↓ ↓ ↓ ↓ ↓ ↓ import { Trans } from "@lingui/react"; -; +; ``` -Lingui generates different IDs when `context` is provided: +#### `comment` -```jsx -import { Trans } from "@lingui/react/macro"; -right; -right; +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. -// ↓ ↓ ↓ ↓ ↓ ↓ +#### `context` -import { Trans } from "@lingui/react"; -; -; -``` +Allows to extract the same messages with different IDs. It is useful when the same message has different meanings in different contexts. See [Context](/docs/guides/explicit-vs-generated-ids.md#context) for more details. -Custom `id` is preserved: +Similarly to [`comment`](#comment), it will be added to the message catalog, visible in TMS and will be removed from the production code. ```jsx import { Trans } from "@lingui/react/macro"; -Attachment {name} saved.; +right; +right; // ↓ ↓ ↓ ↓ ↓ ↓ import { Trans } from "@lingui/react"; -; +; +; ``` -This macro is especially useful when message contains inline markup. +This macro is particularly useful if the message contains inline markup: ```jsx import { Trans } from "@lingui/react/macro"; @@ -877,34 +638,23 @@ import { Trans } from "@lingui/react/macro"; // ↓ ↓ ↓ ↓ ↓ ↓ -import { Trans } from "@lingui/react/macro"; +import { Trans } from "@lingui/react"; }} />; ``` -Components and HTML tags are replaced with dummy indexed tags (`<0>`) which has several advantages: +Components and HTML tags are replaced by dummy indexed tags (`<0>`) which has several advantages: -- both custom React components and built-in HTML tags are supported -- change of component props doesn't break the translation -- the message is extracted as a whole sentence (this seems to be obvious, but most i18n libs simply split message into pieces by tags and translate them separately) +- Both custom React components and built-in HTML tags are supported. +- Changing component props doesn't break translation. +- The message is extracted as a whole sentence (this seems to be obvious, but most i18n libs simply split the message into pieces by tags and translate them separately). -### `Plural` +#### `render` -| Prop name | Type | Description | -| ----------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | -| `value` | number | (required) Value is mapped to plural form below | -| `format` | string\|Object | Number format passed as options to [Intl.NumberFormat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/NumberFormat) | -| `offset` | number | Offset of value when calculating plural forms | -| `zero` | string | Form for empty `value` | -| `one` | string | _Singular_ form | -| `two` | string | _Dual_ form | -| `few` | string | _Paucal_ form | -| `many` | string | _Plural_ form | -| `other` | string | (required) general _plural_ form | -| `_` | string | Exact match form, corresponds to `=N` rule | +Render prop function used to render translation. This prop is passed directly to the [`Trans`](/docs/ref/react.md#trans) component from the [`@lingui/react`](/docs/ref/react.md) package. -> MessageFormat: `{arg, plural, ...forms}` +### `Plural` -Props of [`Plural`](/docs/ref/macro.mdx#plural-1) macro are transformed into [`plural`](/docs/guides/message-format.md) format. +The `Plural` JSX macro is used to handle plural forms. It's similar to the [`plural`](#plural) macro from the core macros, but it's used in JSX elements. ```jsx import { Plural } from "@lingui/react/macro"; @@ -916,7 +666,20 @@ import { Trans } from "@lingui/react"; ; ``` -`#` are formatted using `number` format. `format` prop is passed to this formatter. +Available Props: + +| Prop name | Type | Description | +| ----------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | +| `value` | number | (required) Value is mapped to plural form below | +| `format` | string\|Object | Number format passed as options to [Intl.NumberFormat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/NumberFormat) | +| `offset` | number | Offset of value when calculating plural forms | +| `zero` | string | Form for empty `value` | +| `one` | string | _Singular_ form | +| `two` | string | _Dual_ form | +| `few` | string | _Paucal_ form | +| `many` | string | _Plural_ form | +| `other` | string | (required) general _plural_ form | +| `_` | string | Exact match form, corresponds to `=N` rule | Exact matches in MessageFormat syntax are expressed as `=int` (e.g. `=0`), but in React this isn't a valid prop name. Therefore, exact matches are expressed as `_int` prop (e.g. `_0`). This is commonly used in combination with `offset` prop. `offset` affects only plural forms, not exact matches. @@ -946,7 +709,9 @@ import { Plural } from "@lingui/react/macro"; */ ``` -Use `` inside `` macro if you want to provide `id`, `context` or `comment`. +:::tip + +Use `` inside `` macro if you want to add custom `id`, `context` or `comment` for translators. ```jsx @@ -954,8 +719,24 @@ Use `` inside `` macro if you want to provide `id`, `context` or ``` +::: + ### `SelectOrdinal` +The `SelectOrdinal` JSX macro is used to handle ordinal numbers. It's similar to the [`selectOrdinal`](#selectordinal) macro from the core macros, but it's used in JSX elements. + +```jsx +import { SelectOrdinal } from "@lingui/react/macro"; + +// count == 1 -> 1st +// count == 2 -> 2nd +// count == 3 -> 3rd +// count == 4 -> 4th +; +``` + +Available Props: + | Prop name | Type | Description | | ----------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | `value` | number | (required) Value is mapped to plural form below | @@ -969,21 +750,9 @@ Use `` inside `` macro if you want to provide `id`, `context` or | `_` | string | Exact match form, correspond to `=N` rule. (e.g: `_0`, `_1`) | | `format` | string\|Object | Number format passed as options to [Intl.NumberFormat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/NumberFormat) | -> MessageFormat: `{arg, selectordinal, ...forms}` - -Props of `SelectOrdinal` macro are transformed into [`selectOrdinal`](/docs/guides/message-format.md) format: - -```jsx -import { SelectOrdinal } from "@lingui/react/macro"; - -// count == 1 -> 1st -// count == 2 -> 2nd -// count == 3 -> 3rd -// count == 4 -> 4th -; -``` +:::tip -Use `` inside `` macro if you want to provide `id`, `context` or `comment`. +Use `` inside `` macro if you want to add custom `id`, `context` or `comment` for translators. ```jsx @@ -991,20 +760,11 @@ Use `` inside `` macro if you want to provide `id`, `conte ``` -### `Select` - -| Prop name | Type | Description | -| --------- | ------ | --------------------------------------------------- | -| `value` | number | (required) Value determines which form is outputted | -| `other` | number | (required) Default, catch-all form | - -> MessageFormat: `{arg, select, ...forms}` - -:::note -The select cases except `other` should be prefixed with underscore: `_male` or `_female`. ::: -Props of `Select` macro are transformed into [`select`](/docs/guides/message-format.md) format: +### `Select` + +The `Select` JSX macro is used to handle different forms of a message based on a value. It's similar to the [`select`](#select) macro from the core macros, but it's used in JSX elements. ```jsx import { Select } from "@lingui/react/macro"; @@ -1015,6 +775,18 @@ import { Select } from "@lingui/react/macro"; ` inside `` macro if you want to provide `id`, `context` or `comment`. ```jsx @@ -1023,21 +795,21 @@ Use `