First Commit

tools/localazy/README.md

@@ -0,0 +1,76 @@
+# Localazy
+
+Localazy is used to host the source strings and their translations.
+
+<!--- TOC -->
+
+* [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)
+
+<!--- END -->
+
+## Localazy project
+
+[![Localazy](https://img.shields.io/endpoint?url=https%3A%2F%2Fconnect.localazy.com%2Fstatus%2Felement%2Fdata%3Fcontent%3Dall%26title%3Dlocalazy%26logo%3Dtrue)](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 common accessibility strings must start by `a11y.`. Example: `a11y.hide_password`;
+- Keys for common strings should be named to match the string. Example: `action.copy_link` for the string `Copy link`;
+- When creating common strings, make sure to enable "Use dot (.) to create nested keys";
+- 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`;
+
+*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.
+
+#### 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).
+
+## Download translations
+
+In the root folder of the project, run:
+
+```shell
+./tools/localazy/downloadStrings.sh
+```
+
+It will update all the `localazy.xml` resource files. In case of merge conflicts, just erase the files and download again using the script.
+
+To also include the translations, i.e. the `translations.xml` files, add `--all` argument:
+
+```shell
+./tools/localazy/downloadStrings.sh --all
+```
+
+## Add translations to a specific module
+
+Edit the file [config.json](./config.json) to add a new module, or add a new item in `includeRegex` arrays, then run the script again to see the effect.
+
+[generateLocalazyConfig.py](generateLocalazyConfig.py) is the Python script that convert `config.json` to a localazy configuration file. Generally you should not edit this file.