docs(i18n): trace mail display and callback localisation boundaries
This commit is contained in:
@@ -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.
|
||||
@@ -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.
|
||||
|
@@ -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
|
||||
|
@@ -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()
|
||||
Reference in New Issue
Block a user