docs: various docs improvements

website/docs/guides/dynamic-loading-catalogs.md

@@ -1,6 +1,6 @@
 # Dynamic loading of message catalogs
 
-[`I18nProvider`](/docs/ref/react.md#i18nprovider) doesn't assume anything about your app and it's your responsibility to load messages based on active language.
+[`I18nProvider`](/docs/ref/react.md#i18nprovider) doesn't assume anything about your app and it's the developer responsibility to load messages based on active language.
 
 Here's an example of a basic setup with a dynamic load of catalogs.
 

website/docs/guides/excluding-build-files.md

@@ -1,28 +1,24 @@
-# Excluding message catalog build files
+# Lingui-generated files in version control
 
-[`lingui extract`](/docs/ref/cli.md#extract) command creates temporary message catalogs per each source file. Also, [`lingui compile`](/docs/ref/cli.md#compile) command generates compiled message catalogs from source ones. All these files can be safely ignored from VCS and linters.
+The [`lingui extract`](/docs/ref/cli.md#extract) command extracts a message catalog (usually a po file) for each locale. Also, [`lingui compile`](/docs/ref/cli.md#compile) command generates minified JavaScript files from the po files. All these files can be ignored from your version control system (VCS).
 
-Can be safely ignored because these files must be created every time you deploy to production, so we encourage to use CI methods to automatize this process. If you commit it you will produce conflicts, which somebody will need to solve, in this minimized and transpired (basically unreadable to human) file. In summary, please, **always compile your catalogs**.
+Every time you deploy to production, the JavaScript files need to be available and up-to-date: your app will get the translated strings from there. It follows that the files produced by `lingui extract` need to be up-to-date as well, otherwise some strings might be missing.
 
-Replace `locales` in paths below with your custom `localeDir` from configuration.
+We encourage you to use CI to extract and compile the catalogs.
 
-- `locales/_build/`
-- `locales/**/*.js`
+It's also possible to keep the po files checked in your vcs, but you'll have to deal with potential merge conflicts.
 
 ## Git
 
-Add following lines to your `.gitignore`:
+To ignore the message catalogs, as well as compiled JavaScript files (as discusses above), add following lines to your `.gitignore`:
 
 ```ignore title=".gitignore"
-locales/_build/
+locales/**/*.po
 locales/**/*.js
 ```
 
 ## ESLint
 
-Specify which directories to lint explicitly or add following lines to your [.eslintignore](https://eslint.org/docs/user-guide/configuring#ignoring-files-and-directories):
+You should not need to configure anything, because a compiled message catalog has an `/*eslint-disable*/` comment embedded in itself and ESLint will therefore ignore it.
 
-```ignore title=".eslintignore"
-locales/_build/
-locales/**/*.js
-```
+If you need to customize what files are ignored by ESLint, read [.eslintignore docs](https://eslint.org/docs/user-guide/configuring#ignoring-files-and-directories).

website/docs/guides/flow.md

@@ -1,6 +1,6 @@
 # Flow
 
-Lingui already supports [Flow](https://flow.org/) by default. All you need to do is enable it in your config file:
+Lingui does not ship with [Flow](https://flow.org/) typings. However, you can use Lingui in projects written in Flow. All you need to do is inform the extractor that your sources use Flow syntax:
 
 ```js title="lingui.config.js"
 module.export = {

website/docs/guides/message-extraction.md

@@ -2,7 +2,7 @@
 
 Message extraction is an essential step in the internationalization process. It involves analyzing your code and extracting all messages defined in it so that your message catalogs are always up-to-date with the source code.
 
-To extract messages from your application with the lingui functions, use the `lingui extract` command.
+To extract messages from your application with the Lingui cli, use the `lingui extract` command.
 
 ## Supported patterns
 
@@ -27,7 +27,9 @@ For more usage examples, refer to the [macro documentation](/docs/ref/macro.md).
 
 ### Non-Macro usages
 
-Extractor matches `i18n._` or `i18n.t` function calls. It also matches when these functions are called from other member expressions, such as `ctx.i18n.t()`.
+Note that the non-macro usage is not common. We recommend you use macros.
+
+The extractor matches `i18n._` or `i18n.t` function calls. It also matches when these functions are called from other member expressions, such as `ctx.i18n.t()`.
 
 :::note
 Extractor matches calls only by name. It doesn't check whether they were really imported from Lingui packages.
@@ -153,9 +155,9 @@ lingui extract-experimental
 
 It's worth noting that the accuracy of the catalog heavily relies on tree-shaking, a technique used by modern bundlers to eliminate unused code from the final bundle.
 
-If the code passed to the extractor is written in a tree-shakeable way, the user will receive a highly accurate catalogs.
+If the code passed to the extractor is written in a tree-shakeable way, the user will receive highly accurate catalogs.
 
-While you might think that your code is tree-shakeable, in practice tree-shaking might work differently than what you expect and some unwanted strings may be included in the catalogs.
+While you might think that your code is tree-shakeable, in practice, tree-shaking might work differently than what you expect and some unwanted strings may be included in the catalogs.
 
 To illustrate, let's consider the following code:
 

website/docs/guides/typescript.md

@@ -1,10 +1,10 @@
 # Typescript
 
-Lingui supports typescript types out of the box since version `3.0.0`.
+Lingui is written in Typescript and ships with TS typings out of the box. You should not need to do anything to get type support working.
 
 ## Macros types in non-React environments
 
-Since the opening of this issue we investigated that macros can be used on Typescript environments where React isn't required.
+We investigated how macros can be used on Typescript environments where React isn't required.
 
 Now we're shipping two declaration types:
 

website/docs/introduction.md

@@ -32,7 +32,7 @@ Manage the whole intl workflow using Lingui [CLI](/docs/tutorials/cli.md). It ex
 
 ### Unopinionated
 
-Integrate Lingui into your existing workflow. It supports message keys as well as auto generated messages. Translations are stored either in JSON or standard PO file, which is supported in almost all translation tools.
+Integrate Lingui into your existing workflow. It supports explicit message keys as well as auto-generated ones. Translations are stored either in JSON or standard PO file, which is supported in almost all translation tools.
 
 ### Lightweight and optimized
 

website/docs/ref/cli.md

@@ -131,9 +131,7 @@ lingui compile
 
 #### `--overwrite` {#compile-overwrite}
 
-This command compiles message catalogs in `localeDir` and outputs minified Javascript files. Each message is replaced with a function that returns the translated message when called.
-
-Also, language data (pluralizations) are written to the message catalog as well.
+This command compiles message catalogs in `localeDir` and outputs minified JavaScript files. Each message is replaced with a function that returns the translated message when called.
 
 #### `--strict` {#compile-strict}
 

website/docs/tutorials/cli.md

@@ -4,7 +4,7 @@
 
 ## Extracting messages
 
-We're going to use an app we built in a [React tutorial](/docs/tutorials/react.md). The [`extract`](/docs/ref/cli.md#extract) command looks for messages in the source files and extracts them:
+We're going to use an app we built in the [React tutorial](/docs/tutorials/react.md). The [`extract`](/docs/ref/cli.md#extract) command looks for messages in the source files and extracts them:
 
 ```bash npm2yarn
 > npm run extract
@@ -77,7 +77,7 @@ Visit the [Message Extraction](/docs/guides/message-extraction.md) guide to read
 
 ## Preparing catalogs for production
 
-Once we have all catalogs ready and translated, we can compile the JSON into a minified JS file with the [`compile`](/docs/ref/cli.md#compile) command. This command parses the messages in MessageFormat and compiles them into simple functions. It also adds plural rules to a production ready catalog:
+Once we have all catalogs ready and translated, we can compile the JSON into a minified JS file with the [`compile`](/docs/ref/cli.md#compile) command. This command parses the messages in MessageFormat and compiles them into simple functions:
 
 ```bash npm2yarn
 > npm run compile
@@ -162,7 +162,7 @@ If you use natural language for message IDs (that's the default), set [`sourceLo
 
 ## Catalogs in VCS and CI
 
-The `locale/_build` folder and `locale/*/*.js` (compiled catalogs) are safe to be ignored by your VCS. What you do need to keep in VCS are the json files (`locale/*/*.json`) that contain the messages for translators. The JavaScript functions that return the actual translations when your app runs in production are created from those json files. See [Excluding build files](/docs/guides/excluding-build-files.md) guide for more info.
+The `locale/_build` folder and `locale/*/*.js` (compiled catalogs) are safe to be ignored by your VCS. What you do need to keep in VCS are the po or json files (`locale/*/*.po` or `locale/*/*.json`) that contain the messages for translators. The JavaScript functions that return the actual translations when your app runs in production are created from those files. See [Excluding build files](/docs/guides/excluding-build-files.md) guide for more info.
 
 If you're using a CI, it is a good idea to add the `yarn extract` and `yarn compile` commands to your build process.
 

website/docs/tutorials/explicit-vs-generated-ids.md

@@ -2,7 +2,7 @@
 
 In this guide, we will explore the fundamental concepts of explicit and generated IDs, and then delve into a comprehensive comparison, highlighting the benefits and drawbacks of each approach.
 
-## What is Explicit ID and What is Generated IDs?
+## What are Explicit IDs and what are Generated IDs?
 
 ### Explicit ID
 
@@ -22,7 +22,7 @@ Lingui example:
 
 ### Generated IDs
 
-On the other hand, generated IDs are automatically created by the internalization library. In Lingui, such IDs are created based on a source message and [context](#context).
+On the other hand, generated IDs are automatically created by the internalization library. In Lingui, such IDs are created based on the source message and [context](#context).
 
 Lingui example:
 
@@ -38,15 +38,15 @@ Lingui example:
 
 ### Benefits of Generated IDs
 
-1. **Avoiding "Naming Things" problem:** You don't need to come up with a name for each single phrase in the app. The natural language is used to create an ID.
+1. **Avoiding the "Naming Things" problem:** You don't need to come up with a name for each single phrase in the app.
 2. **Better Developer Experience:** a more streamlined development process with less code to write.
 3. **Preventing ID collisions:** As your application scales, explicit IDs can potentially lead to conflicts. Lingui's generated IDs ensure you steer clear of such collisions.
 4. **Avoiding Duplicates:** Duplicate messages are merged together automatically. Your translators will not have to translate the same phrases again and again. This could lead to cost savings, especially if translators charge by word count.
 5. **Smaller bundle:** The Lingui generates short ID such as `uxV9Xq` which are typically shorter than manually crafted IDs like `index.header.title`. This results in a smaller bundle size, optimizing your application's performance.
 
 ### Benefits of Explicit IDs
 
-1. **Control:** Developers have full control over the naming and assignment of explicit IDs. This control allows for precise targeting and easy maintenance of internationalization keys.
+1. **Control:** Developers have full control over the naming and assignment of explicit IDs. This allows for precise targeting and easy maintenance of internationalization keys. If your team uses a translation management system (TMS), even non-technical people can change the strings without having to touch the code.
 2. **Readability:** Explicit IDs often have meaningful names, making it easier for developers, translators, and content creators to understand their purpose within the codebase.
 3. **Predictability:** Since explicit IDs are manually assigned, they remain stable across different versions of your application, reducing the likelihood of breaking changes during updates.
 

website/docs/tutorials/react-native.md

@@ -11,15 +11,15 @@ If you're looking for a working solution, check out the [sources available here]
 :::caution Note
 This tutorial assumes you use Lingui >= 4.2 and React Native >=0.71 or Expo >=48, with the Hermes JavaScript Engine.
 
-`@lingui/core` depends on several apis exposed by the [`Intl` object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl). Support of the `Intl` object can vary across React Native and OS versions.
+`@lingui/core` depends on several APIs exposed by the [`Intl` object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl). Support of the `Intl` object can vary across React Native and OS versions.
 If some `Intl` feature is not supported by your runtime, you can [polyfill it](https://formatjs.io/docs/polyfills).
 
 See [here](https://github.com/facebook/hermes/issues/23) for details about `Intl` support in the Hermes engine.
 :::
 
-## Polyfilling Intl apis
+## 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. At the same time, modern i18n libraries rely on its presence.
+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 the amount of JS that needs to be `require`d by your app. At the same time, modern i18n libraries rely on its presence.
 
 Follow the polyfill installation instructions before proceeding further.
 

website/docs/tutorials/react-patterns.md

@@ -1,6 +1,6 @@
 # Common i18n patterns in React
 
-Following page describes the most common i18n patterns in React. It's a follow-up to [tutorial](/docs/tutorials/react.md) with practical examples. See the [API reference](/docs/ref/react.md) for detailed information about all components.
+This page describes the most common i18n patterns in React. It's a follow-up to the [tutorial](/docs/tutorials/react.md) with practical examples. See the [API reference](/docs/ref/react.md) for detailed information about all components.
 
 ## Macros
 
@@ -97,15 +97,15 @@ import { t } from "@lingui/macro";
 const colors = [t`Red`, t`Orange`, t`Yellow`, t`Green`];
 
 // ✅ Good! Every time the function is executed, the `t` macro will be re-executed as well,
-// and the actual result will be returned.
+// and the correctly translated color labels will be returned.
 function getColors() {
   return [t`Red`, t`Orange`, t`Yellow`, t`Green`];
 }
 ```
 
-There is an [ESLint Rule](https://github.com/lingui/eslint-plugin#t-call-in-function) designed to check for this misusage.
+There is an [ESLint Rule](https://github.com/lingui/eslint-plugin#t-call-in-function) designed to check for this misuse.
 
-Better option would be to use the Lazy Translations pattern described in the following paragraph.
+A better option would be to use the Lazy Translations pattern described in the following paragraph.
 :::
 
 ## Lazy Translations
@@ -132,10 +132,10 @@ export default function ColorList() {
 ```
 
 :::note
-Note that we import `<Trans>` component from `@lingui/react`, because we want to use a runtime version here, not a macro.
+Note that we import `<Trans>` component from `@lingui/react`, because we want to use the runtime `Trans` component here, not the (compile-time) macro.
 :::
 
-Or to render the message descriptor as a string-only translation, pass it to the [`i18n._()`](/docs/ref/core.md#i18n._) method:
+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";