docs(i18n): trace mail display and callback localisation boundaries

This commit is contained in:
cesnimda
2026-11-19 14:12:28 +01:00
parent a404c913b1
commit 97b1948cfe
4 changed files with 183 additions and 0 deletions
+23
View File
@@ -0,0 +1,23 @@
# Mail and connection messages in the European localisation inventory
B05 extends the I18N-00 inventory to the full mail subset of B03’s remaining quoted lines. It also follows multiline HTML into the actual popup and application presenters. The two CSVs are source-review material for the existing 24 EU language groups and 60 planned locale tags. The active research branch started from `a404c913b1e779fb4e9aac9abbfa9bacd2743a28`; its application references use `5fd5c470452ae78ab46e74b7c1d8fb4336a7484d`.
## What enters translation review
[Mail display occurrences](B05_MAIL_DISPLAY.csv) records 21 literal occurrences on 18 source lines, representing 18 distinct English strings. It gives the owner, source line, display role, English text with any placeholders, context and handling of private values. Occurrences are retained separately when the same English text has different owners or display paths. This is a bounded source inventory rather than 21 proposed runtime keys.
| Screen or boundary | Source evidence on the application commit | Localisation implication |
| --- | --- | --- |
| Gmail and Outlook connection popups | GmailController 706–727, GmailParsing 89–112, MicrosoftGraphController 72–93 and 116–139 | Visible tab titles, success/failure headings, close instructions and callback details need an explicit language owner. Both HTML templates omit a document language. A quote-bearing-line scan alone misses the titles and close instructions in multiline HTML. |
| Settings connection feedback | emailOAuth.ts 19–26, EmailProviderConnections.tsx 109–121 | The validated popup callback supplies the toast body when its message is nonempty. Existing translated success/failure fallbacks only cover missing/empty messages. Preserve provider identifiers, the attempt/origin/window checks and separate the translated frame from provider-error and mailbox parameters. Never submit actual mailbox or exception text for translation. |
| Gmail matching and review | GmailController 138 and 235, GmailReviewPage.tsx 266 | When the backend substitutes “(no subject)”, the review heading can show the English fallback in any UI language. Preserve real subject text, including mail whose author actually used those words. The review queue and job-match paths have separate source loci. |
| Correspondence sender | EmailController 226–232, GmailController 900–906, CorrespondenceInboxPage.tsx 838 and 842 | The inbox shows the external sender when available and otherwise renders the stored sender field. “Me” and “Company” can therefore be visible. A future presenter must use proven role metadata for system values and preserve historical or user-entered names. Direction already has an independent translated chip. |
| Persisted channel and delivery state | EmailController 183–257, GmailController 876–938 | “Email” is a stored channel label with no confirmed visible presenter in this check. Keep its display ownership open. Delivery/error/route/event values remain machine contracts, even when they contain English words. |
## Coverage and verification
[Mail frontier dispositions](B05_MAIL_FRONTIER.csv) partitions **149 of B03’s 708 lines** under nine mail controllers/provider owners. The compared raw Git blobs are identical on the B03 application source and the newer A3 audit source. The 149 comparable lines comprise 53 endpoint or policy lines, 50 identifiers or format lines, 12 provider identity/branding lines, 10 display-source lines, 9 comments, 5 private search-expression lines, 4 persisted-display ambiguities, 4 template-markup lines and 2 opaque exception lines. A role describes the source line’s use; it does not make every substring on the line a translation candidate. The separate display CSV includes supporting lines outside the 149, so its row count must not be added to the coverage count.
Run `python docs/i18n/00/B05_mail_tests.py -v` from the worktree with the two historical Git commits available locally. **4 tests passed**, zero skipped. They check the exact multiset of source-line identities, all nine byte-equivalent mail owners, each review occurrence, 9 presenter/guard anchors across four frontend files, and the frozen 60-candidate catalogue with communications still planned. The first local setup run failed before test execution because it compared a Windows working-copy digest to normalised bytes. The corrected test checks canonical Git LF digests and accepts normal checkout line endings.
**559 other quoted lines in B03 remain** across 19 owners. Quote-free strings, other source owners and unreviewed presenters remain eligible for I18N-00 inventory. Stages 01–08 retain their existing entry gates. No locale has gained translations, native approval, product support or release status through this inventory. No application/UI/provider/security runtime test was needed or executed for this documentation-only package.
+22
View File
@@ -0,0 +1,22 @@
owner,line,role,englishSource,parameterContext
GmailController,138,absent-subject,(no subject),Only the fallback when a source subject is blank. Preserve actual subjects verbatim.
GmailController,235,absent-subject,(no subject),Review queue fallback for a thread without a subject. Preserve original mail text.
EmailController,226,persisted-sender,Me,Historical sender role can appear when externalFrom is absent. Preserve arbitrary sender names.
GmailController,900,persisted-sender,Me,Conditional sender role for a linked mailbox. Preserve historical correspondence.
GmailController,900,persisted-sender,Company,Conditional counterparty role. Never infer that any real sender named Company is synthetic.
GmailController,706,callback-detail,Google returned an error: {error},error is opaque provider text. Never send values to translators.
GmailController,711,callback-detail,Missing Google OAuth code or state.,Fixed callback failure. No token values are copy.
GmailController,717,callback-detail,This Gmail connection request is no longer valid. Start the connection again.,Fixed recovery instruction. Preserve Gmail branding.
GmailController,723,callback-detail,Connected Gmail: {result.GmailAddress},Mailbox address is private. Keep separate from the message template.
MicrosoftGraphController,72,callback-detail,Microsoft returned an error: {error},error is opaque provider text. Never send values to translators.
MicrosoftGraphController,77,callback-detail,Missing Microsoft OAuth code or state.,Fixed callback failure. No token values are copy.
MicrosoftGraphController,83,callback-detail,This Outlook connection request is no longer valid. Start the connection again.,Fixed recovery instruction. Preserve Outlook branding.
MicrosoftGraphController,89,callback-detail,Connected Outlook: {result.MailAddress},Mailbox address is private. Keep separate from the message template.
GmailParsing,93,callback-heading,Gmail connected,Success heading inside browser popup.
GmailParsing,93,callback-heading,Gmail connection failed,Failure heading inside browser popup.
GmailParsing,99,callback-title,Gmail connection,Browser document title in the provider callback.
GmailParsing,104,callback-instruction,You can close this window.,Visible instruction before the window closes.
MicrosoftGraphController,120,callback-heading,Outlook connected,Success heading inside browser popup.
MicrosoftGraphController,120,callback-heading,Outlook connection failed,Failure heading inside browser popup.
MicrosoftGraphController,126,callback-title,Outlook connection,Browser document title in the provider callback.
MicrosoftGraphController,131,callback-instruction,You can close this window.,Visible instruction before the window closes.
1 owner line role englishSource parameterContext
2 GmailController 138 absent-subject (no subject) Only the fallback when a source subject is blank. Preserve actual subjects verbatim.
3 GmailController 235 absent-subject (no subject) Review queue fallback for a thread without a subject. Preserve original mail text.
4 EmailController 226 persisted-sender Me Historical sender role can appear when externalFrom is absent. Preserve arbitrary sender names.
5 GmailController 900 persisted-sender Me Conditional sender role for a linked mailbox. Preserve historical correspondence.
6 GmailController 900 persisted-sender Company Conditional counterparty role. Never infer that any real sender named Company is synthetic.
7 GmailController 706 callback-detail Google returned an error: {error} error is opaque provider text. Never send values to translators.
8 GmailController 711 callback-detail Missing Google OAuth code or state. Fixed callback failure. No token values are copy.
9 GmailController 717 callback-detail This Gmail connection request is no longer valid. Start the connection again. Fixed recovery instruction. Preserve Gmail branding.
10 GmailController 723 callback-detail Connected Gmail: {result.GmailAddress} Mailbox address is private. Keep separate from the message template.
11 MicrosoftGraphController 72 callback-detail Microsoft returned an error: {error} error is opaque provider text. Never send values to translators.
12 MicrosoftGraphController 77 callback-detail Missing Microsoft OAuth code or state. Fixed callback failure. No token values are copy.
13 MicrosoftGraphController 83 callback-detail This Outlook connection request is no longer valid. Start the connection again. Fixed recovery instruction. Preserve Outlook branding.
14 MicrosoftGraphController 89 callback-detail Connected Outlook: {result.MailAddress} Mailbox address is private. Keep separate from the message template.
15 GmailParsing 93 callback-heading Gmail connected Success heading inside browser popup.
16 GmailParsing 93 callback-heading Gmail connection failed Failure heading inside browser popup.
17 GmailParsing 99 callback-title Gmail connection Browser document title in the provider callback.
18 GmailParsing 104 callback-instruction You can close this window. Visible instruction before the window closes.
19 MicrosoftGraphController 120 callback-heading Outlook connected Success heading inside browser popup.
20 MicrosoftGraphController 120 callback-heading Outlook connection failed Failure heading inside browser popup.
21 MicrosoftGraphController 126 callback-title Outlook connection Browser document title in the provider callback.
22 MicrosoftGraphController 131 callback-instruction You can close this window. Visible instruction before the window closes.
+31
View File
@@ -0,0 +1,31 @@
owner,role,lines
EmailController,endpoint-or-policy,30 31 41 63 81 99 128 129 264
EmailController,identifier-or-format,153 183 189 191 195 215 217 227 241 243 255 257
EmailController,persisted-display-ambiguity,226 229
EmailController,provider-brand-or-identifier,282 283 284
EmailDraftsController,endpoint-or-policy,13 14 73 121 151 169 204
EmailDraftsController,identifier-or-format,111 190
CorrespondenceController,endpoint-or-policy,15 16 73 184 198 270
CorrespondenceController,private-search-expression,104 105 106 107 108
CorrespondenceController,identifier-or-format,111 116 120 205 258
GmailController,endpoint-or-policy,15 41 59 67 177 304 375 507 541 614 670 701 731 739 747 777 807 994 1014
GmailController,provider-brand-or-identifier,38 581 917
GmailController,display-source,138 706 711 717 723
GmailController,identifier-or-format,263 264 265 267 269 270 283 298 299 300 309 316 357 360 440 485 492 499 522 576 609 665 693 694 876 901 930 936 938 1007
GmailController,comment,587
GmailController,opaque-provider-or-exception,727
GmailController,persisted-display-ambiguity,900 903
MicrosoftGraphController,comment,10
MicrosoftGraphController,endpoint-or-policy,15 40 58 67 97 107 113
MicrosoftGraphController,display-source,72 77 83 89 120
MicrosoftGraphController,opaque-provider-or-exception,93
MicrosoftGraphController,identifier-or-format,119
MicrosoftGraphController,template-markup,122 125 128 139
ImapController,comment,11
ImapController,endpoint-or-policy,14 42 63 83 93
GmailProvider,comment,6 7
GmailProvider,provider-brand-or-identifier,19 24
MicrosoftGraphProvider,comment,6 7
MicrosoftGraphProvider,provider-brand-or-identifier,19 24
ImapProvider,comment,6 7
ImapProvider,provider-brand-or-identifier,19 24
1 owner role lines
2 EmailController endpoint-or-policy 30 31 41 63 81 99 128 129 264
3 EmailController identifier-or-format 153 183 189 191 195 215 217 227 241 243 255 257
4 EmailController persisted-display-ambiguity 226 229
5 EmailController provider-brand-or-identifier 282 283 284
6 EmailDraftsController endpoint-or-policy 13 14 73 121 151 169 204
7 EmailDraftsController identifier-or-format 111 190
8 CorrespondenceController endpoint-or-policy 15 16 73 184 198 270
9 CorrespondenceController private-search-expression 104 105 106 107 108
10 CorrespondenceController identifier-or-format 111 116 120 205 258
11 GmailController endpoint-or-policy 15 41 59 67 177 304 375 507 541 614 670 701 731 739 747 777 807 994 1014
12 GmailController provider-brand-or-identifier 38 581 917
13 GmailController display-source 138 706 711 717 723
14 GmailController identifier-or-format 263 264 265 267 269 270 283 298 299 300 309 316 357 360 440 485 492 499 522 576 609 665 693 694 876 901 930 936 938 1007
15 GmailController comment 587
16 GmailController opaque-provider-or-exception 727
17 GmailController persisted-display-ambiguity 900 903
18 MicrosoftGraphController comment 10
19 MicrosoftGraphController endpoint-or-policy 15 40 58 67 97 107 113
20 MicrosoftGraphController display-source 72 77 83 89 120
21 MicrosoftGraphController opaque-provider-or-exception 93
22 MicrosoftGraphController identifier-or-format 119
23 MicrosoftGraphController template-markup 122 125 128 139
24 ImapController comment 11
25 ImapController endpoint-or-policy 14 42 63 83 93
26 GmailProvider comment 6 7
27 GmailProvider provider-brand-or-identifier 19 24
28 MicrosoftGraphProvider comment 6 7
29 MicrosoftGraphProvider provider-brand-or-identifier 19 24
30 ImapProvider comment 6 7
31 ImapProvider provider-brand-or-identifier 19 24
+107
View File
@@ -0,0 +1,107 @@
"""Verify the bounded B05 research inventory against local immutable Git sources."""
import csv
import hashlib
import json
import subprocess
import unittest
from collections import Counter
from functools import lru_cache
from pathlib import Path
HERE = Path(__file__).resolve().parent
ROOT = HERE.parents[2]
SOURCE = '5fd5c470452ae78ab46e74b7c1d8fb4336a7484d'
B03_SHA = '4298460dbc8b8e8d6dbc7e7a9663948274d01e0af989852a97e25854ca4bc98d'
CATALOGUE_SHA = 'fe57139831579f5bee482039a6bb15cb1eefb8e6f4f9263f8351d7465ac34cf6'
CONTROLLERS = {'EmailController', 'EmailDraftsController', 'CorrespondenceController',
'GmailController', 'MicrosoftGraphController', 'ImapController'}
PROVIDERS = {'GmailProvider', 'MicrosoftGraphProvider', 'ImapProvider'}
ROLES = {'endpoint-or-policy', 'identifier-or-format', 'persisted-display-ambiguity',
'provider-brand-or-identifier', 'private-search-expression', 'display-source',
'comment', 'opaque-provider-or-exception', 'template-markup'}
def rows(name):
with (HERE / name).open(encoding='utf-8', newline='') as source:
return list(csv.DictReader(source))
@lru_cache(maxsize=None)
def blob(commit, path):
return subprocess.check_output(['git', 'show', f'{commit}:{path}'], cwd=ROOT)
def research_json(name, digest):
data = (HERE / name).read_bytes().replace(b'\r\n', b'\n')
if hashlib.sha256(data).hexdigest() != digest:
raise ValueError(f'Unexpected research input: {name}')
return json.loads(data)
class MailInventory(unittest.TestCase):
@classmethod
def setUpClass(cls):
prior = research_json('B03_CENSUS.json', B03_SHA)
cls.prior_commit = prior['sourceCommit']
cls.owners = {Path(row['source']).stem: row for row in prior['ownerCoverage']
if Path(row['source']).stem in CONTROLLERS | PROVIDERS}
cls.paths = {owner: row['source'] for owner, row in cls.owners.items()}
cls.paths['GmailParsing'] = 'JobTrackerApi/Services/GmailParsing.cs'
def test_complete_mail_frontier_and_unchanged_source(self):
self.assertEqual(set(self.owners), CONTROLLERS | PROVIDERS)
expected = Counter((owner, line) for owner, row in self.owners.items()
for line in row['otherQuotedLinesNotClassified'])
actual = Counter()
for row in rows('B05_MAIL_FRONTIER.csv'):
self.assertIn(row['role'], ROLES)
actual.update((row['owner'], int(n)) for n in row['lines'].split())
self.assertEqual(actual, expected)
self.assertEqual(len(expected), 149)
for owner in self.owners:
path = self.paths[owner]
with self.subTest(owner=owner):
self.assertEqual(blob(SOURCE, path), blob(self.prior_commit, path))
def test_display_occurrences_and_private_parameters(self):
found = set()
for row in rows('B05_MAIL_DISPLAY.csv'):
owner, line, message = row['owner'], int(row['line']), row['englishSource']
with self.subTest(owner=owner, line=line, message=message):
source_line = blob(SOURCE, self.paths[owner]).decode().splitlines()[line - 1]
self.assertIn(message, source_line)
self.assertNotIn((owner, line, message), found)
self.assertTrue(row['parameterContext'].strip())
if '{' in message:
self.assertRegex(row['parameterContext'], r'private|opaque')
found.add((owner, line, message))
self.assertEqual(len(found), 21)
self.assertEqual(sum('close this window' in message for _, _, message in found), 2)
def test_presenter_and_fallback_traces(self):
sites = {
'src/emailOAuth.ts': {20: 'event.source !== attempt.popup', 24: 'data.status !== "connected"',
26: 'message: data.message'},
'src/components/EmailProviderConnections.tsx': {
113: 'emailOAuthMessage(event, attempt)', 117: 'toast(data.message || t(',
120: 'toast(data.message || t('},
'src/views/CorrespondenceInboxPage.tsx': {838: 'item.externalFrom || item.from',
842: 't(item.direction === "inbound"'},
'src/views/GmailReviewPage.tsx': {266: '{thread.subject}'},
}
for path, probes in sites.items():
source = blob(SOURCE, f'job-tracker-ui/{path}').decode().splitlines()
for line, text in probes.items():
with self.subTest(path=path, line=line):
self.assertIn(text, source[line - 1])
def test_research_scope(self):
catalogue = research_json('LOCALE_CATALOG.json', CATALOGUE_SHA)
self.assertEqual(len(catalogue['locales']), 60)
for locale in catalogue['locales']:
with self.subTest(tag=locale['tag']):
self.assertEqual(locale['surfaces']['communications'], 'planned')
if __name__ == '__main__':
unittest.main()