docs: I18nProvider updates

lingui · Mar 13, 2023 · e53823a · e53823a
1 parent 24c359a
commit e53823a
Show file tree

Hide file tree

Showing 3 changed files with 77 additions and 71 deletions.
diff --git a/packages/react/src/I18nProvider.test.tsx b/packages/react/src/I18nProvider.test.tsx
@@ -90,8 +90,8 @@ describe("I18nProvider", () => {
       textContentDynamicAfterActivate: "2_cs",
     },
   ])(
-    "A component that is not consuming i18n context will not re-render on locale change.",
-    // "A component that consumes i18n context will re-render on locale change, only if forceRenderOnLocaleChange is true.",
+    "A component that is not consuming i18n context will not re-render on locale change." +
+      "A component that consumes i18n context will re-render on locale change, only if forceRenderOnLocaleChange is true.",
     ({
       forceRenderOnLocaleChange,
       textContentBeforeActivate,

diff --git a/website/docs/ref/react.md b/website/docs/ref/react.md
@@ -2,13 +2,11 @@
 
 Components from `@lingui/react` wrap the vanilla JS API from `@lingui/core`. React components handle changes of active language or interpolated variables better than low-level API and also take care of re-rendering when locale or messages change.
 
-## General Concepts
+## Rendering of Translations {#rendering-translations}
 
-### Rendering of Translations {#rendering-translations}
+All i18n components render translation as text without a wrapping tag. This can be customized in two different ways:
 
-All i18n components render translation as a text without a wrapping tag. This can be customized in three different ways:
-
--   globally: using `defaultComponent` prop on [`I18nProvider`](#i18nprovider) component;
+-   globally: using `defaultComponent` prop on [`I18nProvider`](#i18nprovider) component
 -   locally: using `render` prop or `component` on i18 components
 
 #### Global Configuration
@@ -36,7 +34,7 @@ import { Text } from "react-native";
 // renders as <Text>Link to docs</Text>
 ```
 
-To get more control over the rendering of translation, use instead the `render` method with **React.Component** (or stateless component). Component passed to `render` will receive the translation value as a `translation` prop:
+To get more control over the rendering of translation, use instead the `render` prop with a render callback. Function passed to `render` will receive the translation value as a `translation` parameter:
 
 ``` jsx
 // custom component
@@ -46,7 +44,7 @@ To get more control over the rendering of translation, use instead the `render`
 // renders as <Icon label="Sign in" />
 ```
 
-`render` or `component` also accepts `null` value to render string without a wrapping component. This can be used to override custom `defaultComponent` config.
+`render` and `component` also accept `null` value to render string without a wrapping component. This can be used to override custom `defaultComponent` config.
 
 ``` jsx
 <Trans render={null}>Heading</Trans>;
@@ -56,71 +54,18 @@ To get more control over the rendering of translation, use instead the `render`
 // renders as "Heading"
 ```
 
-## Components
-
-### Trans
-
-| Prop name | Type     | Description         |
-| --------- | -------- | ------------------- |
-| `id`      | `string` | Key, the message ID |
-
-:::important
-
-Import [`Trans`](/docs/ref/macro.md#jsxmacro-Trans) macro instead of [`Trans`](#trans) if you use macros:
-
-``` jsx
-import { Trans } from "@lingui/macro"
-
-// Trans from @lingui/react won't work in this case
-// import { Trans } from "@lingui/react"
-
-<Trans>Hello, my name is {name}</Trans>
-```
-:::
-
-It's also possible to use `Trans` component directly without macros. In that case, `id` is the message being translated. `values` and `components` are arguments and components used for formatting translation:
-
-``` jsx
-<Trans id="Hello World" />;
-
-<Trans
-  id="Hello {name}"
-  values={{ name: 'Arthur' }}
-/>;
-
-// number of tag corresponds to index in `components` prop
-<Trans
-  id="Read <link>Description</link> below."
-  components={{ link: <a href="/docs" /> }}
-/>
-```
-
-#### 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:
-
-``` jsx
-import React from 'react';
-import { Trans } from '@lingui/react';
-
-<Trans
-   id="{count, plural, =1 {car} other {cars}}"
-   values={{ count: cars.length }}
-></Trans>
-```
-
-## Providers
+## Lingui Context
 
 Message catalogs and the active locale are passed to the context in [`I18nProvider`](#i18nprovider). Use [`useLingui`](#uselingui) hook to access Lingui context.
 
 ### I18nProvider
 
-| Prop name                   | Type                  | Description                                                                   |
-| --------------------------- | --------------------- | ----------------------------------------------------------------------------- |
-| `I18n`                      | `i18n`                | The i18n instance (usually the one imported from `@lingui/core`)              |
-| `children`                  | `React.ReactNode`     | React Children node                                                           |
-| `defaultComponent`          | `React.ComponentType` | A React component for rendering <Trans\> within this component (Not required) |
-| `forceRenderOnLocaleChange` | `boolean`             | Force re-render when locale changes (default: true)                           |
+| Prop name                   | Type                  | Description                                                               |
+| --------------------------- | --------------------- |---------------------------------------------------------------------------|
+| `I18n`                      | `i18n`                | The i18n instance (usually the one imported from `@lingui/core`)          |
+| `children`                  | `React.ReactNode`     | React Children node                                                       |
+| `defaultComponent`          | `React.ComponentType` | A React component for rendering <Trans\> within this component (optional) |
+| `forceRenderOnLocaleChange` | `boolean`             | Force re-render when locale changes (default: true)                       |
 
 `defaultComponent` has the same meaning as `component` in other i18n components. [`Rendering of translations`](#rendering-translations) is explained at the beginning of this document.
 
@@ -157,7 +102,7 @@ const App = () => {
 
 Disable `forceRenderOnLocaleChange` when you have specific needs to handle initial state before locales are loaded and when locale changes.
 
-This component should live above all i18n components. A good place is as a top-level application component. However, if the `locale` is stored in a `redux` store, this component should be inserted below `react-redux/Provider`:
+`I18nProvider` should live above all other i18n components. A good place is as a top-level application component. However, if the `locale` is stored in a `redux` store, this component should be inserted below `react-redux/Provider`:
 
 ``` jsx
 import React from 'react';
@@ -181,6 +126,10 @@ const App = () => {
 
 ### useLingui
 
+This hook allows access to the Lingui context. It returns an object with the same values that were passed to the `I18nProvider` component.
+
+Components that use `useLingui` hook will re-render when locale and / or catalogs change, ensuring that the translations are always up-to-date.
+
 ``` jsx
 import React from "react"
 import { useLingui } from "@lingui/react"
@@ -191,3 +140,60 @@ const CurrentLocale = () => {
    return <span>Current locale: {i18n.locale}</span>
 }
 ```
+
+## 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.
+
+This section is intended for reference purposes.
+
+### Trans
+
+| Prop name | Type     | Description         |
+| --------- | -------- | ------------------- |
+| `id`      | `string` | Key, the message ID |
+
+:::important
+
+Import [`Trans`](/docs/ref/macro.md#jsxmacro-Trans) macro instead of [`Trans`](#trans) component if you use macros:
+
+``` jsx
+import { Trans } from "@lingui/macro"
+
+// Trans from @lingui/react won't work in this case
+// import { Trans } from "@lingui/react"
+
+<Trans>Hello, my name is {name}</Trans>
+```
+:::
+
+It's also possible to use `Trans` component directly without macros. In that case, `id` is the message being translated. `values` and `components` are arguments and components used for formatting translation:
+
+``` jsx
+<Trans id="Hello World" />;
+
+<Trans
+  id="Hello {name}"
+  values={{ name: 'Arthur' }}
+/>;
+
+// number of tag corresponds to index in `components` prop
+<Trans
+  id="Read <link>Description</link> below."
+  components={{ link: <a href="/docs" /> }}
+/>
+```
+
+#### 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:
+
+``` jsx
+import React from 'react';
+import { Trans } from '@lingui/react';
+
+<Trans
+   id="{count, plural, =1 {car} other {cars}}"
+   values={{ count: cars.length }}
+></Trans>
+```
diff --git a/website/sidebars.ts b/website/sidebars.ts
@@ -196,7 +196,7 @@ const sidebar = [
   {
     type: 'category',
     label: 'Releases',
-    items: ['releases/migration-3', 'releases/migration-4'],
+    items: ['releases/migration-4', 'releases/migration-3'],
   },
 ];