docs: various improvements (#1639)

packages/format-po-gettext/README.md

@@ -12,7 +12,7 @@
 [documentation][documentation] for all information, tutorials and examples.
 
 > **Warning**
-> This formatter is made for compatibility with TMS, which does not support ICU expressions in PO files.
+> This formatter is made for compatibility with translation management systems, which do not support ICU expressions in PO files.
 > 
 > It does not support all features of LinguiJS and should be carefully considered over other formats.
 >

website/docs/introduction.md

@@ -44,7 +44,7 @@ Join us on [GitHub Discussions](https://github.com/lingui/js-lingui/discussions)
 
 ### Compatible with react-intl
 
-Low-level React API is very similar to react-intl and the message format is the same. It's easy to migrate existing project.
+Low-level React API is very similar to react-intl and the message format is the same. It's easy to migrate an existing project.
 
 ## Quick overview
 

website/docs/ref/catalog-formats.md

@@ -1,8 +1,8 @@
 # Catalog formats
 
-Catalog format (configured by the [`format`](/docs/ref/conf.md#format) option) refers to the offline catalog file format. This format is never used in production, because it's compiled into a JS module. The reason behind this build step is that the choice of catalog format depends on the individual internationalization workflow. On the other hand, runtime catalog should be as simple as possible, so it can be parsed quickly without additional overhead.
+Catalog format (configured by the [`format`](/docs/ref/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 behind this build step is that the choice of catalog format depends on the individual internationalization workflow. On the other hand, runtime catalog should be as simple as possible, so it can be parsed quickly without additional overhead.
 
-## PO File (recommended)
+## PO File (strongly recommended)
 
 PO files are translation files used by [gettext](https://www.gnu.org/software/gettext/manual/html_node/PO-Files.html) internationalization system. This is the recommended and the default catalog format.
 
@@ -28,12 +28,12 @@ msgstr "Obsolete Message"
 
 Messages with context are exported in the following way:
 
-  ```po
-  #: src/Inbox.js:12
-  msgctxt "my context"
-  msgid "msg.inbox"
-  msgstr "Message Inbox"
-  ```
+```po
+#: src/Inbox.js:12
+msgctxt "my context"
+msgid "msg.inbox"
+msgstr "Message Inbox"
+```
 
 ## PO File with gettext Plurals {#po-gettext}
 

website/docs/ref/core.md

@@ -22,7 +22,7 @@ import { i18n } from "@lingui/core"
  */
 async function activate(locale: string) {
   const { messages } = await import(`${locale}/messages.js`)
-  i18n.loadAndActivate(locale, messages)
+  i18n.loadAndActivate({ locale, messages })
 }
 
 activate("cs")

website/docs/ref/macro.md

@@ -609,9 +609,9 @@ const message = t({
 
 ### `defineMessage` alias: `msg` {#definemessage}
 
-`defineMessage` macro allows to define 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.
+`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).
 
-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 { defineMessage } from "@lingui/macro"
@@ -761,17 +761,21 @@ import { Trans } from "@lingui/react";
 <Trans id="message.attachment_saved" message="Attachment {name} saved." />;
 ```
 
-#### `comment`
-
-Comment for translators to give them additional information about the message. It's removed from the production code.
-
 #### `render`
 
 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.
 
+#### `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 the message. Allows to extract the same messages with different IDs. See [Context](#context) for more detail.
+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).
+
+It's removed from the production code. See [Context](#context) for more details.
 
 ```jsx
 import { Trans } from "@lingui/macro";
@@ -992,11 +996,11 @@ Use `<Select>` inside `<Trans>` macro if you want to provide `id`, `context` or
 
 ## Context
 
-The same text elements with different contexts are extracted with different IDs. For example, if the word "right" uses the following two definitions in two different locations, the word is translated differently and merged back into the application as different translation entries.
+By default, when using generated IDs, the same text elements are extracted with the same ID, and then translated once. This, however, may not always be desired because the same text can have different meaning and translation: For example, consider the word "right" and its two possible meanings:
 
 - correct as in "you are right"
 - direction as in "turn right"
 
-If the same text elements meet the following conditions, the text elements are extracted only once and use the same ID.
+To distinguish these two cases, you can add `context` to messages. The same text elements with different contexts are extracted with different IDs. Then, they can be translated differently and merged back into the application as different translation entries.
 
-Context makes the translation process less challenging and helps translators interpret the source accurately. You, in return, get translations of better quality faster and decrease the number of context-related issues you would need to solve.
+Regardless of whether you use generated IDs or not, adding context makes the translation process less challenging and helps translators interpret the source accurately. You, in return, get translations of better quality faster and decrease the number of context-related issues you would need to solve.

website/docs/tools/introduction.md

@@ -1,5 +1,7 @@
 # Introduction
 
+This guide covers tools that will help managing of your localization process. You may come across abbreviations TMS (translation management system) or CAT (computer-aided translation) that are sometimes used to describe these tools.
+
 ## Why use Sync & Collaboration Tools?
 
 The easiest way to translate your application is to translate the `.po` files directly in a text editor, or with a tool like [Poedit](https://poedit.net).

website/docs/tutorials/react-native.md

@@ -19,13 +19,17 @@ See [here](https://github.com/facebook/hermes/issues/23) for details about `Intl
 
 ## Polyfilling Intl apis
 
-React Native does not support all `Intl` features out of the box and we need to polyfill [`Intl.Locale`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale) using [`@formatjs/intl-locale`](https://formatjs.io/docs/polyfills/intl-locale/) and [`Intl.PluralRules`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/PluralRules) using [`@formatjs/intl-pluralrules`](https://formatjs.io/docs/polyfills/intl-pluralrules). Please note that importing the `Intl` polyfills can significantly increase your bundle size.
+React Native does not support all `Intl` features out of the box and we need to polyfill [`Intl.Locale`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale) using [`@formatjs/intl-locale`](https://formatjs.io/docs/polyfills/intl-locale/) and [`Intl.PluralRules`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/PluralRules) using [`@formatjs/intl-pluralrules`](https://formatjs.io/docs/polyfills/intl-pluralrules). Please note that importing the `Intl` polyfills can significantly increase your bundle size. At the same time, modern i18n libraries rely on its presence.
 
 Follow the polyfill installation instructions before proceeding further.
 
 ## Metro bundler support
 
-Lingui packages make use of the `exports` keyword in `package.json`. Metro bundler versions < 0.76.2 (before React Native 0.72) do not support this feature. There are two ways to make Metro understand the exports. With the first approach, make sure that (1) you're running metro 0.76.2 or newer (if necessary, use yarn resolutions or npm overrides) and (2) `unstable_enablePackageExports` is enabled in your `metro.config.js` file. See the [example](https://github.com/lingui/js-lingui/tree/main/examples/react-native/metro.config.js). Note that future versions of metro will have this option enabled by default so there will be no need to configure this. Alternatively, you can [configure the resolver](https://github.com/lingui/js-lingui/issues/1633#issuecomment-1532243227).
+Lingui packages make use of the `exports` keyword in `package.json`. Metro bundler versions < 0.76.2 (before React Native 0.72) do not support this feature.
+
+There are two ways to make Metro understand the exports. With the first approach, make sure that (1) you're running metro 0.76.2 or newer (if necessary, use yarn resolutions or npm overrides) and (2) `unstable_enablePackageExports` is enabled in your `metro.config.js` file. See the [example](https://github.com/lingui/js-lingui/tree/main/examples/react-native/metro.config.js). Note that future versions of metro will have this option enabled by default so there will be no need to configure this.
+
+Alternatively, you can [configure the resolver](https://github.com/lingui/js-lingui/issues/1633#issuecomment-1532243227).
 
 ## Example component
 

website/docs/tutorials/react-patterns.md

@@ -58,13 +58,11 @@ export default function ImageWithCaption() {
 }
 ```
 
-#### Providing a context for a message
-The same text elements with different contexts are extracted with different IDs. For example, if the word "right" uses the following two definitions in two different locations, the word is translated differently and merged back into the application as different translation entries.
+#### Providing context for a message
 
-- correct as in "you are right"
-- direction as in "turn right"
+Use `context` to add more contextual information for translators. It also influences the ID generation: the same text elements with different contexts are extracted with different IDs.
 
-If the same text elements meet the following conditions, the text elements are extracted only once and use the same ID.
+See [Context](/ref/macro#context) for more details.
 
 ```jsx
 import { Trans } from "@lingui/macro";
@@ -185,7 +183,7 @@ export default function ColorList() {
 }
 ```
 
-Or to render the message descriptor as a string-only translation, just pass it to the [`i18n._()`](/docs/ref/core.md#i18n._) method:
+Or to render the message descriptor as a string-only translation, pass it to the [`i18n._()`](/docs/ref/core.md#i18n._) method:
 
 ```jsx
 import { i18n } from "@lingui/core"
@@ -245,7 +243,7 @@ export function HappySad(props) {
 
 Sometimes you need to pick 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 representing the current status.
 
-A simple way to do this, is to make an object that maps the possible values of "status" to message descriptors (tagged with the [`defineMessage`](/docs/ref/macro.md#definemessage) macro), and render them as needed with lazy translation:
+A simple way to do this, is to make an object that maps the possible values of "status" to message descriptors (tagged with the [`defineMessage`](/docs/ref/macro.md#definemessage) macro), and render them as needed with deferred translation:
 
 ```jsx
 import { msg } from "@lingui/macro";
@@ -263,3 +261,24 @@ export default function StatusDisplay({ statusCode }) {
    return <div>{i18n._(statusMessages[statusCode])}</div>
 }
 ```
+
+## Memoization pitfall
+
+In the following contrived example, the welcome message will not be updated when locale changes.
+
+This is expected behavior, because the `useMemo` has no dependencies. In order for this to work as expected, the `useMemo` needs to depend on an `i18n` instance. Specifically, it needs to depend on `i18n` from the `useLingui` hook, as the reference to the `i18n` object from `@lingui/core` does not change throughout your app's lifetime.
+
+```jsx
+import { msg } from "@lingui/macro";
+import { i18n } from "@lingui/core"
+
+const welcomeMessage = msg`Open`;
+
+export function Welcome() {
+  const buggyWelcome = useMemo(() => {
+    return i18n._(welcomeMessage);
+  }, []);
+
+  return <div>{buggyWelcome}</div>;
+}
+```