You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/translation.md
+73-29Lines changed: 73 additions & 29 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -5,63 +5,107 @@ This document provides guidelines for contributing translations and getting star
5
5
6
6
## Why Translation Matters
7
7
8
-
Translation enables Keycloak to reach a wider audience by making the platform usable for speakers of various languages. By translating Keycloak, you help improve accessibility and usability for users who may not be proficient in English.
8
+
Translation enables Keycloak to reach a wider audience by making the platform usable for speakers of various languages. By translating Keycloak, you help to improve accessibility and usability for users who may not be proficient in English.
9
9
10
10
## What to translate
11
11
12
-
Your contributions can greatly enhance the user experience for non-English speakers.
12
+
Keycloak welcomes translations of its user interfaces and error messages via two distinct ways:
13
13
14
-
Keycloak welcomes translations of its user interfaces and error messages via Weblate.
14
+
* GitHub pull requests to `messages_*.properties` files,
15
15
16
-
There is also a [Keycloak Documentation translation project](https://github.com/openstandia/keycloak-documentation-i18n).
16
+
OR
17
17
18
-
## Getting Started with Weblate
18
+
* Web based translation via [Weblate](https://hosted.weblate.org/projects/keycloak/).
19
19
20
-
Keycloak uses [Weblate](https://hosted.weblate.org/projects/keycloak/), a web-based translation platform, to manage translations of user interfaces and error messages.
21
-
22
-
Here's how you can get started:
23
-
24
-
- Sign Up: Visit Weblate to create an account.
25
-
- Configuration: After signing up, configure your Weblate account settings according to your preferences. Please note that the committer email is set to the login email address by default. You can adjust this in your Weblate profile under Account settings.
26
-
- Join the Keycloak translation team on Weblate to start contributing translations.
20
+
There is also a [Keycloak Documentation translation project](https://github.com/openstandia/keycloak-documentation-i18n) to translate some parts of the documentation to Japanese.
27
21
28
-
###Guidelines and Conventions
22
+
## Guidelines and Conventions
29
23
30
24
To ensure consistency and quality across translations, please adhere to the following guidelines:
31
25
32
26
- Use formal or informal language as appropriate for the context.
33
27
- Maintain consistency with existing translations.
34
28
- Translate text accurately, ensuring that the meaning is preserved.
35
-
- Weblate will pushe translations as a pull request to the [Keycloak repository](https://github.com/keycloak/keycloak) at least once a day. A maintainer for that language has the ability to approve or decline that translation.
36
29
37
-
####Spanish translations
30
+
### Spanish translations
38
31
39
32
- Use the formal "usted" form instead of the informal "vos or tu" (i.e., avoid tuteo), ensuring a more formal tone.
40
33
41
-
### Supported translations
34
+
## Using GitHub pull requests to update translations
35
+
36
+
Translations via GitHub pull requests are possible for all languages.
37
+
38
+
While for those languages on Weblate the preferred way is to use Weblate, contributions are still possible via GitHub. If you are not familiar with GitHub, and want your language to be added to Weblate, see "Steps to add a new language to Weblate"
39
+
40
+
**Tasks of the translator:**
42
41
43
-
Keycloak already supports a lot of translations.
44
-
While were in the transitioning process towards Weblate, the following translations are available in Weblate:
42
+
1. Optional: Create an issue or discussion as outlined in the [contributing docs](../CONTRIBUTING.md).
43
+
2. Update the `messages_*.properties` files for one or more languages.
44
+
3. Commit the changes with sign-off as outlined in the [contributing docs](../CONTRIBUTING.md). If you created an issue in the first step, reference it in the commit.
45
+
4. Create a pull request. If you created an issue in the first step, link it to the issue as described in [contributing docs](../CONTRIBUTING.md).
46
+
5. Find a reviewer that is a native speaker in that language.
45
47
46
-
- German
47
-
- Dutch
48
-
- Japanese
49
-
- Catalan
50
-
- Spanish
48
+
**Task of the reviewer:**
51
49
52
-
For all other translations, look for the `messages_*.properties` files in the main repository and create a pull request with your translations.
50
+
1. As a native speaker, review the changes in the pull request. Once you are satisfied with the changes, leave a comment in the pull request that you approve the changes.
53
51
54
-
Please note that while we aspire to support more translations in the future, our current focus is on these translations. We rely on volunteers like you to take the initiative in steering the translation efforts for additional translations. If you're interested in contributing translations for a language not listed above, add a comment to the [localization platform discussion](https://github.com/keycloak/keycloak/discussions/9270).
52
+
**Tasks of the maintainer:**
55
53
56
-
If you have any questions or need assistance, feel free to reach out to the language maintainers listed below:
54
+
1. Once the review from the native speaker is in, check that the changes to the `messages_*.properties` files are syntactically correct.
55
+
2. If there are any translation pull requests created by Weblate, assure to merge them first to avoid conflicts in Weblate which are difficult to resolve.
56
+
3. If the changes are ok, approve the PR and merge it. If there is an existing issue, reference that in the squash-message, otherwise reference the issue of the pull request.
Keycloak uses [Weblate](https://hosted.weblate.org/projects/keycloak/), a web-based translation platform, to manage translations of user interfaces and error messages.
61
+
62
+
It allows for notifications when the original string changes, and keeps track of missing translations. It also allows contributors without knowledge of Git to contribute to the translations.
63
+
64
+
The following translations are available in Weblate. If you have any questions or need assistance, feel free to reach out to the language maintainers listed below:
To add a new language, see the section "Steps to Add a new language to Weblate" below.
73
+
74
+
**Tasks of the translator:**
75
+
76
+
1. Sign Up: Visit Weblate to create an account.
77
+
2. Configuration: After signing up, configure your Weblate account settings according to your preferences. Please note that the committer email is set to the login email address by default. You can adjust this in your Weblate profile under Account settings.
78
+
3. Navigate to [Keycloak on Weblate](https://hosted.weblate.org/projects/keycloak/), confirm the contribution agreement, and start contributing translations.
79
+
4. For all untranslated and not-yet-approved keys you can directly add or update the translation.
80
+
5. For all approved keys you can suggest an alternative translation.
81
+
82
+
**Tasks of the maintainer:**
83
+
84
+
Weblate will create automated pull requests based on new or updated translations within 24 hours.
85
+
The goal is to merge those pull requests within 2-3 working days.
86
+
Translations are reviewed in Weblate by language maintainers for their correctness, still maintainers do some minimal checks as outlined below.
87
+
88
+
1. Check that the changes to the `messages_*.properties` files are syntactically correct.
89
+
2. Do a spot-check with Google Translate to avoid malicious community translations.
90
+
3. If the changes are ok, approve the PR and merge it. For pull requests created by Weblate there is no referenced GitHub issue, therefore reference the ID of the pull request in the squash-message.
91
+
4. Once the PR is merged, notify the respective language maintainers via a comment in the pull request that there are changes for their languages.
92
+
93
+
**Tasks of the language maintainers:**
94
+
95
+
**Goal:** Before a minor or major release that is due every three months, all translations should be in the state approved and all suggested translation should be reviewed. A language that misses that goal will be removed from Weblate, and translations will then only be possible via GitHub pull requests afterwards.
96
+
97
+
1. Review all translations from the community (`state:=translated`) for your language, review them and set them to **Approved**.
98
+
2. Review all translations that have community suggestions (`has:suggestion`) for your language, review them and approve or reject the suggestions.
99
+
3. When notified that translation changes have been merged in a PR, review the translations that originated either from the community of from a co-maintainer of the language in that pull request, and issue any necessary updates via Weblate.
100
+
101
+
> [!TIP]
102
+
> We recommend language maintainers to set up notifications in Weblate to receive email notifications of outstanding tasks.
103
+
104
+
All language maintainers are set up in Weblate as reviewers for their language according to Weblate's "Dedicated Reviewers" process.
105
+
106
+
## Steps to add a new language to Weblate
107
+
108
+
We rely on volunteers like you to take the initiative in steering the translation efforts for additional translations. If you're interested in contributing translations for a language not listed above, join the [localization platform discussion](https://github.com/keycloak/keycloak/discussions/9270):
65
109
66
110
- Check the discussion, if your language is already proposed [discussion thread](https://github.com/keycloak/keycloak/discussions/9270).
67
111
- Each language requires **two volunteers**
@@ -72,7 +116,7 @@ If you have any questions or need assistance, feel free to reach out to the lang
72
116
- comment on discussion thread, that the language has been enabled
73
117
- Weblate synchronizes daily, so it may take up to 24 hours after enabling the language before you can start your first translations
0 commit comments