Merge branch 'docs-translate-edits-2' into 'master'

Edits to translation docs

See merge request gitlab-org/gitlab!62251

doc/development/i18n/merging_translations.md

@@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 CrowdIn automatically syncs the `gitlab.pot` file with the CrowdIn service, presenting
 newly added externalized strings to the community of translators.
 
-[GitLab CrowdIn Bot](https://gitlab.com/gitlab-crowdin-bot) also creates merge requests
+The [GitLab CrowdIn Bot](https://gitlab.com/gitlab-crowdin-bot) also creates merge requests
 to take newly approved translation submissions and merge them into the `locale/<language>/gitlab.po`
 files. Check the [merge requests created by `gitlab-crowdin-bot`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests?scope=all&utf8=%E2%9C%93&state=opened&author_username=gitlab-crowdin-bot)
 to see new and merged merge requests.
@@ -17,35 +17,34 @@ to see new and merged merge requests.
 ## Validation
 
 By default CrowdIn commits translations with `[skip ci]` in the commit
-message. This is done to avoid a bunch of pipelines being run. Before
-merging translations, make sure to trigger a pipeline to validate
-translations, we have static analysis validating things CrowdIn
-doesn't do. Create a new pipeline at `https://gitlab.com/gitlab-org/gitlab/pipelines/new`
-(need Developer access permissions) for the `master-i18n` branch.
+message. This avoids an excessive number of pipelines from running.
+Before merging translations, make sure to trigger a pipeline to validate
+translations. Static analysis validates things CrowdIn doesn't do. Create
+a new pipeline at [`https://gitlab.com/gitlab-org/gitlab/pipelines/new`](https://gitlab.com/gitlab-org/gitlab/pipelines/new)
+(need developer permissions) for the `master-i18n` branch.
 
 If there are validation errors, the easiest solution is to disapprove
 the offending string in CrowdIn, leaving a comment with what is
-required to fix the offense. There is an
+required to fix the errors. There's an
 [issue](https://gitlab.com/gitlab-org/gitlab/-/issues/23256)
-suggesting to automate this process. Disapproving excludes the
-invalid translation, the merge request is then updated within a few
+that suggests automating this process. Disapproving excludes the
+invalid translation. The merge request is then updated within a few
 minutes.
 
-If the translation has failed validation due to angle brackets `<` or `>`
-it should be disapproved on CrowdIn as our strings should be
-using [variables](externalization.md#html) for HTML instead.
+If the translation fails validation due to angle brackets (`<` or `>`),
+it should be disapproved in CrowdIn. Our strings must use [variables](externalization.md#html)
+for HTML instead.
 
-It might be handy to pause the integration on the CrowdIn side for a
-little while so translations don't keep coming. This can be done by
-clicking `Pause sync` on the [CrowdIn integration settings
-page](https://translate.gitlab.com/project/gitlab-ee/settings#integration).
+It might be useful to pause the integration on the CrowdIn side for a
+moment so translations don't keep coming. You can do this by clicking
+**Pause sync** on the [CrowdIn integration settings page](https://translate.gitlab.com/project/gitlab-ee/settings#integration).
 
 ## Merging translations
 
 After all translations are determined to be appropriate and the pipelines pass,
 you can merge the translations into the default branch. When merging translations,
-be sure to select the **Remove source branch** check box, which causes CrowdIn
-to recreate the `master-i18n` from the default branch after merging the new
+be sure to select the **Remove source branch** checkbox. This causes CrowdIn
+to recreate the `master-i18n` branch from the default branch after merging the new
 translation.
 
 We are discussing [automating this entire process](https://gitlab.com/gitlab-org/gitlab/-/issues/19896).
@@ -54,10 +53,8 @@ We are discussing [automating this entire process](https://gitlab.com/gitlab-org
 
 CrowdIn creates a new merge request as soon as the old one is closed
 or merged. But it does not recreate the `master-i18n` branch every
-time. To force CrowdIn to recreate the branch, close any [open merge
-request](https://gitlab.com/gitlab-org/gitlab/-/merge_requests?scope=all&utf8=%E2%9C%93&state=opened&author_username=gitlab-crowdin-bot)
-and delete the
-[`master-18n`](https://gitlab.com/gitlab-org/gitlab/-/branches/all?utf8=✓&search=master-i18n).
+time. To force CrowdIn to recreate the branch, close any [open merge requests](https://gitlab.com/gitlab-org/gitlab/-/merge_requests?scope=all&utf8=%E2%9C%93&state=opened&author_username=gitlab-crowdin-bot)
+and delete the [`master-18n`](https://gitlab.com/gitlab-org/gitlab/-/branches/all?utf8=✓&search=master-i18n) branch.
 
 This might be needed when the merge request contains failures that
 have been fixed on the default branch.
@@ -76,8 +73,8 @@ recreate it with the following steps:
 1. Sign in to CrowdIn with the GitLab integration.
 1. Go to **Settings > Integrations > GitLab > Set Up Integration**.
 1. Select the `gitlab-org/gitlab` repository.
-1. In `Select Branches for Translation`, select `master`.
-1. Ensure the `Service Branch Name` is `master-i18n`.
+1. In **Select Branches for Translation**, select `master`.
+1. Ensure the **Service Branch Name** is `master-i18n`.
 
 ## Manually update the translation levels
 

doc/development/i18n/proofreader.md

@@ -121,35 +121,35 @@ are very appreciative of the work done by translators and proofreaders!
 
 ## Become a proofreader
 
-Before requesting Proofreader permissions in CrowdIn, be sure you have a history
-of contributing translations to the GitLab project.
+Before requesting proofreader permissions in CrowdIn, be sure you have a history of contributing
+translations to the GitLab project.
 
 1. Contribute translations to GitLab. See instructions for
    [translating GitLab](translation.md).
 
-   Translating GitLab is a community effort that requires team work and
-   attention to detail. Proofreaders play an important role helping new
-   contributors, and ensuring the consistency and quality of translations.
-   Your conduct and contributions as a translator should reflect this before
-   requesting to be a proofreader.
+   Translating GitLab is a community effort that requires teamwork and attention to detail.
+   Proofreaders play an important role helping new contributors, and ensuring the consistency and
+   quality of translations. Your conduct and contributions as a translator should reflect this
+   before requesting to be a proofreader.
 
-1. Request proofreader permissions by opening a merge request to add yourself
-   to the list of proofreaders.
+1. Request proofreader permissions by opening a merge request to add yourself to the list of
+   proofreaders.
 
-   Open the [proofreader.md source file](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/development/i18n/proofreader.md) and click **Edit**.
+   Open the [`proofreader.md` source file](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/development/i18n/proofreader.md) and click **Edit**.
 
-   Add your language in alphabetical order, and add yourself to the list
-   including:
-   - name
-   - link to your GitLab profile
-   - link to your CrowdIn profile
+   Add your language in alphabetical order and add yourself to the list, including:
 
-   In the merge request description, include links to any projects you have
-   previously translated.
+   - Name
+   - Link to your GitLab profile
+   - Link to your CrowdIn profile
 
-1. Your request to become a proofreader is considered on the merits of
-   your previous translations by [GitLab team members](https://about.gitlab.com/company/team/)
-   or [Core team members](https://about.gitlab.com/community/core-team/) who are fluent in
-   the language or current proofreaders.
-   - When a request is made for the first proofreader for a language and there are no [GitLab team members](https://about.gitlab.com/company/team/)
-   or [Core team members](https://about.gitlab.com/community/core-team/) who speak the language, we shall request links to previous translation work in other communities or projects.
+   In the merge request description, include links to any projects you have previously translated.
+
+1. [GitLab team members](https://about.gitlab.com/company/team/),
+   [Core team members](https://about.gitlab.com/community/core-team/),
+   or current proofreaders fluent in the language consider your request to become a proofreader
+   based on the merits of your previous translations.
+
+   - If you request to become the first proofreader for a language and there are no GitLab or Core
+     team members who speak that language, we request links to previous translation work in other
+     communities or projects.

doc/development/i18n/translation.md

@@ -6,47 +6,39 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 
 # Translating GitLab
 
-For managing the translation process we use [CrowdIn](https://crowdin.com).
+For managing the translation process, we use [CrowdIn](https://crowdin.com).
+To contribute translations at [`translate.gitlab.com`](https://translate.gitlab.com),
+you must create a CrowdIn account. You may create a new account or use any of their supported
+sign-in services.
 
-## Using CrowdIn
+## Language selections
 
-The first step is to get familiar with CrowdIn.
+GitLab is being translated into many languages. To select a language to contribute to:
 
-### Sign In
-
-To contribute translations at <https://translate.gitlab.com>
-you must create a CrowdIn account.
-You may create a new account or use any of their supported sign in services.
-
-### Language Selections
+1. Find the language that you want to contribute to, in the
+   [GitLab CrowdIn project](https://crowdin.com/project/gitlab-ee).
 
-GitLab is being translated into many languages.
+   - If the language you want is available, proceed to the next step.
+   - If the language you want is not available,
+      [open an issue](https://gitlab.com/gitlab-org/gitlab/-/issues?scope=all&utf8=✓&state=all&label_name[]=Category%3AInternationalization).
+      Notify our CrowdIn administrators by including `@gitlab-org/manage/import` in your issue.
+   - After the issue and any merge requests are complete, restart this procedure.
 
-1. Find the language that you want to contribute to, in our
-   [GitLab CrowdIn project](https://crowdin.com/project/gitlab-ee).
-   - If the language that you're looking for is available, proceed
-     to the next step.
-   - If the language you are looking for is not available,
-      [open an issue](https://gitlab.com/gitlab-org/gitlab/-/issues?scope=all&utf8=✓&state=all&label_name[]=Category%3AInternationalization). Notify our CrowdIn
-      administrators by including `@gitlab-org/manage/import` in your issue.
-   - After the issue/Merge Request is complete, restart this procedure.
-1. Next, you can view list of files and folders.
-   Select `gitlab.pot` to open the translation editor.
+1. View the list of files and folders. Select `gitlab.pot` to open the translation editor.
 
-### Translation Editor
+### Translation editor
 
 The online translation editor is the easiest way to contribute translations.
 
 ![CrowdIn Editor](img/crowdin-editor.png)
 
-1. Strings for translation are listed in the left panel
-1. Translations are entered into the central panel.
-  Multiple translations are required for strings that contains plurals.
-  The string to be translated is shown above with glossary terms highlighted.
-  If the string to be translated is not clear, you can 'Request Context'
+- Strings for translation are listed in the left panel.
+- Translations are entered into the central panel. Multiple translations are required for strings
+  that contain plurals. The string to translate is shown in the above image with glossary terms
+  highlighted. If the string to translate isn't clear, you can request context.
 
-A glossary of common terms is available in the right panel by clicking Terms.
-Comments can be added to discuss a translation with the community.
+A glossary of common terms is available in the **Terms** tab in the right panel. In the **Comments**
+tab, you can add comments to discuss a translation with the community.
 
 Remember to **Save** each translation.
 
@@ -56,21 +48,18 @@ Be sure to check the following guidelines before you translate any strings.
 
 ### Namespaced strings
 
-When an externalized string is prepended with a namespace, e.g.
-`s_('OpenedNDaysAgo|Opened')`, the namespace should be removed from the final
-translation.
-For example in French `OpenedNDaysAgo|Opened` would be translated to
-`Ouvert•e`, not `OpenedNDaysAgo|Ouvert•e`.
+When an externalized string is prepended with a namespace (for example,
+`s_('OpenedNDaysAgo|Opened')`), the namespace should be removed from the final translation. For
+example, in French, `OpenedNDaysAgo|Opened` is translated to `Ouvert•e`, not
+`OpenedNDaysAgo|Ouvert•e`.
 
 ### Technical terms
 
-Some technical terms should be treated like proper nouns and not be translated.
-
-Technical terms that should always be in English are noted in the glossary when
-using <https://translate.gitlab.com>.
-
-This helps maintain a logical connection and consistency between tools (e.g.
-`git` client) and GitLab.
+You should treat some technical terms like proper nouns and not translate them. Technical terms that
+should always be in English are noted in the glossary when using
+[`translate.gitlab.com`](https://translate.gitlab.com).
+This helps maintain a logical connection and consistency between tools (for example, a Git client)
+and GitLab.
 
 ### Formality
 
@@ -81,33 +70,30 @@ The level of formality used in software varies by language:
 | French   | formal    | `vous` for `you` |
 | German   | informal  | `du` for `you` |
 
-You can refer to other translated strings and notes in the glossary to assist
-determining a suitable level of formality.
+Refer to other translated strings and notes in the glossary to assist you in determining a suitable
+level of formality.
 
 ### Inclusive language
 
-[Diversity](https://about.gitlab.com/handbook/values/#diversity) is a GitLab value.
-We ask you to avoid translations which exclude people based on their gender or
-ethnicity.
-In languages which distinguish between a male and female form, use both or
-choose a neutral formulation.
+[Diversity, inclusion, and belonging](https://about.gitlab.com/handbook/values/#diversity-inclusion)
+are GitLab values. We ask you to avoid translations that exclude people based on their gender or
+ethnicity. In languages that distinguish between a male and female form, use both or choose a
+neutral formulation.
 
 <!-- vale gitlab.Spelling = NO -->
-For example in German, the word "user" can be translated into "Benutzer" (male) or "Benutzerin" (female).
-Therefore "create a new user" would translate into "Benutzer(in) anlegen".
+For example, in German, the word _user_ can be translated into _Benutzer_ (male) or _Benutzerin_
+(female). Therefore, _create a new user_ translates to _Benutzer(in) anlegen_.
 <!-- vale gitlab.Spelling = YES -->
 
 ### Updating the glossary
 
-To propose additions to the glossary please
+To propose additions to the glossary, please
 [open an issue](https://gitlab.com/gitlab-org/gitlab/-/issues?scope=all&utf8=✓&state=all&label_name[]=Category%3AInternationalization).
 
-## French Translation Guidelines
-
-### Inclusive language in French
+## French translation guidelines
 
 <!-- vale gitlab.Spelling = NO -->
-In French, the "écriture inclusive" is now over (see on [Legifrance](https://www.legifrance.gouv.fr/jorf/id/JORFTEXT000036068906/)).
-So, to include both genders, write "Utilisateurs et utilisatrices" instead of "Utilisateur·rice·s".
-When space is missing, the male gender should be used alone.
+In French, the _écriture inclusive_ is now over (see on [Legifrance](https://www.legifrance.gouv.fr/jorf/id/JORFTEXT000036068906/)).
+To include both genders, write _Utilisateurs et utilisatrices_ instead of _Utilisateur·rice·s_. If
+there is not enough space, use the male gender alone.
 <!-- vale gitlab.Spelling = YES -->