056-weblate-integration.rst (7220B)
1 DD 56: Weblate integration 2 ########################## 3 4 :Design status: Superseded 5 :Implementation status: Implemented 6 :DD shepherd: TBD 7 :Historical contributors: Sebastian, Christian Grothoff 8 :First published: 2024-07-08 9 :Last substantive change: 2024-09-02 10 :Implementation evidence: taler-ios (2024-08-22) 11 :Superseded by: The XLIFF-based Weblate workflow in the taler-ios repository 12 :Normative references: :doc:`../developer/taler-developer-manual` 13 14 .. warning:: 15 16 The proposed pogen conversion for iOS was not the path ultimately adopted. 17 The iOS repository uses XLIFF files for Weblate integration. The proposal 18 below is retained as non-normative historical context. 19 20 Summary 21 ======= 22 23 We are using `Weblate <https://weblate.taler.net/>`__ to translate string in all 24 software components. Weblate should be able to read which strings needs to be 25 translated and return a translated version of the string for all the languages 26 supported. 27 28 Motivation 29 ========== 30 31 Every development ecosystem has it's own i18n framework. 32 33 * Android has strings.xml 34 * Apple has Localizable.strings but it's deprecated 35 * We are using gettext PO as default 36 37 38 There is no standard file format in iOS, the current suggested format 39 is not supported by Weblate and looks like it's never going to be a 40 open documentation about it: 41 42 from `Apple developer forum <https://forums.developer.apple.com/forums/thread/732120?answerId=756602022#756602022>`__ 43 44 String Catalogs store an entire string table in a single JSON file, 45 even if there are a large number of keys and languages. If this ends 46 up presenting a problem (with Xcode's performance, for example), please send 47 some feedback our way. 48 As for the specifics of the JSON format itself, we have not published 49 documentation because it is primarily intended to be read/written by Xcode. 50 If you do end up writing your own parser for this format, please be aware 51 that Xcode reserves the right to change it. 52 53 54 What we are doing right now 55 --------------------------- 56 57 How strings are generated: 58 59 *Android*: 60 Defines a key (like "send_deposit_amount_effective" or "amount_effective"), 61 this key has a default English translation in **strings.xml** and some other langs in **strings-{lang}.xml**. 62 63 *iOS*: 64 Uses the English text in the source code, or can also use a key. 65 It has just one file with translations, **Localizable.xcstrings**. 66 67 *SPA*: 68 It has the English string enclosed with i18n reference 69 and all those strings ends up in a file **src/i18n/strings.ts** which maps the English 70 sentence with a translated phrase. (the english sentence is used as a key) 71 72 For the integration in to weblate: 73 74 *Android*: 75 Weblate just takes **strings.xml** and **strings-{lang}.xml**, creates a list of all 76 strings to be translated and once you add new value for untranslated string or 77 change an existing one it modifies the correct file and commit with the new XML. 78 The project will automatically take this values. 79 80 *iOS*: 81 At the time this document was written, no integration had been found. The 82 subsequent implementation uses XLIFF files exported from the string 83 catalogs. 84 85 *SPA*: 86 The **strings.ts** file is not recognized by Weblate, so we generate **.po** files 87 which are supported by weblate. We have a script (pogen) that parses all the source code and 88 generate **.po** files, PO files are understood by Weblate and it will appear in the webapp 89 to be translated. Once the translator change some strings the PO files are updated with 90 the translations. When the changes are push into the repo, the developer can run a second 91 script (pogen) to sync the **.po** files with the **strings.ts**. Once in the **strings.ts** file the 92 app can show it in the UI. 93 94 95 Requirements 96 ============ 97 98 1. We should integrate weblate and iOS development 99 2. Translator should not translate 2 strings twice: if we can, we should reuse strings between apps 100 3. It should be clear whether we need to define a new string or add more context to the current strings 101 4. Stick to the `supported formats <https://docs.weblate.org/en/latest/formats.html>`__ 102 103 Proposed Solution 104 ================= 105 106 What we need to do to support iOS 107 --------------------------------- 108 109 We should move into something more like what we are doing with the SPA since we don't have 110 full support for **Localizable.xcstrings** and this file is kind of the same as **strings.ts** 111 (one big json with the mappings). 112 113 That will mean: 114 115 1. dev code, code, code (adding new strings to be translated, removing some other strings) 116 2. dev run script to sync **Localizable.xcstrings** with **file-that-weblate-understands.po** 117 3. translators translate and push changes 118 4. dev run script to sync **file-that-weblate-understands.po** with **Localizable.xcstrings** 119 120 We only need to use our existing software **pogen** to create **po** files from the 121 **Localizable.xcstrings** which seems really easy. And then also update the 122 **Localizable.xcstrings** from the updated **po** files. 123 124 This will not stop us from using XLIFF exporting/importing. 125 126 What we need to do to reduce the work load in the translators side 127 ------------------------------------------------------------------ 128 129 We can split the problem in topics 130 131 Using the same i18n key between apps: 132 we should stick to DD53 Wallet Design and use this to define 133 which strings developers should use. If the string is defined 134 there then it should be used in the code. That will create a spec 135 for the 3 platforms and it should use the same key. 136 137 Using translation memory in weblate config: 138 from weblate documenantion, this can be used to automatically 139 share translations. 140 141 Using context keys for short keys: 142 Sometimes the words like "close" or "transfer" could have separated 143 meaning depending on the context. For that cases we have the 144 **msgctxt** (that is additional key in addition to the short 145 sentence). Only same sentence with same context are equivalent. 146 We can also add some more context, like a link to the screenshot 147 in the design document so we can trigger an alarm if an image in the 148 weblate translation is out of sync with an image in DD 53. 149 150 Using images in weblate: 151 We should keep DD 53 updated (with the screens and text) and add 152 information in the string sentence (like context) to point into 153 the right location. 154 155 156 What we need to do to reduce the work load in the translators side 157 ------------------------------------------------------------------ 158 159 1. devs and Weblate maintainers look into DD53 + Weblate maintainers take care of checks and keep the repos consistent and up-to-date 160 2. translators know the apps and strings very well and manage ambiguities 161 3. translators and reviewers take a look at: 162 163 * the context message ID / key 164 * string location in the source code 165 * "nearby strings" 166 * comments 167 * the history of string changes 168 169 4. devs and Weblate maintainers add screenshots to ambiguous strings 170 5. devs add context via msgctxt through the pogen script 171 172 173 174 175 Definition of Done 176 ================== 177 178 * [x] iOS app has a semi-automated XLIFF integration with Weblate 179 * [ ] ``msgctxt`` support verified for every platform 180 181 Alternatives 182 ============ 183 184 Drawbacks 185 ========= 186 187 Discussion / Q&A 188 ================