From 46a5fd43bb7fa17131ae53f58605b01df153f0a8 Mon Sep 17 00:00:00 2001 From: Emmanuel Engelhart Date: Tue, 9 May 2023 08:08:01 +0200 Subject: [PATCH] Polishing of localisation documentation --- CONTRIBUTING.md | 72 +++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 41 ---------------------------- 2 files changed, 72 insertions(+), 41 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b0c5fd14d..ece59efdb 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -54,6 +54,12 @@ All branches should have distinct history and should be visually easy to follow, If you wish to rebase you should be following the [Golden Rule](https://www.atlassian.com/git/tutorials/merging-vs-rebasing#the-golden-rule-of-rebasing) and adhere to the advice in the heading [Aside: Rebase as cleanup is awesome in the coding lifecycle](https://www.atlassian.com/git/articles/git-team-workflows-merge-or-rebase). +### Committing + +For writing commit messages please read the +[COMMITSTYLE](docs/commitstyle.md) carefully. Kindly adhere to the +guidelines. Pull requests not matching the style will be rejected. + ### Design and style For an overview of how to make design changes to Kiwix Android, check out [DESIGN.md](https://github.com/kiwix/kiwix-android/blob/develop/DESIGN.md). @@ -119,3 +125,69 @@ learn more about the commands run on the CI please refer to [.github/workflows]( _These guidelines are based on [Tools for Government Data Archiving](https://github.com/edgi-govdata-archiving/overview/blob/master/CONTRIBUTING.md)'s._ + +## Code Style + +For contributions please read the [CODESTYLE](docs/codestyle.md) +carefully. Pull requests that do not match the style will be rejected. + +### Localization + +Kiwix Android is available in multiple languages. Translations of +string resources are managed by +[Translatewiki.net](https://translatewiki.net). + +When adding new strings to the code base (menu entries, warnings, +dialog, ...), developers are required to do it using a string +resource. + +When adding a string resource to the code base, developers +are required to provide additional context on how and where the new +string will be used. This helps translators to understand the context +and translate accurately. + +[More information about the Kiwix project in +Translatewiki.net](https://translatewiki.net/wiki/Translating:Kiwix). + +#### String resources + +Each user-visible string in Kiwix Android should be listed in +`strings.xml ` files to allow proper translation, replacement and +modification. + +Newly added string resources are imported by Translatewiki.net every +few days and and then manually translated by a community of +volunteers. + +Every few days, Translatewiki.net pushes automatically the new +translations in Kiwix Android git repository via a PR. + +##### Howto by example + +Start by adding your new string resource `new_string` to +`values/strings.xml` in English. That is: +``` +... +New String +... + +``` + +You will now have to describe the string in `values-qq/strings.xml` +with where and how the new string is used. E.x. for the string +`On`: `values-qq/strings.xml:` + +``` +... +This is used in the settings screen to turn on the night mode. +... +``` + +It's important to notice that: + +- The values in `values/strings.xml` are the strings that are going to + be displayed in the Kiwix application to the user. + +- The values in `values-qq/strings.xml` are only visible to the + translator and are only there to help them make a correct + translation. diff --git a/README.md b/README.md index 5827bfa9b..458169c00 100644 --- a/README.md +++ b/README.md @@ -61,47 +61,6 @@ We currently have a series of automated Unit and Integration tests. These can be run locally and are also run when submitting a pull request. -## Code Style - -For contributions please read the [CODESTYLE](docs/codestyle.md) -carefully. Pull requests that do not match the style will be rejected. - -## Commit Style - -For writing commit messages please read the -[COMMITSTYLE](docs/commitstyle.md) carefully. Kindly adhere to the -guidelines. Pull requests not matching the style will be rejected. - -## Localization - -Kiwix Android is available in multiple languages and managed by Translatewiki. -When adding new string resources, contributors are required to provide additional context on how and where the new string will be used. -This helps translators to understand the context and translate accurately. - -### String resources -All user visible strings in an Android application should be listed in strings.xml files to allow for easy translation, replacement and modification. -Newly added string resources are imported by translatewiki and are then manually translated. -After translations are complete the translations are merged with Kiwix Android. - -#### How do I add a new string resource? -Start by adding your new string resource `new_string` to `values/strings.xml` in English. That is: -``` -... -New String -... -``` -You will now have to describe the string in `values-qq/strings.xml` with where and how the new string is used. E.x. for the string `On`: - -`values-qq/strings.xml:` -``` -... -This is used in the settings screen to turn on the night mode. -... -``` -- The values in `values/strings.xml` are the strings that are going to be displayed in the Kiwix application to the user. -- The values in `values-qq/strings.xml` are only visible to the translator and are only there to help them make a correct translation. - - ## Communication Available communication channels: