Skip to content

Commit 13611d1

Browse files
docs(macro): add docs for exhaustive select macro
1 parent 35b060d commit 13611d1

File tree

1 file changed

+39
-10
lines changed

1 file changed

+39
-10
lines changed

website/docs/ref/macro.mdx

Lines changed: 39 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -323,7 +323,7 @@ const message = t({
323323
The `select` macro is used to handle different forms of a message based on a value.
324324

325325
```ts
326-
select(value: string | number, options: Object)
326+
select(value: string, options: Object)
327327
```
328328

329329
It works like a switch statement - it selects one of the forms provided in the `options` object based on the `value`:
@@ -349,6 +349,35 @@ const message = i18n._(
349349
);
350350
```
351351

352+
The `select` macro can be strictly exhaustive if the fallback `other` option is not provided and the input `value` is a union type.
353+
354+
```ts
355+
import { select } from "@lingui/core/macro";
356+
357+
type ValidationError =
358+
| "missingValue"
359+
| "invalidEmail"
360+
361+
const message = select(validationError, {
362+
missingValue: "This field is required",
363+
invalidEmail: "Invalid email address",
364+
});
365+
366+
// ↓ ↓ ↓ ↓ ↓ ↓
367+
368+
import { i18n } from "@lingui/core";
369+
370+
const message = i18n._(
371+
/*i18n*/ {
372+
id: "VRptzI",
373+
message: "{validationError, select, missingValue {This field is required} invalidEmail {Invalid email address} other {}}",
374+
values: { validationError },
375+
}
376+
);
377+
```
378+
379+
The `other` option is left empty, for compatibility with [ICU MessageFormat](/guides/message-format).
380+
352381
:::tip
353382
Use `select` inside [`t`](#t) or [`defineMessage`](#definemessage) macro if you want to add custom `id`, `context` or `comment` for translators.
354383

@@ -692,15 +721,15 @@ import { Select } from "@lingui/react/macro";
692721

693722
Available Props:
694723

695-
| Prop name | Type | Description |
696-
| --------- | ------ | ------------------------------------------------------ |
697-
| `value` | number | _(required)_ Value determines which form is output |
698-
| `other` | number | _(required)_ Default, catch-all form |
699-
| `_<case>` | string | Form for specific case |
700-
| `id` | string | Custom message ID |
701-
| `comment` | string | Comment for translators |
702-
| `context` | string | Allows to extract the same messages with different IDs |
703-
| `render` | func | Custom render callback to render translation |
724+
| Prop name | Type | Description |
725+
| --------- | ------ | ------------------------------------------------------------- |
726+
| `value` | number | _(required)_ Value determines which form is output |
727+
| `other` | number | Default, catch-all form, required if cases are not exhaustive |
728+
| `_<case>` | string | Form for specific case |
729+
| `id` | string | Custom message ID |
730+
| `comment` | string | Comment for translators |
731+
| `context` | string | Allows to extract the same messages with different IDs |
732+
| `render` | func | Custom render callback to render translation |
704733

705734
The select cases except `other` should be prefixed with underscore: `_male` or `_female`.
706735

0 commit comments

Comments
 (0)