From 28ed753090cd5f55081706aa56de8ac921cf4b38 Mon Sep 17 00:00:00 2001 From: Benoit Marty Date: Tue, 28 Mar 2023 11:36:23 +0200 Subject: [PATCH 1/9] Add string key naming rules. --- tools/localazy/README.md | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/tools/localazy/README.md b/tools/localazy/README.md index dcb45c5be7..af040d17f7 100644 --- a/tools/localazy/README.md +++ b/tools/localazy/README.md @@ -4,10 +4,22 @@ Localazy is used to host the source strings and their translations. ## Localazy project -To add new strings, or to translate existing strings, go the the Localazy project: [https://localazy.com/p/element](https://localazy.com/p/element). +To add new strings, or to translate existing strings, go the the Localazy project: [https://localazy.com/p/element](https://localazy.com/p/element). Please follow the key naming rules (see below). Never edit manually the files `localazy.xml` or `translations.xml`!. +### Key naming rules + +For code clarity and in order to download strings to the correct module, here are some naming rules to follow as much as possible: + +- Keys for common strings, i.e. strings that can be used at multiple places must start by `action_` if this is a verb, or `common_` if not; +- Keys for strings used in a single screen must start with `screen_` followed by the screen name, followed by a free name. Example: `screen_onboarding_welcome_title`; +- Keys can have `_title` or `_subtitle` suffixes. Example: `screen_onboarding_welcome_title`, `screen_change_server_subtitle`; +- `a11y_` pattern can be used for strings used for accessibility. Example: `a11y_hide_password`, `screen_roomlist_a11y_create_message`; +- Strings for error message can start by `error_`, or contain `_error_` if used in a specific screen only. Example: `error_some_messages_have_not_been_sent`, `screen_change_server_error_invalid_homeserver`. + +*Note*: those rules applies for `strings` and for `plurals`. + ## CLI Installation To install the Localazy client, follow the instructions from [here](https://localazy.com/docs/cli/installation). From 965a8676a60d080bc2f077e2345dc5514dc671a7 Mon Sep 17 00:00:00 2001 From: Benoit Marty Date: Tue, 28 Mar 2023 14:03:52 +0200 Subject: [PATCH 2/9] Update documentation about strings. --- CONTRIBUTING.md | 32 ++++++++++++++++++++++---------- tools/localazy/README.md | 10 ++++++++++ 2 files changed, 32 insertions(+), 10 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5cd8785b33..0c462036b9 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -5,7 +5,9 @@ * [Contributing code to Matrix](#contributing-code-to-matrix) * [Android Studio settings](#android-studio-settings) * [Compilation](#compilation) -* [I want to help translating Element](#i-want-to-help-translating-element) +* [Strings](#strings) + * [I want to add new strings to the project](#i-want-to-add-new-strings-to-the-project) + * [I want to help translating Element](#i-want-to-help-translating-element) * [I want to submit a PR to fix an issue](#i-want-to-submit-a-pr-to-fix-an-issue) * [Kotlin](#kotlin) * [Changelog](#changelog) @@ -15,7 +17,6 @@ * [lint](#lint) * [Unit tests](#unit-tests) * [Tests](#tests) - * [Internationalisation](#internationalisation) * [Accessibility](#accessibility) * [Jetpack Compose](#jetpack-compose) * [Authors](#authors) @@ -40,11 +41,26 @@ Please ensure that you're using the project formatting rules (which are in the p This project should compile without any special action. Just clone it and open it with Android Studio, or compile from command line using `gradlew`. -## I want to help translating Element +## Strings -For now strings are coming from Element Android project, so: -- If you want to fix an issue with an English string, please submit a PR on Element Android. -- If you want to fix an issue in other languages, or add a missing translation, or even add a new language, please use [Weblate](https://translate.element.io/projects/element-android/). +The strings of the project are managed externally using [https://localazy.com](https://localazy.com) and shared with ElementX iOS. + +### I want to add new strings to the project + +Only the core team can modify or add English strings to Localazy. As an external contributor, if you want to add new strings, feel free to add an Android resource file to the project (for instance a file named `temporary.xml`), with a note in the description of the PR for the reviewer to integrate the String into `Localazy`. If accepted, the reviewer will add the String(s) for you, and then you can download them on your branch (following these [instructions](./tools/localazy/README.md#download-translations)) and remove the temporary file. + +Please follow the naming rules for the key. More details in [the dedicated section in this README.md](./tools/localazy/README.md#key-naming-rules) + +### I want to help translating Element + +Please note that the Localazy project is not open yet for external contributions. + +To help translating, please go to [https://localazy.com/p/element](https://localazy.com/p/element). + +- If you want to fix an issue with an English string, please open an issue on the github project of ElementX (Android or iOS).Only the core team can modify or add English strings. +- If you want to fix an issue in other languages, or add a missing translation, or even add a new language, please go to [https://localazy.com/p/element](https://localazy.com/p/element). + +More informations can be found [in this README.md](./tools/localazy/README.md). ## I want to submit a PR to fix an issue @@ -135,10 +151,6 @@ Also, if possible, please test your change on a real device. Testing on Android You should consider adding Unit tests with your PR, and also integration tests (AndroidTest). Please refer to [this document](./docs/integration_tests.md) to install and run the integration test environment. -### Internationalisation - -For now strings are coming from Element Android project, so please read [the documentation](https://github.com/vector-im/element-android/blob/develop/CONTRIBUTING.md#internationalisation) from there. - ### Accessibility Please consider accessibility as an important point. As a minimum requirement, in layout XML files please use attributes such as `android:contentDescription` and `android:importantForAccessibility`, and test with a screen reader if it's working well. You can add new string resources, dedicated to accessibility, in this case, please prefix theirs id with `a11y_`. diff --git a/tools/localazy/README.md b/tools/localazy/README.md index af040d17f7..e855b33992 100644 --- a/tools/localazy/README.md +++ b/tools/localazy/README.md @@ -2,6 +2,16 @@ Localazy is used to host the source strings and their translations. + + +* [Localazy project](#localazy-project) + * [Key naming rules](#key-naming-rules) +* [CLI Installation](#cli-installation) +* [Download translations](#download-translations) +* [Add translations to a specific module](#add-translations-to-a-specific-module) + + + ## Localazy project To add new strings, or to translate existing strings, go the the Localazy project: [https://localazy.com/p/element](https://localazy.com/p/element). Please follow the key naming rules (see below). From adf9b1bed93d354bef18ae99dcd92ceb048f2358 Mon Sep 17 00:00:00 2001 From: Benoit Marty Date: Tue, 28 Mar 2023 14:04:17 +0200 Subject: [PATCH 3/9] Add a note about the configuration. --- CONTRIBUTING.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0c462036b9..82602e7e63 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -41,6 +41,8 @@ Please ensure that you're using the project formatting rules (which are in the p This project should compile without any special action. Just clone it and open it with Android Studio, or compile from command line using `gradlew`. +Note: please make sure that the configuration is `app` and not `samples.minimal`. + ## Strings The strings of the project are managed externally using [https://localazy.com](https://localazy.com) and shared with ElementX iOS. From 7688cfb0310d71d72164ea539ab36e90fa931a14 Mon Sep 17 00:00:00 2001 From: Benoit Marty Date: Tue, 28 Mar 2023 14:05:50 +0200 Subject: [PATCH 4/9] Small clarification --- tools/localazy/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tools/localazy/README.md b/tools/localazy/README.md index e855b33992..6117cf17c0 100644 --- a/tools/localazy/README.md +++ b/tools/localazy/README.md @@ -25,7 +25,7 @@ For code clarity and in order to download strings to the correct module, here ar - Keys for common strings, i.e. strings that can be used at multiple places must start by `action_` if this is a verb, or `common_` if not; - Keys for strings used in a single screen must start with `screen_` followed by the screen name, followed by a free name. Example: `screen_onboarding_welcome_title`; - Keys can have `_title` or `_subtitle` suffixes. Example: `screen_onboarding_welcome_title`, `screen_change_server_subtitle`; -- `a11y_` pattern can be used for strings used for accessibility. Example: `a11y_hide_password`, `screen_roomlist_a11y_create_message`; +- `a11y_` pattern can be used for strings that are only used for accessibility. Example: `a11y_hide_password`, `screen_roomlist_a11y_create_message`; - Strings for error message can start by `error_`, or contain `_error_` if used in a specific screen only. Example: `error_some_messages_have_not_been_sent`, `screen_change_server_error_invalid_homeserver`. *Note*: those rules applies for `strings` and for `plurals`. From ae5a094fe42dbab5c36b38326edd3960b8477705 Mon Sep 17 00:00:00 2001 From: Benoit Marty Date: Tue, 28 Mar 2023 14:07:22 +0200 Subject: [PATCH 5/9] Add rule for string keys starting with `a11y`. --- tools/localazy/README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/tools/localazy/README.md b/tools/localazy/README.md index 6117cf17c0..10faf09ead 100644 --- a/tools/localazy/README.md +++ b/tools/localazy/README.md @@ -23,6 +23,7 @@ Never edit manually the files `localazy.xml` or `translations.xml`!. For code clarity and in order to download strings to the correct module, here are some naming rules to follow as much as possible: - Keys for common strings, i.e. strings that can be used at multiple places must start by `action_` if this is a verb, or `common_` if not; +- Keys for common accessibility strings must start by `a11y_`. Example: `a11y_hide_password`; - Keys for strings used in a single screen must start with `screen_` followed by the screen name, followed by a free name. Example: `screen_onboarding_welcome_title`; - Keys can have `_title` or `_subtitle` suffixes. Example: `screen_onboarding_welcome_title`, `screen_change_server_subtitle`; - `a11y_` pattern can be used for strings that are only used for accessibility. Example: `a11y_hide_password`, `screen_roomlist_a11y_create_message`; From bff138ae22d5e60f079e7a05fb48f96d23367137 Mon Sep 17 00:00:00 2001 From: Benoit Marty Date: Tue, 28 Mar 2023 14:09:46 +0200 Subject: [PATCH 6/9] typo --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 82602e7e63..125c69adb6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -59,7 +59,7 @@ Please note that the Localazy project is not open yet for external contributions To help translating, please go to [https://localazy.com/p/element](https://localazy.com/p/element). -- If you want to fix an issue with an English string, please open an issue on the github project of ElementX (Android or iOS).Only the core team can modify or add English strings. +- If you want to fix an issue with an English string, please open an issue on the github project of ElementX (Android or iOS). Only the core team can modify or add English strings. - If you want to fix an issue in other languages, or add a missing translation, or even add a new language, please go to [https://localazy.com/p/element](https://localazy.com/p/element). More informations can be found [in this README.md](./tools/localazy/README.md). From cbc7982cf5eb86e1a4ee0aa6a9811362783fe156 Mon Sep 17 00:00:00 2001 From: Benoit Marty Date: Tue, 28 Mar 2023 15:16:03 +0200 Subject: [PATCH 7/9] Add rules for platform suffixes. --- tools/localazy/README.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/tools/localazy/README.md b/tools/localazy/README.md index 10faf09ead..ed47efd2c3 100644 --- a/tools/localazy/README.md +++ b/tools/localazy/README.md @@ -6,6 +6,7 @@ Localazy is used to host the source strings and their translations. * [Localazy project](#localazy-project) * [Key naming rules](#key-naming-rules) + * [Special suffixes](#special-suffixes) * [CLI Installation](#cli-installation) * [Download translations](#download-translations) * [Add translations to a specific module](#add-translations-to-a-specific-module) @@ -31,6 +32,13 @@ For code clarity and in order to download strings to the correct module, here ar *Note*: those rules applies for `strings` and for `plurals`. +#### Special suffixes + +- if a key is suffixed by `_ios`, it will not be imported in the Android project; +- if a key is suffixed by `_android`, it will not be imported in the iOS project. + +So feel free to use those suffixes when necessary for instance when the string content is referring to something related to Android only, or iOS only. + ## CLI Installation To install the Localazy client, follow the instructions from [here](https://localazy.com/docs/cli/installation). From 43c070b01b7001874be0324944c9aae33f990d34 Mon Sep 17 00:00:00 2001 From: Benoit Marty Date: Wed, 5 Apr 2023 11:22:53 +0200 Subject: [PATCH 8/9] Add key naming rules for dialogs. --- tools/localazy/README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/tools/localazy/README.md b/tools/localazy/README.md index ed47efd2c3..58bd137932 100644 --- a/tools/localazy/README.md +++ b/tools/localazy/README.md @@ -27,6 +27,7 @@ For code clarity and in order to download strings to the correct module, here ar - Keys for common accessibility strings must start by `a11y_`. Example: `a11y_hide_password`; - Keys for strings used in a single screen must start with `screen_` followed by the screen name, followed by a free name. Example: `screen_onboarding_welcome_title`; - Keys can have `_title` or `_subtitle` suffixes. Example: `screen_onboarding_welcome_title`, `screen_change_server_subtitle`; +- For dialogs, keys can have `_dialog_title`, `_dialog_content`, and `_dialog_submit` suffixes. Example: `screen_signout_confirmation_dialog_title`, `screen_signout_confirmation_dialog_content`, `screen_signout_confirmation_dialog_submit`; - `a11y_` pattern can be used for strings that are only used for accessibility. Example: `a11y_hide_password`, `screen_roomlist_a11y_create_message`; - Strings for error message can start by `error_`, or contain `_error_` if used in a specific screen only. Example: `error_some_messages_have_not_been_sent`, `screen_change_server_error_invalid_homeserver`. From b410fc6983e740b68c5cef33fafa1d9c83e453b0 Mon Sep 17 00:00:00 2001 From: Benoit Marty Date: Wed, 5 Apr 2023 11:33:46 +0200 Subject: [PATCH 9/9] Add a section about placeholders. --- tools/localazy/README.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/tools/localazy/README.md b/tools/localazy/README.md index 58bd137932..395961f91b 100644 --- a/tools/localazy/README.md +++ b/tools/localazy/README.md @@ -7,6 +7,7 @@ Localazy is used to host the source strings and their translations. * [Localazy project](#localazy-project) * [Key naming rules](#key-naming-rules) * [Special suffixes](#special-suffixes) + * [Placeholders](#placeholders) * [CLI Installation](#cli-installation) * [Download translations](#download-translations) * [Add translations to a specific module](#add-translations-to-a-specific-module) @@ -40,6 +41,10 @@ For code clarity and in order to download strings to the correct module, here ar So feel free to use those suffixes when necessary for instance when the string content is referring to something related to Android only, or iOS only. +#### Placeholders + +Placeholders should have the form `%1$s`, `%1$d`, etc.. Please use numbered placeholders. Note that Localazy will take care of converting the placeholder to Android (-> `%1$s`) and iOS specific format (-> `%1$@`). Ideally add a comment on Localazy to explain with what the placeholder(s) will be replaced at runtime. + ## CLI Installation To install the Localazy client, follow the instructions from [here](https://localazy.com/docs/cli/installation).