taler-android

Android apps for GNU Taler (wallet, PoS, cashier)
Log | Files | Refs | README | LICENSE

contacts-and-mailbox-cannot-be-translated.md (9022B)


      1 <!--
      2   This file is part of GNU Taler
      3   (C) 2026 Taler Systems S.A.
      4 
      5   GNU Taler is free software; you can redistribute it and/or modify it under the
      6   terms of the GNU General Public License as published by the Free Software
      7   Foundation; either version 3, or (at your option) any later version.
      8 
      9   GNU Taler is distributed in the hope that it will be useful, but WITHOUT ANY
     10   WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
     11   A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
     12 
     13   You should have received a copy of the GNU General Public License along with
     14   GNU Taler; see the file COPYING.  If not, see <http://www.gnu.org/licenses/>
     15 -->
     16 
     17 # Two whole features are untranslatable, and nothing in the repo can tell
     18 
     19 Found while reading the contacts screens for the alias-registration work: every
     20 label on them is an English string literal in the Compose source rather than an
     21 entry in `strings.xml`.
     22 
     23 **Severity: moderate.** The wallet ships 19 translations and the project keeps a
     24 135-term glossary in 27 languages (`dictionary.md`), but the contacts and
     25 mailbox features will be English in all of them, and no amount of translation
     26 work can change that. Two strings on the *payment prompt* — a screen every user
     27 sees — are in the same state, as is the transaction list's selection counter.
     28 
     29 ## What happens
     30 
     31 `res/values/strings.xml` is the source of truth for translations, and
     32 `./check-translations.py` compares every `values-<lang>/strings.xml` against
     33 it. A literal passed to a Composable is in neither file, so it is invisible to
     34 both the translators and the checker: coverage reads 100 % while the screen is
     35 half English.
     36 
     37 Set the wallet's language to German and the whole UI follows — except these:
     38 
     39 | Where | Untranslatable, user-visible strings |
     40 | --- | --- |
     41 | `contacts/ContactScreen.kt` | 18 — the screen title (`Contacts`, or `Send to Contact` when forwarding a payment), `Add Contact`, `Petname`, `Alias`, `Alias Type`, `Mailbox`, `Lookup with Taldir`, `Search contacts...`, `No contacts yet.`, `Loading...`, `Error: …`, `Lookup failed: …`, `A contact with this alias and type already exists.`, `Send to <petname>`, `Are you sure you want to send this to <petname>?`, and the `Add Contact`/`Delete` content descriptions |
     42 | `mailbox/MailboxScreen.kt` | 16 — `Mailbox`, `Your Mailbox Address`, `Configure Mailbox URL`, `Mailbox Base URL`, `No messages yet.`, `Loading...`, `Error: …`, the `Accept payment` and `Pay invoice` buttons on a message, its `From: …` and `Received: …` lines, the `Mailbox address URI copied to clipboard` toast, and the `Show Mailbox Address`/`Configure Mailbox`/`Refresh`/`Delete` content descriptions |
     43 | `settings/SettingsScreen.kt:257-272` | 5 — the `Contacts` and `Mailbox` entries with their summaries (`Contacts`, `P2P Messaging`), and the `Taldir Registration` summary |
     44 | `contacts/ContactManager.kt:169` | `Alias not found` |
     45 | `payment/PaymentManager.kt:395` | `The order could not be found. Maybe the merchant deleted it.` |
     46 | `main/MainViewModel.kt:503` | `Database migration completed without switching to SQLite` |
     47 | `compose/ExpandableCard.kt:96` | the `Drop Down Arrow` content description |
     48 
     49 **43 strings in all.** Three more (`Error`, `Event`, `Bitcoin`) are `ClipData`
     50 labels on copy buttons, which some Android versions show in the "copied" toast.
     51 Everything else a literal scan turns up is `@Preview` fixture data, commented
     52 out, a `@Deprecated` message, a log line, a wallet-core operation name, or a
     53 token that should not be translated (`payto://`, `https://`, `Cy` for Cyclos).
     54 
     55 The drift is visible inside a single call. The third settings entry in that
     56 block takes its title from a resource and hard-codes its summary:
     57 
     58 ```kotlin
     59 // wallet/src/main/java/net/taler/wallet/settings/SettingsScreen.kt:271
     60 SettingsItem(
     61     title = stringResource(R.string.alias_registration_title),
     62     summary = "Taldir Registration",
     63 ```
     64 
     65 Two details sharpen it:
     66 
     67 * **`contacts_title` already exists** in `strings.xml` (`<string
     68   name="contacts_title">Contacts</string>`) and is translated in the shipped
     69   languages — but it is used for the *forward* button on a peer transaction
     70   (`compose/QrCodeUriComposable.kt:199`), while the settings entry that opens
     71   the contacts screen hard-codes the same word. One of the two spellings of
     72   "Contacts" in this app is translatable and the other is not.
     73 * **The neighbouring file gets it right.**
     74   `contacts/AliasRegistrationScreen.kt`, in the same package, uses
     75   `stringResource` for all 14 of its labels. So this is drift, not a
     76   convention.
     77 
     78 One literal that a scan flags is *not* a live defect, and is worth naming so
     79 nobody re-files it: `compose/SelectionModeTopAppBar.kt:48` renders
     80 `"${selectedItems.size} selected"`, but that composable has no caller —
     81 `TransactionsScreen` implements selection mode inline and uses
     82 `stringResource(R.string.selection_count, …)` for the same text. The dead copy
     83 is the hard-coded one.
     84 
     85 That live resource has a smaller problem of its own:
     86 
     87 ```xml
     88 <!-- res/values/strings.xml:93 -->
     89 <string name="selection_count">%1$d selected</string>
     90 ```
     91 
     92 A count belongs in a `<plurals>` resource; as a single string it cannot be
     93 declined in languages that need it, and "1 selected" is wrong in several of the
     94 19 the wallet ships.
     95 
     96 ## Why the tooling misses it
     97 
     98 The repo's defences are both aimed at `strings.xml`:
     99 
    100 * `./check-translations.py` reads `values*/strings.xml` and reports missing or
    101   extra keys, format-argument mismatches and string-array lengths. A string
    102   that was never a resource cannot be missing from a translation.
    103 * Android lint's `HardcodedText` check only looks at layout XML. These screens
    104   are Compose, so there is no layout file and nothing is flagged — `wallet`
    105   builds with `abortOnError true` and `ignoreWarnings false` and still passes.
    106 
    107 ## Reproduce by hand
    108 
    109 The per-app language setting needs no root (Android 13+):
    110 
    111 ```bash
    112 adb shell cmd locale set-app-locales net.taler.wallet.fdroid.debug --locales de-DE
    113 adb shell am force-stop net.taler.wallet.fdroid.debug     # see the note below
    114 # open the wallet: it reads "Willkommen bei Taler Wallet!", "QR-Code scannen",
    115 # "Einstellungen" …
    116 # and Settings, in German, lists "Contacts" and "Mailbox"
    117 adb shell cmd locale set-app-locales net.taler.wallet.fdroid.debug --locales   # undo
    118 ```
    119 
    120 Expected: the two entries, and everything behind them, in the device's
    121 language.
    122 
    123 The `force-stop` is not politeness: changing the language *without* restarting
    124 the wallet drops it on its initialization error screen, which is a separate
    125 defect — [`config-change-locks-the-wallet-out-of-its-database.md`](config-change-locks-the-wallet-out-of-its-database.md).
    126 
    127 ## Reproduce with the simulator
    128 
    129 ```bash
    130 ssh root@tripwire.taler.net
    131 cd /opt/taler-sim/driver
    132 python3 ../findings/repro_untranslated_contacts_mailbox.py emulator-5554
    133 ```
    134 
    135 It sets the language, restarts the wallet, and then walks to both screens —
    136 needing `Settings|Einstellungen` to find its way and plain English for
    137 everything after that:
    138 
    139 ```
    140 the wallet is in German: ['Einstellungen', 'QR-Code scannen',
    141                           'Willkommen bei Taler Wallet', 'abheben']
    142   home screen: Wallet | Willkommen bei Taler Wallet! | Um Ihre erste Zahlung
    143   zu tätigen, heben Sie digitales Bargeld ab | CHF abheben | … |
    144   Einstellungen | Internes Ereignisprotokoll | QR-Code scannen
    145 
    146 === Contacts (reached by its English name)
    147   Search contacts... | No contacts yet. | Contacts | Add Contact
    148   3 untranslatable labels: ['Add Contact', 'No contacts yet', 'Search contacts']
    149 
    150 === Mailbox (reached by its English name)
    151   No messages yet. | Mailbox | Show Mailbox Address | Configure Mailbox | Refresh
    152   2 untranslatable labels: ['No messages yet', 'Mailbox']
    153 
    154 reproduced: True (5 English labels in a German wallet, plus the two settings
    155 entries that opened them)
    156 ```
    157 
    158 Five is all an empty wallet shows; the other 39 need a contact, a message, a
    159 lookup or an error to be on screen. The table above is from the sources, not
    160 from this run.
    161 
    162 ## Suggested fix
    163 
    164 Move the literals into `res/values/strings.xml` and reference them with
    165 `stringResource`, as `AliasRegistrationScreen.kt` already does, and give the
    166 settings entry a resource of its own rather than hard-coding the word that
    167 `contacts_title` already holds. Separately, make `selection_count` a
    168 `<plurals>`. The content descriptions matter twice over, since they are what a
    169 screen reader announces — see
    170 [`action-buttons-have-no-accessible-name.md`](action-buttons-have-no-accessible-name.md).
    171 
    172 To stop it coming back, something has to look at Kotlin rather than at XML. The
    173 scan that produced the table above is three lines of Python over
    174 `wallet/src/main/java`, matching string literals passed to `Text(…)` and to the
    175 `title`/`label`/`placeholder`/`contentDescription` parameters, and skipping
    176 `@Preview` bodies; as a check in `./check-translations.py` it would have caught
    177 each of these the day it was written.