Skip to content

G
gitlab-ce
Commit 0c984f54 authored by Nick Gaskill's avatar Nick Gaskill Committed by Kati Paizee
Browse files
Options

Edits to translation docs

parent b30db443
Show whitespace changes
Inline Side-by-side
Showing with 89 additions and 106 deletions
doc/development/i18n/merging_translations.md
View file @ 0c984f54
......@@ -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
View file @ 0c984f54
......@@ -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
View file @ 0c984f54
......@@ -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 -->
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7