docs: prettify sync & collaboration tools section

website/docs/tools/crowdin.md

@@ -55,13 +55,17 @@ Source strings are pulled automatically and are always up to date for your trans
 
 ![Automatically pull source strings to Crowdin and push translated content to your repository](/img/docs/Crowdin__js-lingui-vcs.png)
 
-### CLI
+## CLI
 
-Easily integrate Crowdin with your CI server, GIT, SVN, Mercurial, etc. Connect cross-platform [Crowdin CLI](https://developer.crowdin.com/cli-tool/?utm_source=lingui.dev&utm_medium=referral&utm_campaign=lingui.dev) directly to your code repository and never deal with localization files manually again.
+Connect cross-platform [Crowdin CLI](https://crowdin.github.io/crowdin-cli/) directly to your code repository and never deal with localization files manually again.
 
-![Manage and synchronize your localization resources with Crowdin CLI](/img/docs/Crowdin__js-lingui-cli.png)
+With Crowdin CLI, you can:
 
-### 1. Create the `crowdin.yml` configuration file
+- Automate the process of updating your source files in your Crowdin project.
+- Download translations from Crowdin and automatically save them in the correct locations.
+- Upload all your existing translations to Crowdin in minutes.
+
+### Create the `crowdin.yml` configuration file
 
 ```yaml title="crowdin.yml"
 project_id: "123456" # Your Crowdin project ID
@@ -74,15 +78,15 @@ files: # Paths to the source and translation files
     translation: /**/locales/%two_letters_code%/%original_file_name%
 ```
 
-### 2. Install the Crowdin CLI as an npm package
+### Install the Crowdin CLI as an npm package
 
 ```bash npm2yarn
-npm install @crowdin/cli@3
+npm install --save-dev @crowdin/cli
 ```
 
-### 3. Add the following scripts
+### Add the synchronization scripts
 
-Add these lines to your `package.json` to make your life easier.
+Add the following scripts to your `package.json`:
 
 ```json title="package.json"
 {
@@ -95,11 +99,11 @@ Add these lines to your `package.json` to make your life easier.
 }
 ```
 
-### 4. Configuration
+### Configuration
 
 Set the `CROWDIN_PERSONAL_TOKEN` env variable on your computer, to allow the CLI to authenticate with the Crowdin API.
 
-### 5. Usage
+#### Usage
 
 Test that you can run the Crowdin CLI:
 
@@ -137,25 +141,27 @@ To see the full list of possible commands and options:
 npm run crowdin -h
 ```
 
-### Over-The-Air Content Delivery
+## Over-The-Air Content Delivery
 
 Over-the-Air Content Delivery is a feature that allows you to instantly update sources and translations in your mobile, server, desktop, or web apps with a single click without preparing a new release.
 
 Visit the following pages to learn more about how to integrate Over-The-Air Content Delivery into your Lingui project:
 
 - [Lingui tutorial - Crowdin OTA JS Client](https://crowdin.github.io/ota-client-js/tutorials/lingui/)
-- [Lingui String Exporter - Crowdin Marketplace](https://store.crowdin.com/lingui-string-exporter)
+- [Lingui String Exporter - Crowdin Marketplace](https://store.crowdin.com/lingui-string-exporter?utm_source=lingui.dev&utm_medium=referral&utm_campaign=lingui.dev)
 
-### [API](https://support.crowdin.com/api/v2/) and webhooks
+## API and Webhooks
 
 Customize your experience. Automate and scale your localization workflow. Seamlessly add new content for translation to your Crowdin project, check translation status, merge new content, etc.
 
-### To get started, register a [Crowdin.com](https://accounts.crowdin.com/register?utm_source=lingui.dev&utm_medium=referral&utm_campaign=lingui.dev) or [Crowdin Enterprise](https://accounts.crowdin.com/workspace/create?utm_source=lingui.dev&utm_medium=referral&utm_campaign=lingui.dev) account
+See the [API](https://support.crowdin.com/developer/api/?utm_source=lingui.dev&utm_medium=referral&utm_campaign=lingui.dev) and [Webhooks](https://support.crowdin.com/developer/webhooks/?utm_source=lingui.dev&utm_medium=referral&utm_campaign=lingui.dev) documentation for more information.
+
+## Next Steps
 
-Once you have signed up, we recommend [creating your localization project](https://support.crowdin.com/creating-project/?utm_source=lingui.dev&utm_medium=referral&utm_campaign=lingui.dev).
+To get started, register a [Crowdin.com](https://accounts.crowdin.com/register?utm_source=lingui.dev&utm_medium=referral&utm_campaign=lingui.dev) or [Crowdin Enterprise](https://accounts.crowdin.com/workspace/create?utm_source=lingui.dev&utm_medium=referral&utm_campaign=lingui.dev) account. Once you have signed up, [create your localization project](https://support.crowdin.com/creating-project/?utm_source=lingui.dev&utm_medium=referral&utm_campaign=lingui.dev).
 
-Depending on the ways you would like to work with Crowdin, we offer such options:
+Depending on how you'd like to work with Crowdin, you have the following options:
 
-1.  [Integrate Crowdin with GitHub](https://support.crowdin.com/github-integration/?utm_source=lingui.dev&utm_medium=referral&utm_campaign=lingui.dev).
-2.  Manage and synchronize your localization resources with [Crowdin CLI](https://developer.crowdin.com/cli-tool/?utm_source=lingui.dev&utm_medium=referral&utm_campaign=lingui.dev).
-3.  [Upload files for the test via UI](https://support.crowdin.com/uploading-files/?utm_source=lingui.dev&utm_medium=referral&utm_campaign=lingui.dev).
+1. [Integrate Crowdin with GitHub](https://support.crowdin.com/github-integration/?utm_source=lingui.dev&utm_medium=referral&utm_campaign=lingui.dev).
+2. Manage and synchronize your localization resources with [Crowdin CLI](https://developer.crowdin.com/cli-tool/?utm_source=lingui.dev&utm_medium=referral&utm_campaign=lingui.dev).
+3. [Upload files for the test via UI](https://support.crowdin.com/uploading-files/?utm_source=lingui.dev&utm_medium=referral&utm_campaign=lingui.dev).

website/docs/tools/introduction.md

@@ -1,16 +1,16 @@
-# Introduction
+# Sync & Collaboration Tools
 
-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.
+While Lingui provides a powerful API for managing your translations, it doesn't provide an integrated solution for managing synchronization and collaboration with your translators.
 
-## Why use Sync & Collaboration Tools?
+This guide covers tools that can help you manage your localization process. You may come across acronyms like TMS (Translation Management System) or CAT (Computer Aided Translation) that are sometimes used to describe these 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).
+## Workflows
 
-This solution may be good enough when your application is still small and doesn't evolve much, but it quickly becomes hard work when the number of sentences to translate and the target languages to manage increase with time.
+The easiest way to translate your application is to translate your message catalogs directly in a text editor, or with a tool like [Poedit](https://poedit.net).
 
-It then becomes more and more difficult and time-consuming to manage the back and forth with the translators, while keeping your application `.po` files up-to-date with the current state of a codebase that doesn't stop evolving.
+This solution may be good enough when your application is small and doesn't evolve much, but it quickly becomes hard work as the number of sentences to translate and target languages to manage increases over time.
 
-That's why sync and collaboration tools are directly integrated into Lingui to help structure your work with your translators team, to ensure the consistency of the translations, and to make your life easier.
+It becomes increasingly difficult and time-consuming to manage the back-and-forth with translators while keeping your application's message catalogs up to date with the current state of a codebase that does not stop evolving.
 
 ### Regular Workflow
 
@@ -28,7 +28,7 @@ When the amount of text to translate increases, and the number of target languag
 
 Instead of manually sending and receiving many emails and fixing the inconsistencies with your code, a `sync` method is called and your `.po` and `.js` files are directly updated with the latest translations. Your translators will also be notified when there are new text to translate.
 
-## Benefits of these tools
+## Benefits
 
 - **Synchronization**: unique `yarn sync` or `npm run sync` command to synchronize your project with all your translators and update your local `.po` and `.js` files with the latest translations.
 - **Translation Interface**: provide a professional and flexible interface to translators.
@@ -37,14 +37,7 @@ Instead of manually sending and receiving many emails and fixing the inconsisten
 - **Smart Plural Management**: allows to translate `Message` and `Messages` instead of `{count, plural, one {Message} other {Messages}}`.
 - **Consistency**: assist translators with `{variable}` interpolation and HTML formatting.
 
-## List of available tools
+## Available Tools
 
-### [Crowdin](https://crowdin.com/?utm_source=lingui.dev&utm_medium=referral&utm_campaign=lingui.dev)
-
-- Documentation: [Crowdin](/docs/tools/crowdin.md)
-- GitHub: https://github.com/crowdin
-
-### [Translation.io](https://translation.io/lingui)
-
-- Documentation: [translation-io](/docs/tools/translation-io.md)
-- GitHub: https://github.com/translation/lingui
+- [Crowdin](/docs/tools/crowdin.md)
+- [Translation.io](/docs/tools/translation-io.md)

website/docs/tools/translation-io.md

@@ -4,18 +4,15 @@
   <img src="https://translation.io/logo.png" alt="Translation.io - Localization made simple for tech companies" width="300" />
 </p>
 
-[Translation.io](https://translation.io/lingui) is a professional synchronization and collaboration platform that will assist your team in the translation of your Lingui application.
+Translation.io is a professional synchronization and collaboration platform that will assist your team in the translation of your Lingui application.
 
-Links:
-
-- Website: https://translation.io/lingui
-- GitHub: https://github.com/translation/lingui
+[Website](https://translation.io/lingui) \| [GitHub](https://github.com/translation/lingui) \| [[email protected]](mailto:[email protected])
 
 ## Features
 
 ### Smooth Team Management
 
-Invite your collaborators using their email or username, and assign them a role and a target language. We'll bring them on board and keep them informed about any new activity in their language.
+Invite collaborators using their email or username, and assign them a role and a target language. They will be brought on board and kept informed about any new activity in their language.
 
 ![Smooth Team Management on Translation.io](https://translation.io/gifs/lingui/translation-collaborators.gif)
 
@@ -41,7 +38,7 @@ Learn more:
 
 Sometimes you have no choice but to confront your translators with HTML or interpolated variables. The problem is that translators do not necessarily know the meaning of these notations and may be tempted to translate them or may inadvertently alter them.
 
-`Hello {name}` should never be translated as `Bonjour {nom}`, and we have several mechanisms to ensure that, like warnings and auto-completion:
+`Hello {name}` should never be translated as `Bonjour {nom}`, and several mechanisms are in place to ensure this, such as warnings and auto-completion:
 
 ![Syntax Highlighting warning on Translation.io](https://translation.io/_articles/translation/2019-10-11-highlighting-of-html-tags-and-interpolated-variables/highlight-interpolated-variable-lingui.png)
 
@@ -61,9 +58,9 @@ Lingui allows to write plurals using the [ICU MessageFormat](/docs/guides/messag
 
 But you can't ask a translator to understand this syntax, and he or she would be tempted to translate `one` or `other` keywords in other languages, breaking your code at the same time.
 
-That's why we deconstruct the plural syntaxes to make them easy to translate, and then reconstruct them inside your local `.po` files.
+That's why plural syntaxes are deconstructed to make translation easier, and then reconstructed in the local `.po` files.
 
-If the target language has more plural forms than the source language, we also provide some examples to the translator, because it could be unclear what plural form the `few` or `other` keyword may refer to in that specific target language (in this example, Czech has 3 plural forms).
+If the target language has more plural forms than the source language, examples are also provided to the translator, as it may be unclear which plural form the `few` or `other` keyword refers to in that specific target language (for instance, Czech has three plural forms).
 
 ![Smart Plural Management on Translation.io](/img/docs/translation-lingui-plural-forms.png)
 
@@ -90,11 +87,11 @@ Learn more:
 
 ## Installation
 
-### 1. Create your Lingui project
+### Create your Lingui project
 
 Create an account on [Translation.io](https://translation.io/lingui) and create a new Lingui project.
 
-### 2. Configure your application
+### Configure your application
 
 Copy the `.linguirc` configuration file that was generated for you to the root of your application.
 
@@ -113,7 +110,7 @@ The configuration file looks like this:
 
 The synchronization will then be part of the [`extract`](/docs/ref/cli.md#extract) command.
 
-### 3. Add the following scripts
+### Add the following scripts
 
 Add these lines to your `package.json` to make your life easier.
 
@@ -126,7 +123,7 @@ Add these lines to your `package.json` to make your life easier.
 }
 ```
 
-### 4. Initialize your project
+### Initialize your project
 
 Initialize your project and upload your source text and potential existing translations with:
 
@@ -155,7 +152,3 @@ As the name says, this operation will also perform a sync at the same time.
 ```bash npm2yarn
 npm run sync_and_purge
 ```
-
----
-
-If you need some help with your project, feel free to contact [email protected]

website/sidebars.ts

@@ -193,7 +193,23 @@ const sidebar = [
   {
     type: "category",
     label: "Sync & Collaboration Tools",
-    items: ["tools/introduction", "tools/crowdin", "tools/translation-io"],
+    items: [
+      {
+        type: "doc",
+        label: "Introduction",
+        id: "tools/introduction",
+      },
+      {
+        type: "doc",
+        label: "Crowdin",
+        id: "tools/crowdin",
+      },
+      {
+        type: "doc",
+        label: "Translation.io",
+        id: "tools/translation-io",
+      },
+    ],
   },
   {
     type: "category",