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