commit 6373415dd2ee5ed3aca6a297bcd44f0bed5fd701
parent e716a555200bf7d51c7827902be632f7aeafd1b5
Author: Sebastian <sebasjm@gmail.com>
Date: Mon, 8 Jul 2024 11:37:27 -0300
fix #8873
Diffstat:
2 files changed, 170 insertions(+), 0 deletions(-)
diff --git a/design-documents/056-weblate-integration.rst b/design-documents/056-weblate-integration.rst
@@ -0,0 +1,169 @@
+DD 56: Weblate integration
+##########################
+
+Summary
+=======
+
+We are using `Weblate <https://weblate.taler.net/>`__ to translate string in all
+software components. Weblate should be able to read which strings needs to be
+translated and return a translated version of the string for all the languages
+supported.
+
+Motivation
+==========
+
+Every development ecosystem has it's own i18n framework.
+
+* Android has strings.xml
+* Apple has Localizable.strings but it's deprecated
+* We are using gettext PO as default
+
+
+There is no standard file format in iOS, the current suggested format
+is not supported by Weblate and looks like it's never going to be a
+open documentation about it:
+
+from `Apple developer forum <https://forums.developer.apple.com/forums/thread/732120?answerId=756602022#756602022>`__
+
+ String Catalogs store an entire string table in a single JSON file,
+ even if there are a large number of keys and languages. If this ends
+ up presenting a problem (with Xcode's performance, for example), please send
+ some feedback our way.
+ As for the specifics of the JSON format itself, we have not published
+ documentation because it is primarily intended to be read/written by Xcode.
+ If you do end up writing your own parser for this format, please be aware
+ that Xcode reserves the right to change it.
+
+
+What we are doing right now
+---------------------------
+
+How strings are generated
+
+*Android*:
+ Defines a key (like "send_deposit_amount_effective" or "amount_effective"),
+ this key has a default English translation in **strings.xml** and some other langs in **strings-{lang}.xml**.
+
+*iOS*:
+ Uses the English text in the source code, or can also use a key.
+ It has just one file with translations, **Localizable.xcstrings**.
+
+*SPA*:
+ It has the English string enclosed with i18n reference
+ and all those strings ends up in a file **src/i18n/strings.ts** which maps the English
+ sentence with a translated phrase. (the english sentence is used as a key)
+
+For the integration in to weblate:
+
+*Android*:
+ Weblate just takes **strings.xml** and **strings-{lang}.xml**, creates a list of all
+ strings to be translated and once you add new value for untranslated string or
+ change an existing one it modifies the correct file and commit with the new XML.
+ The project will automatically take this values.
+
+*iOS*:
+ No integration has been found.
+
+*SPA*:
+ The **strings.ts** file is not recognized by Weblate, so we generate **.po** files
+ which are supported by weblate. We have a script (pogen) that parses all the source code and
+ generate **.po** files, PO files are understood by Weblate and it will appear in the webapp
+ to be translated. Once the translator change some strings the PO files are updated with
+ the translations. When the changes are push into the repo, the developer can run a second
+ script (pogen) to sync the **.po** files with the **strings.ts**. Once in the **strings.ts** file the
+ app can show it in the UI.
+
+
+Requirements
+============
+
+1. We should integrate weblate and iOS development
+2. Translator should not translate 2 strings twice: if we can, we should reuse strings between apps
+3. It should be clear wether we need to define a new string or add more context to the current strings
+4. Stick to the `supported formats <https://docs.weblate.org/en/latest/formats.html>`__
+
+Proposed Solution
+=================
+
+What we need to do to support iOS
+---------------------------------
+
+We should move into something more like what we are doing with the SPA since we don't have
+full support for **Localizable.xcstrings** and this file is kind of the same as **strings.ts**
+(one big json with the mappings).
+
+That will mean:
+
+1. dev code, code, code (adding new strings to be translated, removing some other strings)
+2. dev run script to sync **Localizable.xcstrings** with **file-that-weblate-understands.po**
+3. translators translate and push changes
+4. dev run script to sync **file-that-weblate-understands.po** with **Localizable.xcstrings**
+
+We only need to use our existing software **pogen** to create **po** files from the
+**Localizable.xcstrings** which seems really easy. And then also update the
+**Localizable.xcstrings** from the updated **po** files.
+
+This will not stop us from using XLIFF exporting/importing.
+
+What we need to do to reduce the work load in the translators side
+------------------------------------------------------------------
+
+We can split the problem in topics
+
+Using the same i18n key between apps:
+ we should stick to DD53 Wallet Design and use this to define
+ which strings developers should use. If the string is defined
+ there then it should be used in the code. That will create a spec
+ for the 3 platforms and it should use the same key.
+
+Using translation memory in weblate config:
+ from weblate documenantion, this can be used to automatically
+ share translations.
+
+Using context keys for short keys:
+ Sometimes the words like "close" or "transfer" could have separated
+ meaning depending on the context. For that cases we have the
+ **msgctxt** (that is additional key in addition to the short
+ sentence). Only same sentence with same context are equivalent.
+ We can also add some more context, like a link to the screenshot
+ in the design document so we can trigger an alarm if an image in the
+ weblate translation is out of sync with an image in DD 53.
+
+Using images in weblate:
+ We should keep DD 53 updated (with the screens and text) and add
+ information in the string sentence (like context) to point into
+ the right location.
+
+
+What we need to do to reduce the work load in the translators side
+------------------------------------------------------------------
+
+1. devs and Weblate maintainers look into DD53 + Weblate maintainers take care of checks and keep the repos consistent and up-to-date
+2. translators know the apps and strings very well and manage ambiguities
+3. translators and reviewers take a look at the context
+ message ID / key,
+ string location in the source code / "nearby strings",
+ comments,
+ the history of string changes
+4. devs and Weblate maintainers add screenshots to ambiguous strings
+5. devs add context via msgctxt through the pogen script
+
+
+
+
+Definition of Done
+==================
+
+* When iOS app has a complete semi-automated integration with weblate
+* Adding msgctxt works for every platforms
+
+Alternatives
+============
+
+Drawbacks
+=========
+
+Discussion / Q&A
+================
+
+
diff --git a/design-documents/index.rst b/design-documents/index.rst
@@ -67,4 +67,5 @@ Design documents that start with "XX" are considered deprecated.
053-wallet-ui.rst
054-dynamic-form.rst
055-wallet-problem-report.rst
+ 056-weblate-integration.rst
999-template
