The zh pair's other direction, and a rule pack that mostly says no
`pair_lang` had always been answering a second question nobody asked: it says which two languages, and every surface built on it assumed English was the one being learned. That is why hanzi is never tokenized, never spell-checked, never glossed — correct for a Mandarin native practising English, backwards for an English native practising Mandarin. `users.direction` (migration 0016) separates the two questions; a `zh-learner` pair code would have been cheaper and would have made two directions of one pair look like two unrelated languages to every query. Segmentation is what replaces `wordAt` where there are no spaces: a shortest-path walk over log-probabilities, 232 ms and 14 MB for 188,522 words. The browser gets the word list because segmentation runs on hover; the server keeps the whole dictionary. Their coverage gates come out opposite on purpose — the client list is frequency-gated because the segmentation is measurably identical without the tail, and the dictionary is gated by nothing, because its only power is to explain and the word a learner stops on is the rare one. The 错别字 pack is 24 confusable pairs behind two mechanical gates. One admits a pair only if the wrong form is not a dictionary word and the right form is, which is why it refuses 自已 for 自己 — a real error whose wrong form is a headword. The other asks the segmenter whether the two characters already belong to two different words, without which 自己经常, 睡觉的时候 and 不知到底 would all be corrupted silently into text still made of real characters. Not deployed (this carries a migration), not seen in a browser, and no account has ever been in the learner direction. The IME composition guards were in scope and are not done — see BUILD_PLAN Phase 26.
This commit is contained in:
prosolis
@@ -367,10 +367,40 @@ Scope agreed with the user 2026-07-28: **Latin American neutral, quorum review,
|
||||
- Verified: go build/vet, `go test ./...` clean, tsc, vite build, **vitest 251/251**. ⚠️ **Not seen in a browser** — no Chrome extension on this laptop; the 1.59 MB dictionary inflating in a real tab and the picker's fourth entry in a real mobile drawer are what unit tests cannot cover.
|
||||
- **Not deployed.** No migration, so it is a rebuild whenever the user wants it; `piper-es` wants `docker compose up -d piper-es` and a voice download on the box. **No es account exists**, and all three accounts are still on `zh` — flipping a pair is hers to do from the picker.
|
||||
|
||||
### Phase 26 — the zh pair's other direction (2026-07-28, code half) — segmentation, and a rule pack that mostly says no
|
||||
Scope agreed with the user 2026-07-28: **a `direction` column, segmentation + hover pinyin/gloss, 错别字 detection, IME guards** — code only, and this one carries a migration, so deploy is its own step. SUGGESTIONS §4 called this "its own phase with its own spec" and "Petal's next big product bet"; it is also the first phase whose user is the *other* writer — the one learning Chinese rather than the one learning English.
|
||||
|
||||
1. [x] **`users.direction` (migration `0016`), and why it is a column rather than a pair code.** `pair_lang` has always answered "which two languages" and every surface built on it quietly assumed the answer to a second question nobody asked: that **English is the language being learned**. That assumption is load-bearing in a dozen places — CJK is deliberately never tokenized, never spell-checked, never glossed; the prompts explain English in her language; the garden captures English words. All correct for a Mandarin native practising English, all backwards for an English native practising Mandarin. A second pair code (`zh-learner`) was cheaper and the wrong shape: it makes two directions of one pair look like two unrelated languages to every query, and it would have to be repeated for fr, es and pt-PT before any of them could turn around. The backfill is the DEFAULT itself, and it is right rather than merely convenient — all three accounts today really are Mandarin natives writing English.
|
||||
- **`PATCH /api/me` validates the two fields as one decision.** Both are optional and each defaults to what the account has, which is what makes the picker able to send one without knowing the other — and it is exactly that convenience the endpoint has to protect against: a client sending only `pair_lang: "fr"` while the account sits on `learning_pair` is asking for French-with-segmentation, a state neither field names on its own. **Refused, not silently downgraded**: a downgrade leaves the writer looking at an editor that behaves like the one she just tried to leave, with nothing to read as an explanation.
|
||||
- **`auth.learnerPairs` is a third list, and deliberately not either of the two that exist.** `internal/llm`'s languages name every pair the *prompts* can discuss; `shippedPairs` names every pair Petal can *render itself in* (needs a langpack); this one names every pair Petal can be *learned toward*, which needs a word list and a dictionary reading out of that language. zh has both; fr, es and pt-PT have neither, and their failure mode is worse than a missing pack — a missing pack shows unreadable copy, a missing word list shows an editor that silently does nothing when you hover.
|
||||
- An empty `PATCH` body used to be a 400 and is now a 200 that changes nothing. That is a real contract change and it is the price of optional fields; it has its own test saying so.
|
||||
2. [x] **Two assets, split so their coverage decisions come out opposite** (`scripts/build_cedict.py`, CC-CEDICT + jieba's `dict.txt`). Neither source has both halves: CC-CEDICT has headwords, pinyin and senses and *no frequencies*; jieba has 349k headwords with frequencies and *no definitions*. Segmentation needs the frequencies, because the algorithm is a shortest-path walk over log-probabilities and not longest-match.
|
||||
- **The browser gets the word list** (`words.txt.gz`, 188,522 words, **0.97 MB gzipped**) because segmentation runs on hover and a round-trip per hover is not a hover. **The server holds the whole dictionary** (`hanzi.json.gz`, 113,637 entries, **3.12 MB gzipped**, its own `sync.Once` so only a learner account pays for it).
|
||||
- **The client gate is a size decision and was measured as one.** Segmentation by the full 381,886-word union and by a frequency-gated list is **identical** on ordinary learner prose, including the textbook ambiguities (研究生命的起源, 乒乓球拍卖完了, 南京市长江大桥) — the long tail is rare proper nouns, and a rare word loses to two common ones every time. So the gate sits at freq ≥ 5, with **every CC-CEDICT headword unioned back in** so the segmenter can always see a word the server can explain.
|
||||
- **The dictionary gate is nothing at all, for the opposite reason.** The es phase settled that a *spelling* dictionary holds the union of every variety because its only power is to underline. This asset's only power is to **explain**, and the word a learner stops on is precisely the one they do not know — which is to say, the rare one. Trimming it by frequency would remove exactly the entries it exists for.
|
||||
- **Pinyin is tone-marked here, not at render time**, and `MAX_READINGS = 2` is not arbitrary: 得 is dé "to obtain" *and* de, the complement marker, and a learner who hovers 得 in 说得很好 and is told only "to obtain" has been actively misinformed about the sentence in front of them. The build script asserts all three of 的/地/得 carry their neutral-tone reading.
|
||||
- **Simplified only, said out loud.** Glossing traditional would be nearly free here and useless in the app: nothing would segment it, so nothing would ever ask.
|
||||
3. [x] **The segmenter** (`web/src/lib/segment.ts`) — shortest-path over log-probabilities, `MAX_WORD_LEN` 6, unknown single characters scored at half an occurrence (positive, so every position has *some* path; below the rarest real word, so it never wins). **369 ms/74 MB was fr's Hunspell cost; this is 232 ms and 14 MB** for a bigger language, because a flat word list needs no affix machinery. `hanziWordAt` (`hanziWord.ts`) resolves it to ProseMirror positions through **the same `mapOffset`** the suggestion, spell and search layers anchor with, plus its inverse.
|
||||
- **Writing the tests found the boundary bug.** A position names a *gap* and a word covers *characters*, so a hover on a boundary was resolving to the word that **ended** there rather than the one that starts — index 6 of 我今天去公园跑步了 is the 跑 under the mouse. The step-back to the left-hand character is kept for exactly one case: the caret at the end of the text, which is where it sits the instant an IME commits a word.
|
||||
- Tested twice over: hand-built dictionaries pin the *algorithm* (they would pass with any word list), and a block at the bottom pins the **shipped asset** on the sentences a rebuild would plausibly break — including the minimal pair 研究生宿舍 / 他们正在研究生物, which is what says the 研究/生命 result was a decision and not a bias against long words.
|
||||
4. [x] **Hover pinyin + English gloss, as an adapter rather than a second card.** `GET /api/hanzi/{word}` and one new prop each on `GlossTip` (a `lead` line above the meaning) and `WordCard` (`pinyin`, rendered **without** the slashes, because pinyin is not a phonetic transcription and the slashes would say something untrue in the one place a learner is looking for the truth about pronunciation). Everything else is reuse: same anchoring, same garden capture, same 🔊 — the zh pair already speaks Chinese, so reading 公园 aloud needed nothing.
|
||||
- **The character fallback.** The word list is a superset of the dictionary, so a hover really can land on a real word with no headword; Chinese compounds are usually transparent from their parts, which makes the per-character reading a real second answer. Returned in its own field so the surface can say which it is showing — and `hanziPinyin` stays empty in that case on purpose, since 不 is bù alone and bú before a fourth tone, and joining character readings would be inventing a pronunciation.
|
||||
5. [x] **错别字 — and the pack's most interesting property is what it refuses.** Chinese has no misspellings in the Hunspell sense: every character an IME offers is a real character, correctly formed. The error is a **substituted character inside a correct-looking word**, so this is a rule pack over confusable pairs, filed as the existing `mechanics` family (same rail, same cards, no new colour) and gated on the segmenter's presence — which *is* the direction gate, so a writer practising English can never be told her quoted Chinese is wrong.
|
||||
- **Gate one: the pair must be decidable by the dictionary** — `wrong` absent from the 188k list, `right` present, checked against the shipped asset in the suite rather than asserted in a comment. This is what keeps out errors everyone knows are errors: **自已 for 自己 is among the commonest slips in written Chinese and 自已 is itself a headword**, so the pack does not flag it — exactly as Phase 22's English pack left out `married with`. Same fate for 好象, 倒底, 帐号 and 部份. 24 pairs survived out of ~50 screened.
|
||||
- **Gate two: the characters must not already belong to two different words,** and without it every rule is dangerous. 自己经常 contains 己经. 睡觉的时候 contains 觉的. 不知到底 contains 知到. A substring match corrupts all three — silently, into text still made of real characters. The segmenter already knows the difference: if the two characters land in different tokens and either is a real multi-character word, that is a word boundary; two adjacent single-character tokens is what the walk produces when it has nothing better, which is what a mistyped compound looks like.
|
||||
- **Where the gate costs a real catch, it pays.** 我不知到他在哪里 really is 知到 for 知道 and is left alone, because 不知 is itself a word — while 我不知到底该怎么办 is the same three characters and is correct. The test is named for that trade rather than for the rule.
|
||||
- Server-side, `TestOfflineHanziFindingStaysMechanics` pins the one rule a layer above that would plausibly claim it: `isTranslation` re-labels an edit whose original reads as her language and whose replacement reads as English. 己经 → 已经 looks like the first half of that and nothing like the second, and must stay a tidy-up in her own sentence.
|
||||
6. [x] **The direction picker names each option in the language of the person who would choose it** — 英文 for the writer who is native in Chinese, "Chinese 中文" for the one who is native in English. The same self-naming principle the pair buttons follow, for the same reason: someone on the wrong side of this switch cannot read the side they are trying to reach. It renders only when the pack carries a `learner` block, which is the frontend's half of `auth.learnerPairs`.
|
||||
- **`@types/node` added as a devDependency**, which is a small thing with a real consequence: vitest can now read the *shipped* assets. Phases 21–25 all verified their dictionaries with throwaway scripts because the suite could not; `segment.test.ts` and `hanzi.test.ts` assert against the real files.
|
||||
- Verified: go build/vet, `go test ./...`, tsc, vite build, **vitest 284/284**; live smoke on a throwaway DB (:8071, LLM pointed at a dead port) — 公园 → gōngyuán, 得 → both readings, 猫书 → the character fallback, the word list served at 965,266 B, `PATCH {"direction":"learning_pair"}` accepted, `{"pair_lang":"fr"}` refused 400 while the account stayed put. The smoke also caught a cosmetic build bug: stripping CC-CEDICT's `CL:` field left "cat (" with an unbalanced paren, now fixed and the asset rebuilt.
|
||||
- ⚠️ **The IME guards were scoped into this phase and are NOT done.** No composition handling exists anywhere in the app — verified, not assumed. The risk is concrete and known: the decoration plugins (`SpellCheck`, `SuggestionHighlight`, `SearchHighlight`) recompute on every doc change, and a rebuild mid-composition is the classic bug that eats half-typed pinyin. This is the single most likely thing to be wrong the first time someone types Chinese into Petal with a real IME, and it is untouched rather than half-built.
|
||||
- ⚠️ **Not deployed** (this one carries a migration, so it is a deploy and not a rebuild), **not seen in a browser**, and **no account has ever been in the learner direction** — every claim above about how this feels to use is inference from unit tests. The 错别字 pack has not been read by a native speaker either; unlike the Latin packs it is 24 mechanically-screened pairs rather than prose, which lowers the stakes without removing them.
|
||||
|
||||
### Later / explicitly not now
|
||||
- Learner-facing Chinese writing (the zh pair's second direction) — own phase with its own spec (SUGGESTIONS §4); only after Phases 19–21 prove the pair model
|
||||
- ~~Spanish pair — gated on DreamDict growing an es dataset~~ **ungated 2026-07-26**, **shipped (code) 2026-07-28** — see Phase 25. What it still owes: a deploy, a native reader, and a writer who actually uses it.
|
||||
- ~~Voseo for the es pair~~ **resolved 2026-07-28 before shipping** — the fix was not to generate the paradigm but to stop using Debian's package, which is peninsular. RLA's generic build has it. See Phase 25 item 2.
|
||||
- **IME composition guards** — scoped into Phase 26 and not built; see that entry. The decoration plugins recompute on every doc change, and doing so mid-composition is what eats half-typed pinyin. First thing to do before anyone types Chinese into Petal in earnest.
|
||||
- **`restoring` is untranslated in the fr and pt-PT packs** — surfaced by the es review, fixed only in es. One line each, whenever those packs are next touched.
|
||||
- Reactive-animation puppy companion — wishlist, low priority; `companions.ts` roster + mood engine is the drop-in point
|
||||
- Copyleaks Tier-2 — revisit once Phase 15 provides a public webhook endpoint
|
||||
@@ -383,6 +413,7 @@ Scope agreed with the user 2026-07-28: **Latin American neutral, quorum review,
|
||||
- [x] **Phase 14 — companion warmth + bedtime nag + night mode**: more encouraging phrases, a gentle "go to bed" nudge after 11pm, and a calm dark theme + falling stars at night. ✅ (see Phase 14 above)
|
||||
|
||||
## Session log
|
||||
- 2026-07-28: **Phase 26 — the zh pair's other direction, and a rule pack whose best feature is what it refuses** (user asked to continue the build plan, then chose a new phase over deploying fr/es; scope chosen with the user: **direction column, segmentation + hover pinyin/gloss, 错别字, IME guards**, code only). SUGGESTIONS §4 had called this its own epic, and the reason turned out to be one sentence: **`pair_lang` had always been answering a second question nobody asked.** It says which two languages; every surface built on it assumed English was the one being *learned*, which is why CJK is deliberately never tokenized, never spell-checked and never glossed. All correct for the writer this app was built for, all backwards for the other one. A `direction` column rather than a `zh-learner` pair code, because the two are genuinely separate questions and the column is what lets fr/es/pt inherit the capacity later. **The phase has three decisions in it and they are all about coverage.** The browser gets a word list and the server keeps the dictionary, and their gates come out *opposite*: the client list is frequency-gated at 5 because segmentation by the full union and by the gated list is **identical** on ordinary prose (measured, including 研究生命的起源 and 乒乓球拍卖完了 — the long tail is rare proper nouns and the max-probability walk never picks one), while the dictionary is gated by **nothing**, because its only power is to *explain* and the word a learner stops on is precisely the rare one. That is the es dictionary decision arrived at from both sides in one phase. **Writing the segmenter tests found the boundary bug**: a position names a gap and a word covers characters, so a hover on a boundary was resolving to the word that ended there rather than the one that starts. **The 错别字 pack is the part worth reading.** Chinese has no misspellings — every character an IME offers is real — so the unit of error is a substituted character inside a correct-looking word, and the pack is 24 confusable pairs held by two mechanical gates. Gate one admits a pair only if the wrong form is *not* a dictionary word and the right form is, which is what makes it refuse **自已 for 自己** — one of the commonest slips in written Chinese, whose wrong form is itself a headword — exactly as Phase 22 refused `married with`. Gate two is the one that matters: **自己经常 contains 己经, 睡觉的时候 contains 觉的, 不知到底 contains 知到**, so a substring match would corrupt correct sentences silently, into text still made of real characters. The segmenter settles it — two adjacent single-character tokens is what the walk produces when it has nothing better, which is what a mistyped compound looks like — and where the gate costs a real catch (我不知到他在哪里 *is* 知到 for 知道, but 不知 is a word) it declines rather than risk the identical-looking correct sentence beside it. **`@types/node` went in as a devDependency and quietly fixes something older**: phases 21–25 each verified their shipped dictionary with a throwaway script because vitest could not read files; the suite now asserts against the real assets. go build/vet/test, tsc, vite, **vitest 284/284**, live smoke on a throwaway DB which itself caught a cosmetic build bug ("cat (" left by stripping CC-CEDICT's CL: field). ⚠️ **The IME guards were in scope and are not done** — no composition handling exists anywhere in the app, and a decoration rebuild mid-composition eating half-typed pinyin is the likeliest thing to be wrong the first time anyone types Chinese into Petal for real. Left untouched rather than half-built, and named here rather than buried. ⚠️ **Not deployed** (it carries a migration), **not seen in a browser**, and **no account has ever been in the learner direction**, so everything above about how it feels to use is inference from tests.
|
||||
- 2026-07-28: **Phase 25 — the es pair, and a plan that had quietly chosen the wrong Spanish** (user asked where Spanish support had gone, then "yes" to starting the phase; scope chosen with the user: **Latin American neutral**, quorum review, code only). The starting point was a misreading worth recording: the plan *reads* as though Spanish shipped, because the DreamDict rebuild, the LLM language entry, the L1 rule gating and the TTS env-discovery are all `[x]` — every piece of groundwork was done and the pair itself had never been built. `shippedPairs` was the honest answer all along: the server had been refusing `es` on purpose. **The regional question was the phase.** pt-PT's was forced by packaging and fr's turned out not to exist; es had a real choice with no default, and once the user chose Latin American, the plan's own two concrete decisions were both wrong. It warned that `hunspell-es` is "packaged per country — check what `es_ES` actually is": it ships twenty country codes and **every one is a symlink to one pan-Hispanic file**, so the trap was not there. And it named **`es_ES-davefx-medium`** for the voice, which *is* the trap — six of Piper's nine Spanish voices are peninsular, so the obvious pick would have read Latin American copy in a Castilian accent, the pt-PT mistake arriving through a different door. `es_MX-ald-medium` instead. **Then the user asked "should we pick a different Spanish dictionary?" and the answer was yes** — the phase had shipped the wrong one and written a confident justification for it. Debian's `hunspell-es` symlinks twenty country codes to one file, which reads as pan-Hispanic; RLA actually publishes twenty-four builds per release, one per country **plus a generic `es` that is the union**, and Debian ships **peninsular `es_ES`**. The 58,622-form difference is essentially **voseo**: under the first build, *vení* and *tenés* — the ordinary present tense of Argentina, Uruguay, Paraguay and much of Central America — were underlined as misspellings, and this document called that a known gap handled on principle. **What makes it worth writing down is that the MUST_ACCEPT list was designed to catch exactly this and could not**: it asserted the pan-Hispanic *vocabulary*, and every RLA variant carries the full pan-Hispanic vocabulary — only the paradigms are localised — so it was satisfiable by all twenty-four. The `REP` table cited as the corroborating witness (yeísmo, seseo) is likewise shared by every build. Two independent-looking proofs, neither of which could distinguish anything, agreeing with each other. The profile now demands **voseo** (rejects es_ES and Debian), **vosotros** (rejects es_MX) and **another region's everyday words** — *arepa*, *chévere*, *bacán* (rejects es_AR, which has both paradigms and would otherwise pass); all four neighbours were run through it and confirmed refused. Shipping the union is the same call fr made between *coût* and *cout*: the dictionary's only power is to underline, so it holds every variety, while the *copy* picks a register because speaking requires one. 717,640 forms, 1.74 MB gzipped, **762 ms / 97 MB** in a real nspell, and **fr and pt-PT rebuild byte-identical** from their own upstream debs. **The quorum review earned its place twice**: four models, ≥2-of-4, 5 of 27 findings applied — one of which caught the pack's bedtime proverb being *Qui dort dîne* calqued into Spanish, English gloss and all, which is exactly the "a pack is not a translation of another pack" rule the fr header states and I had broken while writing it. And one below-threshold finding (a missing `¡` on an exclamative, seen by 1 of 4 because an absent *opening* mark has no closing `!` to look wrong against) was applied anyway and **turned into an assertion**: the suite now rejects any native line that closes `?`/`!` without opening one. That is Phase 24's lesson one level up — what a review finds once, a test should find every time. go build/vet/test, tsc, vite, **vitest 251/251**. ⚠️ **Not deployed, not seen in a browser, not read by a native speaker, and no es account exists** — all four accounts' worth of Spanish experience is still hypothetical, and the pack says so in its own header.
|
||||
- 2026-07-27: **Phase 24 — the fr pair, and a "generalizes" that did not** (user: "resume the build plan"; scope chosen with the user: French end to end, code only, deploy its own step). The plan's five items were meant to be mechanical, and four of them were — the Piper voice is a compose service and two env lines because Phase 21 made a language configuration; the lexicon needed nothing at all, fr having been measured at 63.1% during Phase 20's rebuild, better than the pair that already shipped; the sidebar picker grew a third entry without a line of UI because it derives itself from the shipped packs. **Item 3 was the one that had been recorded as done and wasn't.** `build_ptpt_dictionary.py` was said to generalize; it handled single-character flags and plain PFX/SFX and stopped on everything else, and `fr.aff` uses four of the things it stopped on. `FLAG long` is the dangerous one: French flags are two characters, so the pt-PT reader's `set(flagstr)` yields a bag of unrelated letters and expands every entry through the wrong paradigm without erroring. Plus continuation flags (French really does affix an affixed form), NEEDAFFIX on 68,075 of 84,140 stems, and FULLSTRIP. The rewritten `build_hunspell_dictionary.py` carries a per-language profile and asserts that CIRCUMFIX and FORBIDDENWORD are still unused — and **rebuilds pt-PT byte-identical to the shipped asset**, which is the only thing that makes "generalized" a claim rather than a hope. **The second decision was elision, and it was made by measuring both halves**: keeping `l'arbre` and its thirty-three siblings costs 3,159,832 forms and 8.25 MB gzipped; dropping them costs 473,326 and 1.19 MB. They are not new words, but the tokenizer keeps internal apostrophes, so they really would have been underlined — so they moved out of the dictionary and into `withElision`, which splits at a known clitic and still requires the remainder to be a word (`l'zzzz` stays flagged). Real nspell: 369 ms and 74 MB for the larger language, against pt-PT's 842 ms and 139 MB. **Where the regional trap lives is the mirror image of Portuguese's**: every `fr_*` Piper voice is fr_FR and every Debian fr dictionary is one shared word list, so nothing can be quietly wrong about the country — the whole decision is in the copy, which is why the pack is greped for *courriel* and *magasiner* the way pt-PT is greped for *arquivo*. What French does have instead is the 1990 reform, packaged three ways; Petal ships comprehensive, because Petal never corrects her French and *coût* and *cout* are both correct. go build/vet/test, tsc, vite, vitest 190/190. **Two things owed and both said plainly**: no native speaker has read the pack (SUGGESTIONS §3's bar, unmet for pt-PT too), and nothing here has been seen in a browser. **Then, same session, an interim answer to the first of those** (user: "perhaps for now, we could leverage multiple LLMs to act as reviewers?"): four models reviewed each Latin pack independently, and only findings ≥2 of them reached on their own were applied — five per pack. It earned its keep on the pack that was *already shipped*: pt-PT had **pre-Acordo spellings in a file whose own header commits to post-Acordo**, because the Phase 21 greps checked for Brazilian vocabulary and never checked the pack against its own spelling policy. That grep now exists and was confirmed to fail on the old text. Where reviewers agreed a line was wrong but split on the fix, the wording is mine and the reasoning is in the phase entry rather than averaged away. Still not a native speaker, and both packs now say so precisely.
|
||||
- 2026-07-27: **Phase 22 finished — the build plan's last four items, and the LLM stops holding anything hostage** (user: "let's finish the last phase of the build plan"; code only, no VPS work). The four remaining items shared one theme, and it only became visible while building them: **§6's left-hand column is now complete.** Spell, define, gloss, pronounce, catch the common mistakes, review vocabulary, prove authorship — every daily-writing need works with the tunnel down. **The plan asked for "grammar lite as a fourth suggestion family", and the fourth family already existed**: Phase 8's deterministic `mechanics` pass was the plumbing, so this was the rule pack it had been waiting for rather than new machinery — preposition pairs, doubled comparatives, `people is`, plus per-pair L1 interference. **Q6 answered by hand-curating rather than mining LanguageTool**: that corpus is broad because it aims at recall, and this pack aims at the exact opposite, so every entry is a pairing wrong in essentially *all* contexts and the ones only *usually* wrong were left out on purpose — `married with` is a mistake until "married with children", `arrive to` wants at or in depending on the noun, `different than` is ordinary American English. Each rule is pinned in both directions, the guard case being the correct English next to the mistake. **The L1 rules are gated by pair, and the gating is what earns them their confidence** — *ter 30 anos* → "I am 30 years old" is a near-certainty for a Portuguese writer and only a guess for anyone else. The two zh rules the plan itself named are the ones this pack **refuses** to implement: dropped articles and he/she slips are not detectable from text alone ("She said he was late" is perfect whichever pronoun was meant), and flagging them would mean correcting correct writing. **The miscollocation list forced the session's one real design change.** It had to file as `collocation` rather than as its own family — same rail, same phrasing, and an accepted chunk plants in the garden exactly as the coach's would — but `type` had been quietly doubling as the answer to *which engine found this*, and that breaks the instant an offline rule proposes a collocation. Migration `0013_suggestion_source` splits the two apart: each pass now scopes its DELETE by engine, and the span tiebreak moved with it (an exact offline card beats an overlapping LLM one by source, not by type — an offline miscollocation is as exact as an offline comma). Without it the coach silently wiped every offline chunk on the page and the offline pass left the coach's rows to pile up; both directions are now tested, and a pre-0013 collocation row correctly backfills to the coach, since the offline list did not exist yet. **The daily invitation's whole substance is one stored date** — no count, no run of days, nothing that gets worse for being away, so a month away reads exactly like a day away; it lives in its own file because that is the property this feature would lose silently, and the test is named for it rather than for the query. Both answers spend the day's invitation, because being asked again after "not today" would make no a negotiation. **False friends are the one thing here that never becomes a card**: ~19 curated en↔pt entries, shown as a lavender block above the WordCard's definition and as at most one companion note per pass, with no `fix` anywhere — *actually* may well be the word she meant, and this is the mistake that makes a learner feel foolish rather than merely corrected. zh has none, which is the honest answer and not an unwritten one: the trap needs a shared script. Copy for the invitation and the false friends is greped by tests the same way the journal's is (*streak / in a row / 连续 / todos os dias*; *wrong / mistake / errado*) — the framing is the feature, and it is the part a future edit would undo while meaning well. Verified: go build/vet, `go test ./internal/...` clean, tsc, vite build, vitest 172/172 (30 new rule cases, 7 invitation, plus false-friend shape/tone guards), and a live throwaway DB on :8099 with **no LLM configured at all** — offline `did a mistake` → card → accept → garden card *made a mistake*, example bounded to its own corrected sentence, journal `kept:1`. ⚠️ **Not deployed and not seen in a browser**, and this one carries a migration, so it is a deploy rather than a rebuild. The pt-PT copy added here joins the pack a native speaker still has not reviewed.
|
||||
|
||||
@@ -207,6 +207,9 @@ func main() {
|
||||
lex := lexicon.NewHandler(database.DB, lexSet)
|
||||
pr.Mount("/word", lex.Routes())
|
||||
pr.Mount("/gloss", lex.GlossRoutes())
|
||||
// The same lookup pointing the other way: a Chinese word to its pinyin
|
||||
// and English senses, for an account whose direction is learning_pair.
|
||||
pr.Mount("/hanzi", lex.HanziRoutes())
|
||||
|
||||
// Vocabulary garden: words the writer looks up are captured here and
|
||||
// surfaced for gentle spaced-repetition review.
|
||||
|
||||
@@ -24,7 +24,7 @@ func patchMe(t *testing.T, users *UserStore, id, body string) *httptest.Response
|
||||
func TestSetPairLang(t *testing.T) {
|
||||
_, users, _ := newStores(t)
|
||||
|
||||
if err := users.SetPairLang("bob", "pt-PT"); err != nil {
|
||||
if err := users.SetPair("bob", "pt-PT", DirectionLearningEn); err != nil {
|
||||
t.Fatalf("set pt-PT: %v", err)
|
||||
}
|
||||
if u, _ := users.Get("bob"); u.PairLang != "pt-PT" {
|
||||
@@ -34,14 +34,14 @@ func TestSetPairLang(t *testing.T) {
|
||||
// Every pair with a langpack, not just the first one: this list and the
|
||||
// frontend's PACKS are two copies of the same fact, and the day they
|
||||
// disagree is the day she can pick a pair the app cannot render.
|
||||
if err := users.SetPairLang("bob", "fr"); err != nil {
|
||||
if err := users.SetPair("bob", "fr", DirectionLearningEn); err != nil {
|
||||
t.Fatalf("set fr: %v", err)
|
||||
}
|
||||
if u, _ := users.Get("bob"); u.PairLang != "fr" {
|
||||
t.Fatalf("pair_lang = %q, want fr", u.PairLang)
|
||||
}
|
||||
|
||||
if err := users.SetPairLang("bob", "es"); err != nil {
|
||||
if err := users.SetPair("bob", "es", DirectionLearningEn); err != nil {
|
||||
t.Fatalf("set es: %v", err)
|
||||
}
|
||||
if u, _ := users.Get("bob"); u.PairLang != "es" {
|
||||
@@ -50,7 +50,7 @@ func TestSetPairLang(t *testing.T) {
|
||||
|
||||
// And back — a writer who tries a pair and doesn't like it must be able to
|
||||
// return, which is the whole reason the picker exists.
|
||||
if err := users.SetPairLang("bob", "zh"); err != nil {
|
||||
if err := users.SetPair("bob", "zh", DirectionLearningEn); err != nil {
|
||||
t.Fatalf("set zh: %v", err)
|
||||
}
|
||||
if u, _ := users.Get("bob"); u.PairLang != "zh" {
|
||||
@@ -70,7 +70,7 @@ func TestSetPairLangRejectsUnshippedPairs(t *testing.T) {
|
||||
// regional code Petal has not decided about is refused rather than rounded
|
||||
// to the nearest pack it happens to have.
|
||||
for _, lang := range []string{"es-ES", "pt-BR", "fr-CA", "de", "klingon", "", " "} {
|
||||
if err := users.SetPairLang("bob", lang); err == nil {
|
||||
if err := users.SetPair("bob", lang, DirectionLearningEn); err == nil {
|
||||
t.Fatalf("stored unshipped pair %q", lang)
|
||||
}
|
||||
}
|
||||
@@ -81,7 +81,7 @@ func TestSetPairLangRejectsUnshippedPairs(t *testing.T) {
|
||||
|
||||
func TestSetPairLangUnknownUser(t *testing.T) {
|
||||
_, users, _ := newStores(t)
|
||||
if err := users.SetPairLang("nobody", "pt-PT"); err == nil {
|
||||
if err := users.SetPair("nobody", "pt-PT", DirectionLearningEn); err == nil {
|
||||
t.Fatal("set a pair language on an account that does not exist")
|
||||
}
|
||||
}
|
||||
@@ -109,7 +109,7 @@ func TestUpdateMeHandlerRejects(t *testing.T) {
|
||||
|
||||
for name, body := range map[string]string{
|
||||
"unshipped pair": `{"pair_lang":"es-ES"}`,
|
||||
"missing field": `{}`,
|
||||
"unknown direction": `{"direction":"learning_klingon"}`,
|
||||
"not json": `pt-PT`,
|
||||
} {
|
||||
if w := patchMe(t, users, "bob", body); w.Code != http.StatusBadRequest {
|
||||
@@ -126,3 +126,116 @@ func TestUpdateMeHandlerRejects(t *testing.T) {
|
||||
t.Fatalf("unknown user: status = %d, want 401", w.Code)
|
||||
}
|
||||
}
|
||||
|
||||
// An empty body used to be a 400, back when pair_lang was the only field and a
|
||||
// request that named none of it could only be a client bug. With two optional
|
||||
// fields it is an ordinary PATCH that changes nothing, and it has to be: the
|
||||
// picker sends one field without knowing the other, and "omitted" has to mean
|
||||
// "leave it alone" for that to be safe.
|
||||
func TestUpdateMeHandlerEmptyBodyChangesNothing(t *testing.T) {
|
||||
_, users, _ := newStores(t)
|
||||
|
||||
if err := users.SetPair("bob", "zh", DirectionLearningPair); err != nil {
|
||||
t.Fatalf("set up: %v", err)
|
||||
}
|
||||
w := patchMe(t, users, "bob", `{}`)
|
||||
if w.Code != http.StatusOK {
|
||||
t.Fatalf("status = %d, want 200 (%s)", w.Code, w.Body.String())
|
||||
}
|
||||
u, _ := users.Get("bob")
|
||||
if u.PairLang != "zh" || u.Direction != DirectionLearningPair {
|
||||
t.Fatalf("empty PATCH moved the account to %q/%q", u.PairLang, u.Direction)
|
||||
}
|
||||
}
|
||||
|
||||
// The direction axis: an account can be turned around and turned back, and the
|
||||
// default every existing row already carries is the one it had before the column
|
||||
// existed.
|
||||
func TestDirectionRoundTrip(t *testing.T) {
|
||||
_, users, _ := newStores(t)
|
||||
|
||||
if u, _ := users.Get("bob"); u.Direction != DirectionLearningEn {
|
||||
t.Fatalf("a fresh account starts at %q, want %q", u.Direction, DirectionLearningEn)
|
||||
}
|
||||
|
||||
w := patchMe(t, users, "bob", `{"direction":"learning_pair"}`)
|
||||
if w.Code != http.StatusOK {
|
||||
t.Fatalf("turn around: status = %d (%s)", w.Code, w.Body.String())
|
||||
}
|
||||
var got db.User
|
||||
if err := json.Unmarshal(w.Body.Bytes(), &got); err != nil {
|
||||
t.Fatalf("decode: %v", err)
|
||||
}
|
||||
// The response carries the direction, not just the pair — the client reads
|
||||
// its whole state back from here rather than assuming the write took.
|
||||
if got.Direction != DirectionLearningPair || got.PairLang != "zh" {
|
||||
t.Fatalf("response = %+v, want bob learning zh", got)
|
||||
}
|
||||
|
||||
if w := patchMe(t, users, "bob", `{"direction":"learning_en"}`); w.Code != http.StatusOK {
|
||||
t.Fatalf("turn back: status = %d (%s)", w.Code, w.Body.String())
|
||||
}
|
||||
if u, _ := users.Get("bob"); u.Direction != DirectionLearningEn {
|
||||
t.Fatalf("direction = %q after turning back", u.Direction)
|
||||
}
|
||||
}
|
||||
|
||||
// The refusal this axis exists to make: a pair with no word list cannot be
|
||||
// learned toward, however good its langpack is. fr, es and pt-PT all have copy,
|
||||
// voices and spelling dictionaries — and nothing that could segment a sentence
|
||||
// or read from that language into English, which is what a learner needs.
|
||||
func TestLearnerDirectionRefusedForPairsWithoutData(t *testing.T) {
|
||||
_, users, _ := newStores(t)
|
||||
|
||||
for _, lang := range []string{"pt-PT", "fr", "es"} {
|
||||
if err := users.SetPair("bob", lang, DirectionLearningEn); err != nil {
|
||||
t.Fatalf("set %s: %v", lang, err)
|
||||
}
|
||||
w := patchMe(t, users, "bob", `{"direction":"learning_pair"}`)
|
||||
if w.Code != http.StatusBadRequest {
|
||||
t.Fatalf("%s: status = %d, want 400", lang, w.Code)
|
||||
}
|
||||
if u, _ := users.Get("bob"); u.Direction != DirectionLearningEn {
|
||||
t.Fatalf("%s: a refused write still moved direction to %q", lang, u.Direction)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// The two-field combination the handler validates as one decision. An account
|
||||
// already learning Chinese that asks only to change pair is asking for a state
|
||||
// neither field names on its own — French with segmentation — and it must not
|
||||
// arrive by leaving one field out.
|
||||
func TestPairChangeCannotStrandTheLearnerDirection(t *testing.T) {
|
||||
_, users, _ := newStores(t)
|
||||
|
||||
if err := users.SetPair("bob", "zh", DirectionLearningPair); err != nil {
|
||||
t.Fatalf("set up: %v", err)
|
||||
}
|
||||
if w := patchMe(t, users, "bob", `{"pair_lang":"fr"}`); w.Code != http.StatusBadRequest {
|
||||
t.Fatalf("status = %d, want 400", w.Code)
|
||||
}
|
||||
u, _ := users.Get("bob")
|
||||
if u.PairLang != "zh" || u.Direction != DirectionLearningPair {
|
||||
t.Fatalf("refused write left the account at %q/%q", u.PairLang, u.Direction)
|
||||
}
|
||||
|
||||
// Naming both at once is how that move is actually made, and it works.
|
||||
if w := patchMe(t, users, "bob", `{"pair_lang":"fr","direction":"learning_en"}`); w.Code != http.StatusOK {
|
||||
t.Fatalf("both fields: status = %d (%s)", w.Code, w.Body.String())
|
||||
}
|
||||
if u, _ := users.Get("bob"); u.PairLang != "fr" || u.Direction != DirectionLearningEn {
|
||||
t.Fatalf("account = %q/%q, want fr/learning_en", u.PairLang, u.Direction)
|
||||
}
|
||||
}
|
||||
|
||||
// The CHECK constraint is the last line, below the handler and below SetPair:
|
||||
// a direction that reaches the column by any other route is still refused.
|
||||
func TestDirectionCheckConstraint(t *testing.T) {
|
||||
_, users, database := newStores(t)
|
||||
if _, err := database.Exec(`UPDATE users SET direction = 'sideways' WHERE id = 'bob'`); err == nil {
|
||||
t.Fatal("the users.direction CHECK accepted 'sideways'")
|
||||
}
|
||||
if u, _ := users.Get("bob"); u.Direction != DirectionLearningEn {
|
||||
t.Fatalf("direction = %q after a refused UPDATE", u.Direction)
|
||||
}
|
||||
}
|
||||
|
||||
+97
-11
@@ -49,9 +49,9 @@ func (u *UserStore) Upsert(sub, email, displayName string) error {
|
||||
func (u *UserStore) Get(id string) (db.User, error) {
|
||||
var user db.User
|
||||
err := u.db.QueryRow(
|
||||
`SELECT id, email, COALESCE(display_name, ''), created_at, pair_lang
|
||||
`SELECT id, email, COALESCE(display_name, ''), created_at, pair_lang, direction
|
||||
FROM users WHERE id = ?`, id,
|
||||
).Scan(&user.ID, &user.Email, &user.DisplayName, &user.CreatedAt, &user.PairLang)
|
||||
).Scan(&user.ID, &user.Email, &user.DisplayName, &user.CreatedAt, &user.PairLang, &user.Direction)
|
||||
return user, err
|
||||
}
|
||||
|
||||
@@ -93,12 +93,63 @@ func pairIsShipped(lang string) bool {
|
||||
return false
|
||||
}
|
||||
|
||||
// SetPairLang moves an account to another (English + X) pair.
|
||||
func (u *UserStore) SetPairLang(id, lang string) error {
|
||||
// The two directions a pair can be travelled in. `DirectionLearningEn` is the
|
||||
// original assumption made explicit: the writer is native in X and practising
|
||||
// English. `DirectionLearningPair` is the other way round.
|
||||
const (
|
||||
DirectionLearningEn = "learning_en"
|
||||
DirectionLearningPair = "learning_pair"
|
||||
)
|
||||
|
||||
// The pairs whose *learner* direction Petal can actually serve, which is a
|
||||
// narrower thing than a shipped pair and narrower again than a langpack.
|
||||
//
|
||||
// Turning a pair around needs data no langpack carries: a word list to segment
|
||||
// with, and a dictionary that reads from the pair language into English. Chinese
|
||||
// has both as of Phase 26 (CC-CEDICT + jieba); French, Spanish and Portuguese
|
||||
// have neither yet, and — unlike a missing pack, which leaves a writer looking
|
||||
// at copy she cannot read — a missing word list would leave her looking at an
|
||||
// editor that silently does nothing when she hovers. Both are bad; only one is
|
||||
// legible as a bug. So the server refuses, for the same reason and by the same
|
||||
// mechanism as `shippedPairs`.
|
||||
//
|
||||
// This list is expected to grow one pair at a time and never to be inferred:
|
||||
// segmentation is a property of a writing system, and there is no rule that
|
||||
// derives "has a word list" from a language code.
|
||||
var learnerPairs = []string{"zh"}
|
||||
|
||||
// SupportsLearnerDirection reports whether a pair can be turned around.
|
||||
func SupportsLearnerDirection(lang string) bool {
|
||||
for _, p := range learnerPairs {
|
||||
if p == lang {
|
||||
return true
|
||||
}
|
||||
}
|
||||
return false
|
||||
}
|
||||
|
||||
func directionIsKnown(d string) bool {
|
||||
return d == DirectionLearningEn || d == DirectionLearningPair
|
||||
}
|
||||
|
||||
// SetPair moves an account to another (English + X) pair, in a given direction.
|
||||
//
|
||||
// The two are written together because they constrain each other: a direction is
|
||||
// only meaningful for a pair that can be travelled in it, and validating them a
|
||||
// field at a time would let a two-step change pass through a state that neither
|
||||
// step is allowed to leave behind.
|
||||
func (u *UserStore) SetPair(id, lang, direction string) error {
|
||||
if !pairIsShipped(lang) {
|
||||
return errors.New("auth: unshipped pair language " + lang)
|
||||
}
|
||||
res, err := u.db.Exec(`UPDATE users SET pair_lang = ? WHERE id = ?`, lang, id)
|
||||
if !directionIsKnown(direction) {
|
||||
return errors.New("auth: unknown direction " + direction)
|
||||
}
|
||||
if direction == DirectionLearningPair && !SupportsLearnerDirection(lang) {
|
||||
return errors.New("auth: no learner direction for " + lang)
|
||||
}
|
||||
res, err := u.db.Exec(
|
||||
`UPDATE users SET pair_lang = ?, direction = ? WHERE id = ?`, lang, direction, id)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
@@ -108,8 +159,8 @@ func (u *UserStore) SetPairLang(id, lang string) error {
|
||||
return nil
|
||||
}
|
||||
|
||||
// UpdateMeHandler changes the caller's own settings — today, the one setting
|
||||
// there is: which language Petal speaks alongside her English.
|
||||
// UpdateMeHandler changes the caller's own settings: which language Petal
|
||||
// speaks alongside her English, and which of the two she is learning.
|
||||
//
|
||||
// It answers with the whole updated user rather than an empty 204 so the client
|
||||
// has one shape to trust: /api/me and this return the same thing, and the app
|
||||
@@ -119,24 +170,59 @@ func (u *UserStore) SetPairLang(id, lang string) error {
|
||||
// dictionary, her read-aloud voice, which word-lookup provider answers, and the
|
||||
// language the prompts ask the model to explain in. All of those read
|
||||
// `users.pair_lang` at use time, so all of them follow from this one write.
|
||||
//
|
||||
// Both fields are optional and each defaults to what the account already has, so
|
||||
// the picker can send one without knowing the other. That matters for the
|
||||
// combination this endpoint exists to prevent: a client that sent only
|
||||
// `pair_lang: "fr"` while the account sat on `learning_pair` would otherwise ask
|
||||
// for French-with-segmentation, which does not exist. Here it is one decision
|
||||
// with one validation, and the answer carries whatever actually landed.
|
||||
func (u *UserStore) UpdateMeHandler() http.HandlerFunc {
|
||||
return func(w http.ResponseWriter, r *http.Request) {
|
||||
var body struct {
|
||||
PairLang string `json:"pair_lang"`
|
||||
PairLang *string `json:"pair_lang"`
|
||||
Direction *string `json:"direction"`
|
||||
}
|
||||
if err := json.NewDecoder(r.Body).Decode(&body); err != nil {
|
||||
httputil.BadRequest(w, "invalid request body")
|
||||
return
|
||||
}
|
||||
lang := strings.TrimSpace(body.PairLang)
|
||||
id := UserID(r.Context())
|
||||
current, err := u.Get(id)
|
||||
if err != nil {
|
||||
httputil.ErrorJSON(w, http.StatusUnauthorized, "not signed in")
|
||||
return
|
||||
}
|
||||
|
||||
lang, direction := current.PairLang, current.Direction
|
||||
if body.PairLang != nil {
|
||||
lang = strings.TrimSpace(*body.PairLang)
|
||||
}
|
||||
if body.Direction != nil {
|
||||
direction = strings.TrimSpace(*body.Direction)
|
||||
}
|
||||
|
||||
if !pairIsShipped(lang) {
|
||||
// Name the ones that work. A writer who lands here has picked from a
|
||||
// stale client, and "not a language" tells her nothing.
|
||||
httputil.BadRequest(w, "unsupported language pair — Petal speaks "+strings.Join(shippedPairs, ", "))
|
||||
return
|
||||
}
|
||||
id := UserID(r.Context())
|
||||
if err := u.SetPairLang(id, lang); err != nil {
|
||||
if !directionIsKnown(direction) {
|
||||
httputil.BadRequest(w, "unknown direction — expected "+DirectionLearningEn+" or "+DirectionLearningPair)
|
||||
return
|
||||
}
|
||||
if direction == DirectionLearningPair && !SupportsLearnerDirection(lang) {
|
||||
// Refused rather than quietly downgraded to learning_en. A silent
|
||||
// downgrade would leave the writer looking at an editor that behaves
|
||||
// like the one she just tried to leave, with nothing to read as an
|
||||
// explanation — and the caller cannot tell the two outcomes apart
|
||||
// without diffing the response it was given.
|
||||
httputil.BadRequest(w, "Petal can only be learned toward "+strings.Join(learnerPairs, ", ")+" so far")
|
||||
return
|
||||
}
|
||||
|
||||
if err := u.SetPair(id, lang, direction); err != nil {
|
||||
if errors.Is(err, sql.ErrNoRows) {
|
||||
httputil.ErrorJSON(w, http.StatusUnauthorized, "not signed in")
|
||||
return
|
||||
|
||||
@@ -561,6 +561,34 @@ DROP TABLE suggestions;
|
||||
ALTER TABLE suggestions_new RENAME TO suggestions;
|
||||
CREATE INDEX idx_suggestions_doc_id ON suggestions(doc_id);
|
||||
CREATE INDEX idx_suggestions_resolved ON suggestions(status, resolved_at);
|
||||
`,
|
||||
},
|
||||
{
|
||||
// Which half of the pair is being learned.
|
||||
//
|
||||
// `pair_lang` (0010) has always answered "which two languages", and every
|
||||
// surface built on it assumed the answer to a second question nobody had
|
||||
// asked: that English is the language being *learned*. That assumption is
|
||||
// load-bearing in a dozen places — CJK is deliberately never tokenized,
|
||||
// never spell-checked, never glossed; the prompts explain English in her
|
||||
// language; the vocabulary garden captures English words. All correct for
|
||||
// a Mandarin native practising English, and all backwards for an English
|
||||
// native practising Mandarin.
|
||||
//
|
||||
// A second pair code ('zh-learner') was the cheaper option and is the
|
||||
// wrong shape: it would make the two directions of one pair look like two
|
||||
// unrelated languages to every query, and it would have to be repeated for
|
||||
// fr, es and pt-PT before any of them could turn around. A column keeps
|
||||
// the two questions separate, which is what they are.
|
||||
//
|
||||
// 'learning_en' is the default and is what every existing row means — the
|
||||
// backfill is the DEFAULT itself, and it is right rather than merely
|
||||
// convenient: all three accounts today are Mandarin natives writing
|
||||
// English.
|
||||
name: "0016_user_direction",
|
||||
stmt: `
|
||||
ALTER TABLE users ADD COLUMN direction TEXT NOT NULL DEFAULT 'learning_en'
|
||||
CHECK(direction IN ('learning_en','learning_pair'));
|
||||
`,
|
||||
},
|
||||
}
|
||||
|
||||
@@ -15,6 +15,19 @@ type User struct {
|
||||
// today, "pt-PT"/"fr"/"es" once the langpacks land. It selects the UI copy
|
||||
// and dictionary set, not the language they may type in.
|
||||
PairLang string `json:"pair_lang"`
|
||||
|
||||
// Direction says which half of the pair is being *learned*. Every pair until
|
||||
// now assumed one answer: the writer is native in X and practising English,
|
||||
// so hanzi is never tokenized and English is what gets underlined. Turn it
|
||||
// around — a native English speaker learning Chinese — and the same pair
|
||||
// wants the opposite of nearly every default.
|
||||
//
|
||||
// It is a separate column from PairLang rather than a second pair code
|
||||
// ("zh-learner") because it is a genuinely separate question: the pair says
|
||||
// *which two languages*, this says *which way round*. Keeping them apart is
|
||||
// what lets fr, es and pt-PT inherit the learner direction later without a
|
||||
// second langpack each.
|
||||
Direction string `json:"direction"`
|
||||
}
|
||||
|
||||
// Document is a single piece of writing. `Content` is the Tiptap JSON document
|
||||
|
||||
@@ -36,3 +36,13 @@ var glossGz []byte
|
||||
//
|
||||
//go:embed data/phonetic.json.gz
|
||||
var phoneticGz []byte
|
||||
|
||||
// hanziGz is the gzipped Chinese→English map: simplified headword → [[pinyin,
|
||||
// senses], …]. Built from CC-CEDICT (scripts/build_cedict.py), unfiltered — the
|
||||
// word a learner stops on is the one they do not know, so this is the one
|
||||
// dataset here with no frequency gate. Loaded on its own sync.Once (see
|
||||
// hanzi.go), not with the four above, because only a learner-direction account
|
||||
// ever asks for it.
|
||||
//
|
||||
//go:embed data/hanzi.json.gz
|
||||
var hanziGz []byte
|
||||
|
||||
Binary file not shown.
@@ -42,6 +42,36 @@ func (h *Handler) GlossRoutes() chi.Router {
|
||||
return r
|
||||
}
|
||||
|
||||
// HanziRoutes returns the router mounted at /api/hanzi — a Chinese word to its
|
||||
// pinyin and English senses, for a writer going the other way through the zh
|
||||
// pair (`users.direction = 'learning_pair'`).
|
||||
//
|
||||
// It does not go through [Handler.providerFor], and that is not an oversight.
|
||||
// providerFor picks a dictionary by the writer's *pair*, to answer "what does
|
||||
// this English word mean in her language" — a question whose answer differs per
|
||||
// pair. This endpoint asks the opposite question of exactly one language, and
|
||||
// [auth.SupportsLearnerDirection] already guarantees that language is Chinese.
|
||||
// Routing it through the pair would add a database read per hover to choose
|
||||
// between one option and itself.
|
||||
func (h *Handler) HanziRoutes() chi.Router {
|
||||
r := chi.NewRouter()
|
||||
r.Get("/{word}", h.hanzi)
|
||||
return r
|
||||
}
|
||||
|
||||
// hanzi answers a Chinese word lookup. Like the other two, a miss is a 200 with
|
||||
// empty lists — a hover that lands on a word the dictionary has never heard of
|
||||
// is an ordinary thing to happen while reading, and the tooltip simply doesn't
|
||||
// open.
|
||||
func (h *Handler) hanzi(w http.ResponseWriter, r *http.Request) {
|
||||
res, err := h.Set.Hanzi(pathWord(r))
|
||||
if err != nil {
|
||||
writeLookupErr(w, err)
|
||||
return
|
||||
}
|
||||
writeLookup(w, res)
|
||||
}
|
||||
|
||||
// providerFor returns the provider for the caller's language pair.
|
||||
//
|
||||
// The pair language is read here rather than threaded down because a word
|
||||
|
||||
@@ -0,0 +1,144 @@
|
||||
package lexicon
|
||||
|
||||
import (
|
||||
"fmt"
|
||||
"strings"
|
||||
"sync"
|
||||
"unicode"
|
||||
)
|
||||
|
||||
// The Chinese half of the lexicon: a word written in hanzi to its pinyin and
|
||||
// English senses. This is the mirror image of `gloss` — that one reads English
|
||||
// and answers in Chinese, for a Mandarin native practising English; this one
|
||||
// reads Chinese and answers in English, for the other direction of the same
|
||||
// pair (`users.direction = 'learning_pair'`).
|
||||
//
|
||||
// It is deliberately not folded into [Lexicon.load]. That method reads four
|
||||
// datasets on the first lookup of any kind, and this one is 3.1 MB gzipped that
|
||||
// only a learner-direction account will ever ask for — every other writer would
|
||||
// pay the decompression and the resident memory for a map they never touch. Its
|
||||
// own sync.Once means the cost lands on the first Chinese hover and nowhere
|
||||
// else.
|
||||
|
||||
// HanziReading is one pronunciation of a word and the senses it carries in that
|
||||
// pronunciation. A word usually has one; the ones that have two are why this is
|
||||
// a list rather than a pair of strings. 得 is dé, "to obtain", *and* de, the
|
||||
// particle that makes 说得很好 mean "speaks well" — a learner shown only the
|
||||
// first has been told something false about the sentence in front of them.
|
||||
type HanziReading struct {
|
||||
Pinyin string `json:"pinyin"`
|
||||
Senses string `json:"senses"`
|
||||
}
|
||||
|
||||
// HanziChar is one character of a word that the dictionary could not answer as
|
||||
// a whole. See [Lexicon.Hanzi].
|
||||
type HanziChar struct {
|
||||
Char string `json:"char"`
|
||||
Pinyin string `json:"pinyin"`
|
||||
Senses string `json:"senses"`
|
||||
}
|
||||
|
||||
// HanziResult is what a Chinese word lookup answers. Readings is empty for a
|
||||
// word the dictionary does not have, in which case Chars may carry the
|
||||
// character-by-character reading instead.
|
||||
type HanziResult struct {
|
||||
Word string `json:"word"`
|
||||
Readings []HanziReading `json:"readings"`
|
||||
Chars []HanziChar `json:"chars"`
|
||||
}
|
||||
|
||||
type hanziStore struct {
|
||||
once sync.Once
|
||||
err error
|
||||
// word → [[pinyin, senses], …], exactly as scripts/build_cedict.py writes it.
|
||||
entries map[string][][]string
|
||||
}
|
||||
|
||||
var hanzi hanziStore
|
||||
|
||||
func (h *hanziStore) load() {
|
||||
h.once.Do(func() {
|
||||
if err := gunzipJSON(hanziGz, &h.entries); err != nil {
|
||||
h.err = fmt.Errorf("load hanzi: %w", err)
|
||||
}
|
||||
})
|
||||
}
|
||||
|
||||
// maxHanziChars caps the per-character fallback. A run longer than this is
|
||||
// almost certainly a phrase the segmenter split badly rather than a word, and
|
||||
// spelling out eight characters one at a time is a wall, not a hint.
|
||||
const maxHanziChars = 6
|
||||
|
||||
// Hanzi returns the pinyin and English senses of a Chinese word.
|
||||
//
|
||||
// There is no de-inflection walk here, and its absence is a fact about the
|
||||
// language rather than an omission: Chinese words do not inflect, so the
|
||||
// candidate forms [lookupGloss] tries for "running" → "run" have no analogue.
|
||||
// A lookup either hits the headword or it does not.
|
||||
//
|
||||
// What it does instead is fall back to the characters. The segmentation word
|
||||
// list is a superset of this dictionary — every glossable word can be
|
||||
// segmented, but jieba knows ordinary compounds CC-CEDICT has no entry for — so
|
||||
// a hover really can land on a word with nothing to say about it. Chinese
|
||||
// compounds are usually transparent from their parts (电脑 is "electric brain"),
|
||||
// which makes the character reading a genuinely useful second answer rather
|
||||
// than a consolation prize. It is returned as its own field so the surface can
|
||||
// say which of the two it is showing; a caller that only wants whole words can
|
||||
// ignore it.
|
||||
func (l *Lexicon) Hanzi(word string) (HanziResult, error) {
|
||||
hanzi.load()
|
||||
if hanzi.err != nil {
|
||||
return HanziResult{}, hanzi.err
|
||||
}
|
||||
|
||||
norm := strings.TrimSpace(word)
|
||||
res := HanziResult{Word: word, Readings: []HanziReading{}, Chars: []HanziChar{}}
|
||||
if norm == "" {
|
||||
return res, nil
|
||||
}
|
||||
|
||||
if rows, ok := hanzi.entries[norm]; ok {
|
||||
res.Readings = toReadings(rows)
|
||||
return res, nil
|
||||
}
|
||||
|
||||
chars := []rune(norm)
|
||||
if len(chars) < 2 || len(chars) > maxHanziChars {
|
||||
// A single character that missed has no parts to fall back to, and a long
|
||||
// run is not a word. Either way the honest answer is nothing.
|
||||
return res, nil
|
||||
}
|
||||
for _, r := range chars {
|
||||
if !unicode.Is(unicode.Han, r) {
|
||||
// Mixed input (a stray letter or digit inside the run) is not something
|
||||
// the character reading can explain, and guessing at the hanzi parts of
|
||||
// it would be worse than silence.
|
||||
return HanziResult{Word: word, Readings: []HanziReading{}, Chars: []HanziChar{}}, nil
|
||||
}
|
||||
rows, ok := hanzi.entries[string(r)]
|
||||
if !ok {
|
||||
continue
|
||||
}
|
||||
first := toReadings(rows)
|
||||
if len(first) == 0 {
|
||||
continue
|
||||
}
|
||||
res.Chars = append(res.Chars, HanziChar{
|
||||
Char: string(r),
|
||||
Pinyin: first[0].Pinyin,
|
||||
Senses: first[0].Senses,
|
||||
})
|
||||
}
|
||||
return res, nil
|
||||
}
|
||||
|
||||
func toReadings(rows [][]string) []HanziReading {
|
||||
out := make([]HanziReading, 0, len(rows))
|
||||
for _, row := range rows {
|
||||
if len(row) < 2 {
|
||||
continue
|
||||
}
|
||||
out = append(out, HanziReading{Pinyin: row[0], Senses: row[1]})
|
||||
}
|
||||
return out
|
||||
}
|
||||
@@ -0,0 +1,150 @@
|
||||
package lexicon
|
||||
|
||||
import (
|
||||
"encoding/json"
|
||||
"net/http"
|
||||
"net/http/httptest"
|
||||
"strings"
|
||||
"testing"
|
||||
|
||||
"github.com/go-chi/chi/v5"
|
||||
)
|
||||
|
||||
// The Chinese direction of the lexicon, against the real embedded asset — not a
|
||||
// fixture. The dataset is built by scripts/build_cedict.py, which asserts its
|
||||
// own invariants at build time; what these assert is that the *lookup* over it
|
||||
// behaves, including on the entries the build script goes out of its way to keep.
|
||||
|
||||
func TestHanziLookup(t *testing.T) {
|
||||
l := New()
|
||||
|
||||
res, err := l.Hanzi("公园")
|
||||
if err != nil {
|
||||
t.Fatalf("lookup 公园: %v", err)
|
||||
}
|
||||
if len(res.Readings) == 0 {
|
||||
t.Fatal("公园 has no readings")
|
||||
}
|
||||
// Tone marks, not the numbered pinyin CC-CEDICT stores. The number is the
|
||||
// storage format; the marks are what a learner reads.
|
||||
if got := res.Readings[0].Pinyin; got != "gōngyuán" {
|
||||
t.Errorf("公园 pinyin = %q, want gōngyuán", got)
|
||||
}
|
||||
if !strings.Contains(res.Readings[0].Senses, "park") {
|
||||
t.Errorf("公园 senses = %q, want something about a park", res.Readings[0].Senses)
|
||||
}
|
||||
// A word answered whole says nothing about its characters — the fallback is
|
||||
// the other branch, and sending both would double the payload of the common
|
||||
// case to no purpose.
|
||||
if len(res.Chars) != 0 {
|
||||
t.Errorf("a whole-word hit also returned %d characters", len(res.Chars))
|
||||
}
|
||||
}
|
||||
|
||||
// 得 is the reason readings are a list. Answered with only dé "to obtain", a
|
||||
// learner hovering it in 说得很好 has been told something false about the
|
||||
// sentence they are looking at.
|
||||
func TestHanziParticleCarriesItsGrammaticalReading(t *testing.T) {
|
||||
l := New()
|
||||
|
||||
for _, particle := range []string{"的", "地", "得"} {
|
||||
res, err := l.Hanzi(particle)
|
||||
if err != nil {
|
||||
t.Fatalf("lookup %s: %v", particle, err)
|
||||
}
|
||||
var found bool
|
||||
for _, r := range res.Readings {
|
||||
if r.Pinyin == "de" {
|
||||
found = true
|
||||
}
|
||||
}
|
||||
if !found {
|
||||
t.Errorf("%s never reads as neutral \"de\": %+v", particle, res.Readings)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// The fallback the segmentation gap makes necessary: jieba knows ordinary
|
||||
// compounds CC-CEDICT has no headword for, so a hover can land on a real word
|
||||
// with no entry. Chinese compounds are usually transparent from their parts, so
|
||||
// the characters are a real second answer.
|
||||
func TestHanziFallsBackToCharacters(t *testing.T) {
|
||||
l := New()
|
||||
|
||||
// Constructed rather than borrowed from the corpus: a word that CC-CEDICT
|
||||
// *does* carry would test the other branch, and which compounds it happens to
|
||||
// omit is not something a test should pin.
|
||||
const made = "猫书"
|
||||
if _, ok := hanzi.entries[made]; ok {
|
||||
t.Skipf("%s has become a real headword; pick another compound", made)
|
||||
}
|
||||
res, err := l.Hanzi(made)
|
||||
if err != nil {
|
||||
t.Fatalf("lookup %s: %v", made, err)
|
||||
}
|
||||
if len(res.Readings) != 0 {
|
||||
t.Fatalf("%s answered as a whole word: %+v", made, res.Readings)
|
||||
}
|
||||
if len(res.Chars) != 2 {
|
||||
t.Fatalf("character fallback gave %d entries, want 2: %+v", len(res.Chars), res.Chars)
|
||||
}
|
||||
if res.Chars[0].Char != "猫" || !strings.Contains(res.Chars[0].Senses, "cat") {
|
||||
t.Errorf("first character = %+v, want 猫 ~ cat", res.Chars[0])
|
||||
}
|
||||
if res.Chars[0].Pinyin != "māo" {
|
||||
t.Errorf("猫 pinyin = %q, want māo", res.Chars[0].Pinyin)
|
||||
}
|
||||
}
|
||||
|
||||
func TestHanziMisses(t *testing.T) {
|
||||
l := New()
|
||||
|
||||
for name, word := range map[string]string{
|
||||
// A single character with no entry has no parts to fall back to.
|
||||
"lone unknown character": "龥",
|
||||
"empty": "",
|
||||
"whitespace": " ",
|
||||
// Not Chinese at all: the English tokenizer owns these, and answering
|
||||
// would mean guessing.
|
||||
"english": "hello",
|
||||
"mixed": "猫cat",
|
||||
// Longer than a word: a bad segmentation, not something to spell out
|
||||
// character by character.
|
||||
"a whole clause": "我今天早上去公园跑步了",
|
||||
} {
|
||||
res, err := l.Hanzi(word)
|
||||
if err != nil {
|
||||
t.Fatalf("%s: %v", name, err)
|
||||
}
|
||||
if len(res.Readings) != 0 || len(res.Chars) != 0 {
|
||||
t.Errorf("%s (%q) answered with %+v / %+v", name, word, res.Readings, res.Chars)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func TestHanziEndpoint(t *testing.T) {
|
||||
h := NewHandler(nil, NewSet(nil))
|
||||
r := chi.NewRouter()
|
||||
r.Mount("/hanzi", h.HanziRoutes())
|
||||
|
||||
w := httptest.NewRecorder()
|
||||
r.ServeHTTP(w, httptest.NewRequest(http.MethodGet, "/hanzi/"+"跑步", nil))
|
||||
if w.Code != http.StatusOK {
|
||||
t.Fatalf("status = %d", w.Code)
|
||||
}
|
||||
var got HanziResult
|
||||
if err := json.Unmarshal(w.Body.Bytes(), &got); err != nil {
|
||||
t.Fatalf("decode: %v", err)
|
||||
}
|
||||
if got.Word != "跑步" || len(got.Readings) == 0 || got.Readings[0].Pinyin != "pǎobù" {
|
||||
t.Fatalf("response = %+v", got)
|
||||
}
|
||||
|
||||
// A miss is a 200 with empty lists, like the other two lookups — the tooltip
|
||||
// quietly doesn't open rather than showing an error over her writing.
|
||||
w = httptest.NewRecorder()
|
||||
r.ServeHTTP(w, httptest.NewRequest(http.MethodGet, "/hanzi/zzz", nil))
|
||||
if w.Code != http.StatusOK {
|
||||
t.Fatalf("miss: status = %d, want 200", w.Code)
|
||||
}
|
||||
}
|
||||
@@ -109,3 +109,13 @@ func (g glossless) Lookup(word string) (Result, error) {
|
||||
func (g glossless) Gloss(word string) (GlossResult, error) {
|
||||
return GlossResult{Word: word}, nil
|
||||
}
|
||||
|
||||
// Hanzi answers a Chinese-word lookup from the embedded CC-CEDICT map.
|
||||
//
|
||||
// It is on the Set rather than on [Provider] because it is not the same
|
||||
// question the other two ask. Lookup and Gloss vary by pair — which is why they
|
||||
// are behind an interface with two implementations — while this one is asked of
|
||||
// Chinese or not at all: the learner direction exists for exactly one pair (see
|
||||
// auth.learnerPairs), and DreamDict's own CC-CEDICT would be a second copy of
|
||||
// the same dictionary, chosen by a rule with one branch.
|
||||
func (s *Set) Hanzi(word string) (HanziResult, error) { return s.embedded.Hanzi(word) }
|
||||
|
||||
@@ -201,3 +201,36 @@ func TestOfflineCardWinsSpanCollision(t *testing.T) {
|
||||
t.Errorf("the exact offline card should own the span, got %+v", got[0])
|
||||
}
|
||||
}
|
||||
|
||||
// TestOfflineHanziFindingStaysMechanics: a 错别字 the Chinese rule pack found —
|
||||
// both halves written in hanzi — files as an ordinary mechanics row.
|
||||
//
|
||||
// The check is worth its own test because there is a rule one layer over that
|
||||
// would plausibly claim it. `isTranslation` re-labels an edit whose original
|
||||
// reads as the writer's language and whose replacement reads as English, which
|
||||
// is exactly how a zh-pair writer's quoted Chinese becomes a 'translate' card.
|
||||
// A wrong-character fix looks like the first half of that and nothing like the
|
||||
// second: 己经 → 已经 never leaves Chinese. It must stay a tidy-up in her own
|
||||
// sentence, on the same rail as a doubled word, with no rendering-into-English
|
||||
// implied anywhere.
|
||||
func TestOfflineHanziFindingStaysMechanics(t *testing.T) {
|
||||
srv, docID, _ := newTestServer(t, &stubClient{response: `{"suggestions":[]}`})
|
||||
|
||||
got := postMechanics(t, srv, docID, `[
|
||||
{"from":1,"to":3,"original":"己经","replacement":"已经","explanation":"已经 (already) takes 已","type":"mechanics"}
|
||||
]`)
|
||||
if len(got) != 1 {
|
||||
t.Fatalf("want the one finding, got %+v", got)
|
||||
}
|
||||
if got[0].Type != db.SuggestionTypeMechanics {
|
||||
t.Errorf("hanzi fix filed as %q, want %q", got[0].Type, db.SuggestionTypeMechanics)
|
||||
}
|
||||
if got[0].Source != db.SuggestionSourceLocal {
|
||||
t.Errorf("source = %q, want %q", got[0].Source, db.SuggestionSourceLocal)
|
||||
}
|
||||
// The characters survive the round trip intact — a mangled span here would
|
||||
// replace the wrong characters in her document.
|
||||
if got[0].Original != "己经" || got[0].Replacement != "已经" {
|
||||
t.Errorf("round-tripped as %q → %q", got[0].Original, got[0].Replacement)
|
||||
}
|
||||
}
|
||||
|
||||
@@ -0,0 +1,322 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Build the two Chinese assets the learner direction of the zh pair needs.
|
||||
|
||||
Why two, and why they are split the way they are
|
||||
------------------------------------------------
|
||||
Every other pair Petal ships needs one asset: a word list the browser loads so
|
||||
it can underline. Chinese needs two, because the browser and the server want
|
||||
different halves of the same dictionary and for different reasons.
|
||||
|
||||
* **The browser needs a word list, and it needs it offline.** Chinese is
|
||||
written without spaces, so there is no such thing as "the word under the
|
||||
cursor" until something segments the sentence. Every ESL surface Petal
|
||||
already has — the hover gloss, the right-click lookup, Ctrl/Cmd+D, the
|
||||
vocabulary garden capture — is built on `wordAt`, and `wordAt` is a regex
|
||||
over Latin letters. Segmentation is what replaces that regex, it runs on
|
||||
every hover, and a round-trip per hover is not a hover. So the word list
|
||||
ships to the browser: `web/public/dictionaries/zh/words.txt`.
|
||||
|
||||
* **The server holds the whole dictionary.** Pinyin and English senses are
|
||||
only ever wanted one word at a time, in answer to a hover or a click, which
|
||||
is exactly what `/api/gloss/{word}` already does for the other direction. So
|
||||
the readings stay in the binary — `internal/lexicon/data/hanzi.json.gz` —
|
||||
where their size costs a browser nothing.
|
||||
|
||||
That split is what makes the coverage decisions below come out *opposite* to
|
||||
each other, and both are deliberate.
|
||||
|
||||
Two sources, because neither one has both halves
|
||||
------------------------------------------------
|
||||
* **CC-CEDICT** (CC BY-SA 4.0, https://www.mdbg.net/) has the headwords,
|
||||
pinyin and English senses, and no frequency information at all.
|
||||
* **jieba's `dict.txt`** (MIT, https://github.com/fxsjy/jieba) has ~349k
|
||||
headwords with corpus frequencies, and no definitions.
|
||||
|
||||
Segmentation needs the frequencies: the standard algorithm is a shortest-path
|
||||
walk over log-probabilities, not longest-match, and without frequencies the
|
||||
classic ambiguities go the wrong way. The client list therefore carries
|
||||
`word freq` per line; the gloss map carries readings.
|
||||
|
||||
The size decision is the client list, and it is a size decision only
|
||||
--------------------------------------------------------------------
|
||||
Measured on ordinary learner prose, the segmentation produced by the full jieba
|
||||
dictionary (381,886 hanzi headwords once CC-CEDICT is unioned in) and by a
|
||||
frequency-gated one is **identical**, including on the textbook ambiguities
|
||||
(研究生命的起源, 乒乓球拍卖完了, 南京市长江大桥). What the long tail contains is
|
||||
rare proper nouns, and the max-probability walk almost never chooses one: a
|
||||
freq-3 name loses to two common words every time. The cases where a missing word
|
||||
does change the answer degrade *gracefully* — the sentence splits into smaller
|
||||
real words, which is a slightly clumsier gloss, not a wrong underline.
|
||||
|
||||
So the gate is set where the size is, at **freq >= 5**: 188,522 words, ~0.97 MB
|
||||
gzipped over the wire, in line with fr (1.19 MB) and es (1.74 MB) rather than in
|
||||
excess of them. Every CC-CEDICT headword is unioned back in regardless of
|
||||
frequency, so the segmenter can always see a word the server can explain.
|
||||
|
||||
The gloss map is gated by nothing, for the opposite reason
|
||||
-----------------------------------------------------------
|
||||
The es phase settled that a *spelling* dictionary should hold the union of every
|
||||
variety, because its only power is to underline and it must not underline
|
||||
correct writing. This asset's only power is to **explain**, and the word a
|
||||
learner stops on is precisely the one they do not know — which is to say, the
|
||||
rare one. Trimming this by frequency would remove exactly the entries it exists
|
||||
for. All 113,637 glossable headwords ship, ~3.1 MB gzipped, which is less than
|
||||
half of what `synonyms.json.gz` has embedded since Phase 9.
|
||||
|
||||
Simplified only, and said out loud
|
||||
-----------------------------------
|
||||
The zh langpack is written in simplified characters and jieba's frequencies are
|
||||
counted over simplified text, so the traditional headword in each CC-CEDICT line
|
||||
is dropped and simplified is what both assets are keyed by. Glossing traditional
|
||||
would be nearly free *here* and useless in the app: nothing would segment it, so
|
||||
nothing would ever ask. Traditional support is a real feature and it starts with
|
||||
a traditional word list, not with this file.
|
||||
|
||||
Usage:
|
||||
curl -sL https://www.mdbg.net/chinese/export/cedict/cedict_1_0_ts_utf-8_mdbg.txt.gz | gunzip > cedict.txt
|
||||
curl -sL https://raw.githubusercontent.com/fxsjy/jieba/master/jieba/dict.txt -o jieba.txt
|
||||
python3 scripts/build_cedict.py cedict.txt jieba.txt \
|
||||
web/public/dictionaries/zh/words.txt.gz \
|
||||
internal/lexicon/data/hanzi.json.gz
|
||||
"""
|
||||
import gzip
|
||||
import json
|
||||
import re
|
||||
import sys
|
||||
|
||||
# Frequency gate for the *client* list only (see the module docstring). Words
|
||||
# below it survive if CC-CEDICT knows them, so "segmentable" is always a superset
|
||||
# of "glossable" and a hover can never land on a word the server cannot explain.
|
||||
MIN_FREQ = 5
|
||||
|
||||
# A CC-CEDICT headword we keep must be nothing but han characters. This drops the
|
||||
# entries that are really English or numerals with a Chinese gloss attached
|
||||
# ("AA制", "PM2.5", "11区"): the segmenter walks runs of hanzi, so a mixed
|
||||
# headword can never be matched anyway, and a Latin one would collide with the
|
||||
# English tokenizer that is still running on the same paragraph.
|
||||
HANZI_ONLY = re.compile(r'^[一-鿿]+$')
|
||||
|
||||
CEDICT_LINE = re.compile(r'^(\S+) (\S+) \[(.*?)\] /(.*)/$')
|
||||
|
||||
# At most this many readings per word, and this many senses per reading. Two
|
||||
# readings is not an arbitrary cap: it is what the particles need. 得 is dé "to
|
||||
# obtain" *and* de, the complement marker — and a learner who hovers 得 in
|
||||
# 说得很好 and is told only "to obtain" has been actively misinformed. Beyond two
|
||||
# the tail is dialect and surnames, which crowd out the sense actually wanted.
|
||||
MAX_READINGS = 2
|
||||
MAX_SENSES = 3
|
||||
MAX_SENSE_CHARS = 110
|
||||
|
||||
# Senses that describe the *dictionary* rather than the word. A learner hovering
|
||||
# a word wants to know what it means, not that it is an orthographic variant of
|
||||
# another headword they also do not know.
|
||||
SKIP_SENSE_PREFIXES = ('variant of', 'old variant', 'see ', 'used in', 'abbr. for')
|
||||
|
||||
# ── pinyin: numbered syllables to tone marks ────────────────────────────────
|
||||
# CC-CEDICT stores "gong1 yuan2". A learner reading their own writing back wants
|
||||
# gōngyuán: the tone mark is the part that is hard to remember and the part that
|
||||
# changes the word. The placement rule is the standard one — a/o/e take the mark
|
||||
# if present, otherwise the last vowel of the final — and it is small enough to
|
||||
# do here rather than to take a dependency for.
|
||||
TONE_VOWELS = {
|
||||
'a': 'āáǎà',
|
||||
'e': 'ēéěè',
|
||||
'i': 'īíǐì',
|
||||
'o': 'ōóǒò',
|
||||
'u': 'ūúǔù',
|
||||
'ü': 'ǖǘǚǜ',
|
||||
}
|
||||
|
||||
SYLLABLE = re.compile(r'^([a-zA-Zü:]+)([1-5])$')
|
||||
|
||||
|
||||
def tone_mark(syllable: str) -> str:
|
||||
"""One numbered pinyin syllable to its tone-marked form."""
|
||||
m = SYLLABLE.match(syllable)
|
||||
if not m:
|
||||
# Punctuation, a bare letter (CC-CEDICT writes "X" for unknown), or an
|
||||
# already-marked syllable: pass it through rather than mangling it.
|
||||
return syllable
|
||||
body, tone = m.group(1), int(m.group(2))
|
||||
# CC-CEDICT writes ü as "u:" and, in a few entries, as "v".
|
||||
body = body.replace('u:', 'ü').replace('U:', 'Ü').replace('v', 'ü').replace('V', 'Ü')
|
||||
if tone == 5: # neutral tone carries no mark
|
||||
return body
|
||||
low = body.lower()
|
||||
idx = -1
|
||||
for vowel in ('a', 'o', 'e'):
|
||||
idx = low.find(vowel)
|
||||
if idx >= 0:
|
||||
break
|
||||
if idx < 0:
|
||||
# No a/o/e: the mark goes on the last of i/u/ü (liú, guǐ, nǚ).
|
||||
idx = max(low.rfind('i'), low.rfind('u'), low.rfind('ü'))
|
||||
if idx < 0:
|
||||
return body
|
||||
marked = TONE_VOWELS[low[idx]][tone - 1]
|
||||
if body[idx].isupper():
|
||||
marked = marked.upper()
|
||||
return body[:idx] + marked + body[idx + 1:]
|
||||
|
||||
|
||||
def pinyin(numbered: str) -> str:
|
||||
"""A whole CC-CEDICT pinyin field to tone marks, syllables joined up.
|
||||
|
||||
Joined rather than spaced because that is how a word is written when it is
|
||||
being read as a word (gōngyuán, not gōng yuán); the spaces in the source are
|
||||
a storage convention, not orthography.
|
||||
"""
|
||||
return ''.join(tone_mark(s) for s in numbered.split())
|
||||
|
||||
|
||||
def clean_senses(raw: list[str]) -> list[str]:
|
||||
"""Strip the apparatus CC-CEDICT carries for lexicographers, not learners."""
|
||||
out = []
|
||||
for sense in raw:
|
||||
# "CL:座[zuo4]" is the measure-word field, useful and not a definition.
|
||||
sense = re.sub(r'\s*CL:.*$', '', sense).strip()
|
||||
# Bracketed pinyin cross-references ("abbr. for 的士[di1 shi4]").
|
||||
sense = re.sub(r'\[[a-zA-Z0-9: ]+\]', '', sense).strip()
|
||||
# Both edits cut inside parentheses — "cat (CL:只)" loses its closing
|
||||
# bracket and leaves "cat (" on the card. Drop a dangling opener rather
|
||||
# than trying to rebalance: what it introduced is gone.
|
||||
if sense.count('(') > sense.count(')'):
|
||||
sense = re.sub(r'\s*\([^()]*$', '', sense).strip()
|
||||
if not sense or sense.startswith(SKIP_SENSE_PREFIXES):
|
||||
continue
|
||||
out.append(sense)
|
||||
return out
|
||||
|
||||
|
||||
def read_cedict(path: str) -> dict[str, list[tuple[str, list[str]]]]:
|
||||
entries: dict[str, list[tuple[str, list[str]]]] = {}
|
||||
for line in open(path, encoding='utf-8'):
|
||||
if line.startswith('#'):
|
||||
continue
|
||||
m = CEDICT_LINE.match(line.strip())
|
||||
if not m:
|
||||
continue
|
||||
_traditional, simplified, py, defs = m.groups()
|
||||
if not HANZI_ONLY.match(simplified):
|
||||
continue
|
||||
entries.setdefault(simplified, []).append((py, defs.split('/')))
|
||||
return entries
|
||||
|
||||
|
||||
def read_jieba(path: str) -> dict[str, int]:
|
||||
freqs: dict[str, int] = {}
|
||||
for line in open(path, encoding='utf-8'):
|
||||
parts = line.split()
|
||||
if len(parts) >= 2 and HANZI_ONLY.match(parts[0]):
|
||||
freqs[parts[0]] = int(parts[1])
|
||||
return freqs
|
||||
|
||||
|
||||
# ── the assertions ──────────────────────────────────────────────────────────
|
||||
# The es phase's lesson, in the place it applies here: a check that every
|
||||
# plausible input would pass is not a check. The Spanish MUST_ACCEPT list
|
||||
# asserted vocabulary that all twenty-four builds carried, so it could not tell
|
||||
# them apart. These assert the things that actually go wrong in *this* build —
|
||||
# a mis-parsed pinyin field, a missing particle reading, a word list gated so
|
||||
# hard the segmenter can no longer see a word the server can explain.
|
||||
|
||||
# Tone marking, including the three cases the placement rule exists for.
|
||||
MUST_MARK = {
|
||||
'gong1 yuan2': 'gōngyuán', # a/o/e rule, first syllable
|
||||
'pao3 bu4': 'pǎobù',
|
||||
'liu2': 'liú', # no a/o/e: mark the *last* of i/u
|
||||
'gui3': 'guǐ',
|
||||
'nu:3': 'nǚ', # u: is ü
|
||||
'lu:e4': 'lüè', # ü and an e in the same syllable: e wins
|
||||
'de5': 'de', # neutral tone takes no mark at all
|
||||
'Zhong1 wen2': 'Zhōngwén', # capitalised headword keeps its capital
|
||||
}
|
||||
|
||||
# The particles the 错别字 rules are about must each carry the *grammatical*
|
||||
# reading, not only the lexical one. 的/地/得 are the single most confused triple
|
||||
# in written Chinese and all three are neutral-tone "de" in the use that matters;
|
||||
# an entry that only knows 得 as dé is worse than no entry.
|
||||
MUST_READ_DE = ('的', '地', '得')
|
||||
|
||||
# Words the segmenter must be able to see. 图书馆 and 乒乓球 are ordinary
|
||||
# vocabulary; 我 and 的 are the two commonest words in the language and a gate
|
||||
# that dropped either would be visibly broken; 的士 is a CC-CEDICT headword rare
|
||||
# enough to fall below the frequency gate, and is here to prove the union.
|
||||
MUST_SEGMENT = ('我', '的', '图书馆', '乒乓球', '公园', '的士')
|
||||
|
||||
|
||||
def check(words: dict[str, int], gloss: dict[str, list[list[str]]]) -> None:
|
||||
for numbered, want in MUST_MARK.items():
|
||||
got = pinyin(numbered)
|
||||
assert got == want, f'pinyin({numbered!r}) = {got!r}, want {want!r}'
|
||||
|
||||
for particle in MUST_READ_DE:
|
||||
readings = gloss.get(particle)
|
||||
assert readings, f'{particle} has no gloss entry at all'
|
||||
assert any(r[0] == 'de' for r in readings), \
|
||||
f'{particle} never reads as neutral "de": {readings}'
|
||||
|
||||
for word in MUST_SEGMENT:
|
||||
assert word in words, f'{word} missing from the segmentation list'
|
||||
|
||||
# The invariant the two gates exist to keep: everything the server can
|
||||
# explain, the browser can find.
|
||||
missing = [w for w in gloss if w not in words]
|
||||
assert not missing, f'{len(missing)} glossable words are unsegmentable, e.g. {missing[:5]}'
|
||||
|
||||
# Nothing Latin leaked into either asset (see HANZI_ONLY).
|
||||
for name, keys in (('words', words), ('gloss', gloss)):
|
||||
bad = [k for k in keys if not HANZI_ONLY.match(k)]
|
||||
assert not bad, f'non-hanzi headwords in {name}: {bad[:5]}'
|
||||
|
||||
|
||||
def main() -> None:
|
||||
if len(sys.argv) != 5:
|
||||
sys.exit(__doc__.strip().rsplit('Usage:', 1)[-1].strip())
|
||||
cedict_path, jieba_path, words_out, gloss_out = sys.argv[1:]
|
||||
|
||||
entries = read_cedict(cedict_path)
|
||||
freqs = read_jieba(jieba_path)
|
||||
|
||||
# The client list: frequency-gated, then unioned with every glossable word.
|
||||
# A CC-CEDICT word jieba has never seen gets frequency 1 — real, and rare
|
||||
# enough that the max-probability walk will only choose it when nothing else
|
||||
# fits, which is exactly the standing it should have.
|
||||
words = {w: f for w, f in freqs.items() if f >= MIN_FREQ}
|
||||
for w in entries:
|
||||
words.setdefault(w, 1)
|
||||
|
||||
gloss: dict[str, list[list[str]]] = {}
|
||||
for word, rows in entries.items():
|
||||
readings: list[list[str]] = []
|
||||
for numbered, defs in rows:
|
||||
senses = clean_senses(defs)
|
||||
if not senses:
|
||||
continue
|
||||
readings.append([pinyin(numbered), '; '.join(senses[:MAX_SENSES])[:MAX_SENSE_CHARS]])
|
||||
if len(readings) == MAX_READINGS:
|
||||
break
|
||||
if readings:
|
||||
gloss[word] = readings
|
||||
|
||||
check(words, gloss)
|
||||
|
||||
# Gzipped on disk, like the pt-PT/fr/es word lists: the browser inflates it
|
||||
# with DecompressionStream (see useSpellChecker.fetchText), which costs no
|
||||
# bundle bytes, and 0.97 MB over the wire rather than 2.23 MB is the whole
|
||||
# difference between this and the biggest asset Petal ships.
|
||||
body = ('\n'.join(f'{w} {words[w]}' for w in sorted(words)) + '\n').encode('utf-8')
|
||||
with gzip.open(words_out, 'wb', compresslevel=9) as fh:
|
||||
fh.write(body)
|
||||
|
||||
payload = json.dumps(gloss, ensure_ascii=False, separators=(',', ':')).encode('utf-8')
|
||||
with gzip.open(gloss_out, 'wb', compresslevel=9) as fh:
|
||||
fh.write(payload)
|
||||
|
||||
print(f'{words_out}: {len(words)} words, {len(body) / 1e6:.2f} MB raw, '
|
||||
f'{len(gzip.compress(body, 9)) / 1e6:.2f} MB gzipped')
|
||||
print(f'{gloss_out}: {len(gloss)} entries, {len(gzip.compress(payload, 9)) / 1e6:.2f} MB gzipped')
|
||||
|
||||
|
||||
if __name__ == '__main__':
|
||||
main()
|
||||
Generated
+18
@@ -30,6 +30,7 @@
|
||||
},
|
||||
"devDependencies": {
|
||||
"@tailwindcss/vite": "^4.0.0",
|
||||
"@types/node": "^26.1.2",
|
||||
"@types/react": "^19.1.0",
|
||||
"@types/react-dom": "^19.1.0",
|
||||
"@vitejs/plugin-react": "^4.3.4",
|
||||
@@ -2107,6 +2108,16 @@
|
||||
"integrity": "sha512-RGdgjQUZba5p6QEFAVx2OGb8rQDL/cPRG7GiedRzMcJ1tYnUANBncjbSB1NRGwbvjcPeikRABz2nshyPk1bhWg==",
|
||||
"license": "MIT"
|
||||
},
|
||||
"node_modules/@types/node": {
|
||||
"version": "26.1.2",
|
||||
"resolved": "https://registry.npmjs.org/@types/node/-/node-26.1.2.tgz",
|
||||
"integrity": "sha512-Vu4a5UFA9rIIFJ7rB/Vaafh9lrCQszopTCx6KjFboXTGQbPNasehVR5TEiithSDGyd1DEiUByggTZsg8jukeIg==",
|
||||
"dev": true,
|
||||
"license": "MIT",
|
||||
"dependencies": {
|
||||
"undici-types": "~8.3.0"
|
||||
}
|
||||
},
|
||||
"node_modules/@types/react": {
|
||||
"version": "19.2.17",
|
||||
"resolved": "https://registry.npmjs.org/@types/react/-/react-19.2.17.tgz",
|
||||
@@ -3559,6 +3570,13 @@
|
||||
"integrity": "sha512-ARDJmphmdvUk6Glw7y9DQ2bFkKBHwQHLi2lsaH6PPmz/Ka9sFOBsBluozhDltWmnv9u/cF6Rt87znRTPV+yp/A==",
|
||||
"license": "MIT"
|
||||
},
|
||||
"node_modules/undici-types": {
|
||||
"version": "8.3.0",
|
||||
"resolved": "https://registry.npmjs.org/undici-types/-/undici-types-8.3.0.tgz",
|
||||
"integrity": "sha512-j375ScV60dom+YkPFIfTLcOiPxkN/buHz5GobjLhixFuANaNs3C9l4GmrWqejgXWJ7BbJcFYpTEUkS1Ge8bpZQ==",
|
||||
"dev": true,
|
||||
"license": "MIT"
|
||||
},
|
||||
"node_modules/update-browserslist-db": {
|
||||
"version": "1.2.3",
|
||||
"resolved": "https://registry.npmjs.org/update-browserslist-db/-/update-browserslist-db-1.2.3.tgz",
|
||||
|
||||
@@ -33,6 +33,7 @@
|
||||
},
|
||||
"devDependencies": {
|
||||
"@tailwindcss/vite": "^4.0.0",
|
||||
"@types/node": "^26.1.2",
|
||||
"@types/react": "^19.1.0",
|
||||
"@types/react-dom": "^19.1.0",
|
||||
"@vitejs/plugin-react": "^4.3.4",
|
||||
|
||||
@@ -0,0 +1,59 @@
|
||||
Chinese word list (segmentation)
|
||||
================================
|
||||
|
||||
`words.txt.gz` is not a spelling dictionary — Chinese has no spelling to check
|
||||
in the Hunspell sense. It is the word list Petal's segmenter walks, so that a
|
||||
sentence written without spaces has words in it to hover, look up and capture.
|
||||
Each line is `word frequency`. See scripts/build_cedict.py for how it is built
|
||||
and why it is gated where it is.
|
||||
|
||||
It is derived from two upstream sources, both redistributable, both credited
|
||||
here because the file itself has no room for a header.
|
||||
|
||||
|
||||
CC-CEDICT — the headwords
|
||||
-------------------------
|
||||
Community maintained free Chinese-English dictionary, published by MDBG.
|
||||
https://www.mdbg.net/chinese/dictionary?page=cedict
|
||||
|
||||
Licensed under the Creative Commons Attribution-ShareAlike 4.0 International
|
||||
License — https://creativecommons.org/licenses/by-sa/4.0/
|
||||
|
||||
Referenced works:
|
||||
CEDICT — Copyright (C) 1997, 1998 Paul Andrew Denisowski
|
||||
|
||||
CC-CEDICT is also the source of `internal/lexicon/data/hanzi.json.gz`, the
|
||||
pinyin and English senses embedded in the Petal binary. The same attribution and
|
||||
the same ShareAlike terms apply to that file; it is named here because it has
|
||||
nowhere of its own to say so.
|
||||
|
||||
|
||||
jieba — the frequencies
|
||||
-----------------------
|
||||
"结巴" Chinese word segmentation, by Sun Junyi.
|
||||
https://github.com/fxsjy/jieba
|
||||
|
||||
MIT License
|
||||
|
||||
Copyright (c) 2013 Sun Junyi
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||
of this software and associated documentation files (the "Software"), to deal
|
||||
in the Software without restriction, including without limitation the rights
|
||||
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
||||
copies of the Software, and to permit persons to whom the Software is
|
||||
furnished to do so, subject to the following conditions:
|
||||
|
||||
The above copyright notice and this permission notice shall be included in all
|
||||
copies or substantial portions of the Software.
|
||||
|
||||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||||
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
||||
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||||
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
||||
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
||||
SOFTWARE.
|
||||
|
||||
Only the word/frequency columns are used; jieba's part-of-speech tags and its
|
||||
algorithm are not (Petal's segmenter is its own, in web/src/lib/segment.ts).
|
||||
Binary file not shown.
+13
-2
@@ -3,6 +3,7 @@ import { api, type DocSummary, type DocUpdate, type Document, type Suggestion, t
|
||||
import { useAutoSave } from './hooks/useAutoSave'
|
||||
import { findingKey, useCheckpoint } from './hooks/useCheckpoint'
|
||||
import { useSpellChecker } from './hooks/useSpellChecker'
|
||||
import { useSegmenter } from './hooks/useSegmenter'
|
||||
import { useTags } from './hooks/useTags'
|
||||
import { DocList } from './components/DocList/DocList'
|
||||
import { EditorCore, type EditorChange } from './components/Editor/EditorCore'
|
||||
@@ -31,7 +32,7 @@ export default function App() {
|
||||
const night = useNightMode()
|
||||
// Who's writing, and whether the server still recognises them. `signedOut`
|
||||
// flips the moment any call comes back 401.
|
||||
const { me, signedOut } = useSession()
|
||||
const { me, signedOut, setDirection } = useSession()
|
||||
const t = usePack()
|
||||
// A real account to sign out of, as opposed to the hardcoded local user a
|
||||
// build without auth configured runs as.
|
||||
@@ -80,6 +81,13 @@ export default function App() {
|
||||
}, [])
|
||||
|
||||
const { status, schedule, saveNow } = useAutoSave(currentDoc?.id ?? null)
|
||||
// The Chinese word list, for a writer going the other way through the zh pair.
|
||||
// Gated on the account's own setting rather than on anything in the text: a
|
||||
// Mandarin native drafting English quotes Chinese constantly, and none of that
|
||||
// is what segmentation is for. Declared above the checkpoint because the
|
||||
// offline 错别字 pass reads it.
|
||||
const segmenter = useSegmenter(me?.direction === 'learning_pair')
|
||||
|
||||
const {
|
||||
suggestions,
|
||||
checking,
|
||||
@@ -91,7 +99,7 @@ export default function App() {
|
||||
runCollocation,
|
||||
removeSuggestion,
|
||||
resolveServerId,
|
||||
} = useCheckpoint(currentDoc?.id ?? null)
|
||||
} = useCheckpoint(currentDoc?.id ?? null, segmenter)
|
||||
// Browser-side spell checker — loads the en-US dictionary once per session.
|
||||
const { checker: spellChecker, addWord } = useSpellChecker()
|
||||
// The tag roster (with counts). Assignments live on the doc summaries below.
|
||||
@@ -528,6 +536,8 @@ export default function App() {
|
||||
onToggleTag={handleToggleTag}
|
||||
onCreateTag={handleCreateTag}
|
||||
account={account}
|
||||
direction={me?.direction}
|
||||
onDirection={setDirection}
|
||||
/>
|
||||
</div>
|
||||
|
||||
@@ -591,6 +601,7 @@ export default function App() {
|
||||
docId={currentDoc.id}
|
||||
initialContent={currentDoc.content}
|
||||
onChange={handleEditorChange}
|
||||
segmenter={segmenter}
|
||||
suggestions={suggestions}
|
||||
onAccept={handleAccept}
|
||||
onAcceptMany={handleAcceptMany}
|
||||
|
||||
@@ -210,6 +210,21 @@ export interface PersonalWords {
|
||||
words: string[]
|
||||
}
|
||||
|
||||
// One pronunciation of a Chinese word, and what it means in that pronunciation.
|
||||
// A list, because 得 is dé "to obtain" and also the particle in 说得很好.
|
||||
export interface HanziReading {
|
||||
pinyin: string
|
||||
senses: string
|
||||
}
|
||||
|
||||
// A Chinese word lookup. `readings` is empty for a word with no headword, in
|
||||
// which case `chars` may carry the character-by-character reading.
|
||||
export interface HanziInfo {
|
||||
word: string
|
||||
readings: HanziReading[]
|
||||
chars: { char: string; pinyin: string; senses: string }[]
|
||||
}
|
||||
|
||||
// Who's writing. Mirrors the backend db.User.
|
||||
export interface Me {
|
||||
id: string
|
||||
@@ -217,6 +232,11 @@ export interface Me {
|
||||
display_name: string
|
||||
created_at: string
|
||||
pair_lang: string
|
||||
// Which half of the pair is being learned: 'learning_en' (the writer is
|
||||
// native in pair_lang and practising English) or 'learning_pair' (the other
|
||||
// way round). Mirrors users.direction; the server refuses 'learning_pair' for
|
||||
// a pair it has no word list for.
|
||||
direction: string
|
||||
}
|
||||
|
||||
// Thrown when the server says the session is gone. Callers can tell it apart
|
||||
@@ -269,6 +289,15 @@ export const api = {
|
||||
setPairLang: (lang: string) =>
|
||||
req<Me>('/me', { method: 'PATCH', body: JSON.stringify({ pair_lang: lang }) }),
|
||||
|
||||
// Turn the pair around. Same endpoint, same contract, and deliberately a
|
||||
// separate call: the two fields are validated together server-side, so a
|
||||
// client that wants to change both says both in one request rather than
|
||||
// sending two that each pass on their own.
|
||||
setDirection: (direction: string) =>
|
||||
req<Me>('/me', { method: 'PATCH', body: JSON.stringify({ direction }) }),
|
||||
setPair: (lang: string, direction: string) =>
|
||||
req<Me>('/me', { method: 'PATCH', body: JSON.stringify({ pair_lang: lang, direction }) }),
|
||||
|
||||
listDocs: () => req<DocSummary[]>('/docs'),
|
||||
createDoc: () => req<Document>('/docs', { method: 'POST' }),
|
||||
getDoc: (id: string) => req<Document>(`/docs/${id}`),
|
||||
@@ -348,6 +377,12 @@ export const api = {
|
||||
// Lightweight Chinese-only gloss for the inline hover/select tooltip — instant
|
||||
// and offline, so it fires on hover without spinning up the heavier lookup.
|
||||
glossWord: (word: string) => req<Gloss>(`/gloss/${encodeURIComponent(word)}`),
|
||||
// The same lookup pointing the other way: a Chinese word to its pinyin and
|
||||
// English senses, for an account learning the pair language rather than
|
||||
// English. A word the dictionary has no headword for comes back with empty
|
||||
// readings and — when its characters are known — a per-character reading
|
||||
// instead, which is a real second answer for a compound.
|
||||
hanziWord: (word: string) => req<HanziInfo>(`/hanzi/${encodeURIComponent(word)}`),
|
||||
// Tone-rewrite: rewrites a selected passage in the given style ('natural',
|
||||
// 'academic', …) and returns the rewritten text for an in-editor preview. Not
|
||||
// persisted — the editor applies it directly on accept.
|
||||
|
||||
@@ -0,0 +1,141 @@
|
||||
import { readFileSync } from 'node:fs'
|
||||
import { gunzipSync } from 'node:zlib'
|
||||
import { describe, expect, it } from 'vitest'
|
||||
|
||||
import { CONFUSION_PAIRS, hanziFindings } from './hanzi'
|
||||
import { buildSegmenter } from '../../lib/segment'
|
||||
|
||||
// The 错别字 pack, held to the bar Phase 22 set for the English rule pack: every
|
||||
// rule pinned in *two* directions — the mistake it must catch, and the correct
|
||||
// writing next to it that it must leave alone.
|
||||
//
|
||||
// Here the second direction is the one that matters, and it is unusually easy to
|
||||
// get wrong. Chinese has no spaces, so every one of these rules is a substring
|
||||
// match on running text, and for most of them there exists an ordinary correct
|
||||
// sentence that contains the substring across a word boundary. Those sentences
|
||||
// are the real test.
|
||||
|
||||
const raw = gunzipSync(readFileSync(new URL('../../../public/dictionaries/zh/words.txt.gz', import.meta.url)))
|
||||
const seg = buildSegmenter(raw.toString('utf8'))
|
||||
|
||||
const flagged = (text: string) => hanziFindings(text, seg).map((f) => `${f.original}→${f.replacement}`)
|
||||
|
||||
describe('the gate that admits a rule', () => {
|
||||
// The pack's own claim about itself, checked against the shipped dictionary
|
||||
// rather than asserted in a comment. A pair whose wrong form is a real word
|
||||
// cannot be decided mechanically and does not belong here.
|
||||
it('every wrong form is not a word, and every right form is', () => {
|
||||
for (const { wrong, right } of CONFUSION_PAIRS) {
|
||||
expect(seg.has(wrong), `${wrong} is a dictionary word and must not be flagged`).toBe(false)
|
||||
expect(seg.has(right), `${right} is not a dictionary word`).toBe(true)
|
||||
}
|
||||
})
|
||||
|
||||
// The errors this pack deliberately refuses, and why — each is a genuine
|
||||
// mistake by a modern standard whose wrong form is itself a headword. If a
|
||||
// dictionary rebuild ever drops one of these, this test fails and the pair
|
||||
// becomes admissible; that is the intended way to find out.
|
||||
it('refuses the well-known errors it cannot decide', () => {
|
||||
for (const undecidable of ['自已', '好象', '倒底', '帐号', '部份']) {
|
||||
expect(seg.has(undecidable), `${undecidable} is no longer a word — reconsider the rule`).toBe(true)
|
||||
expect(flagged(`这是${undecidable}的例子`)).toEqual([])
|
||||
}
|
||||
})
|
||||
})
|
||||
|
||||
describe('the mistakes it catches', () => {
|
||||
it('已 / 己 / 以', () => {
|
||||
expect(flagged('我己经写完了作业')).toEqual(['己经→已经'])
|
||||
expect(flagged('我以经吃过饭了')).toEqual(['以经→已经'])
|
||||
expect(flagged('下课已后我们去公园')).toEqual(['已后→以后'])
|
||||
})
|
||||
|
||||
it('在 / 再', () => {
|
||||
expect(flagged('明天在见')).toEqual(['在见→再见'])
|
||||
expect(flagged('他正再看书')).toEqual(['正再→正在'])
|
||||
expect(flagged('现再几点了')).toEqual(['现再→现在'])
|
||||
})
|
||||
|
||||
it('做 / 作', () => {
|
||||
expect(flagged('我的工做很忙')).toEqual(['工做→工作'])
|
||||
expect(flagged('老师给我们很多做业')).toEqual(['做业→作业'])
|
||||
expect(flagged('这本书的做者是谁')).toEqual(['做者→作者'])
|
||||
})
|
||||
|
||||
it('the rest', () => {
|
||||
expect(flagged('我觉的这个很好')).toEqual(['觉的→觉得'])
|
||||
expect(flagged('你因该早点睡')).toEqual(['因该→应该'])
|
||||
expect(flagged('即然你来了就坐下吧')).toEqual(['即然→既然'])
|
||||
expect(flagged('你知到吗')).toEqual(['知到→知道'])
|
||||
expect(flagged('请输入你的蜜码')).toEqual(['蜜码→密码'])
|
||||
})
|
||||
|
||||
it('reports an exact span, so the card replaces the right characters', () => {
|
||||
const text = '我己经到了'
|
||||
const [f] = hanziFindings(text, seg)
|
||||
expect(text.slice(f.from, f.to)).toBe('己经')
|
||||
expect(text.slice(0, f.from) + f.replacement + text.slice(f.to)).toBe('我已经到了')
|
||||
})
|
||||
|
||||
it('finds every occurrence, in document order', () => {
|
||||
expect(flagged('我己经吃了，他也己经吃了')).toEqual(['己经→已经', '己经→已经'])
|
||||
expect(flagged('我的工做很忙，所以我觉的很累')).toEqual(['工做→工作', '觉的→觉得'])
|
||||
})
|
||||
})
|
||||
|
||||
// ── the direction that matters ──────────────────────────────────────────────
|
||||
|
||||
describe('the correct writing it must not touch', () => {
|
||||
// Each of these is an ordinary sentence containing a flagged substring across
|
||||
// a word boundary. Without the boundary gate, every one would be corrupted —
|
||||
// and corrupted silently, into text that is still made of real characters.
|
||||
it('leaves two real words alone where they happen to abut', () => {
|
||||
// 自己 + 经常. The substring is 己经.
|
||||
expect(flagged('他自己经常做饭')).toEqual([])
|
||||
// 睡觉 + 的. The substring is 觉的.
|
||||
expect(flagged('睡觉的时候不要看手机')).toEqual([])
|
||||
// 感觉 + 的.
|
||||
expect(flagged('这是我感觉的方向')).toEqual([])
|
||||
// 不知 + 到底.
|
||||
expect(flagged('我不知到底该怎么办')).toEqual([])
|
||||
// 因 + 位置.
|
||||
expect(flagged('因位置不好我们换了座位')).toEqual([])
|
||||
// 已 + 后悔.
|
||||
expect(flagged('他已后悔了')).toEqual([])
|
||||
})
|
||||
|
||||
it('leaves ordinary correct prose entirely alone', () => {
|
||||
for (const good of [
|
||||
'我今天早上去公园跑步了',
|
||||
'他的中文说得很好',
|
||||
'我已经完成了我的作业',
|
||||
'现在几点了，我们再见面吧',
|
||||
'我觉得这个工作很有意思',
|
||||
'既然你已经知道了，就按照计划做',
|
||||
]) {
|
||||
expect(flagged(good), good).toEqual([])
|
||||
}
|
||||
})
|
||||
|
||||
// Where the gate costs the pack a real catch, and the trade it is making.
|
||||
// 不知 is itself a word, so 我不知到他在哪里 — which really is 知到 for 知道 —
|
||||
// reads to the segmenter as 不知 + 到 and is left alone. That is the gate
|
||||
// preferring a missed error to a corrupted sentence, which is the whole
|
||||
// premise: 我不知到底该怎么办 is the same three characters and is correct.
|
||||
it('declines a real error rather than risk the sentence beside it', () => {
|
||||
expect(flagged('我不知到他在哪里')).toEqual([])
|
||||
expect(flagged('你知到吗')).toEqual(['知到→知道'])
|
||||
})
|
||||
|
||||
it('says nothing about English, or about nothing', () => {
|
||||
expect(flagged('I already finished my homework')).toEqual([])
|
||||
expect(flagged('')).toEqual([])
|
||||
})
|
||||
|
||||
// The direction gate. The word list is loaded only for an account learning
|
||||
// Chinese, so without one this pack is silent — a writer practising English
|
||||
// must never be told her own quoted Chinese is wrong.
|
||||
it('is silent without a segmenter, which is how the direction gate works', () => {
|
||||
expect(hanziFindings('我己经写完了', null)).toEqual([])
|
||||
})
|
||||
})
|
||||
@@ -0,0 +1,149 @@
|
||||
import type { MechanicsFinding } from '../../api/client'
|
||||
import type { Segmenter } from '../../lib/segment'
|
||||
|
||||
// 错别字 — wrong-character detection, the Chinese counterpart of the spell
|
||||
// checker, and a different problem from the one Hunspell solves.
|
||||
//
|
||||
// Chinese has no misspellings in the English sense: every character a writer can
|
||||
// type is a real character, correctly formed, and an IME will not offer one that
|
||||
// is not. What it *will* offer is the wrong one. Typing pinyin `yijing` and
|
||||
// taking the first candidate gives 已经 or 己经 depending on the moment, and both
|
||||
// are made of real characters. So the unit of error is not a malformed word but
|
||||
// a **substituted character inside a correct-looking one** — which is why this
|
||||
// is a rule pack over confusable pairs rather than a dictionary membership test.
|
||||
//
|
||||
// The discipline is Phase 22's, and the bar is the same: **precision over
|
||||
// recall**. A wrong nudge costs more trust than a missed one earns, and it costs
|
||||
// double here, because a learner has no way to know the tool is wrong. Two
|
||||
// mechanical gates enforce it, and both are checked in the tests rather than
|
||||
// asserted in prose.
|
||||
|
||||
// A confusable pair: `wrong` is never a word, `right` is what was meant.
|
||||
//
|
||||
// **Gate one — the pair must be decidable by the dictionary.** Each entry is
|
||||
// admitted only if `wrong` is absent from the 188k-word list *and* `right` is
|
||||
// present. That is what makes the correction a fact rather than a preference,
|
||||
// and it is checked against the shipped asset in hanzi.test.ts.
|
||||
//
|
||||
// It is also the gate that keeps out errors everyone knows are errors. 自已 for
|
||||
// 自己 is among the commonest slips in written Chinese, and 自已 is itself a
|
||||
// dictionary headword — so this pack does not flag it, exactly as Phase 22's
|
||||
// English pack left out `married with`. The same fate for 好象 (an older form of
|
||||
// 好像, still in the dictionary), 倒底, 帐号 and 部份: all real errors by a modern
|
||||
// standard, none of them decidable here.
|
||||
interface Confusion {
|
||||
wrong: string
|
||||
right: string
|
||||
// The note on the card. English, because this pack only ever runs for a writer
|
||||
// whose English is the language they think in — see the direction gate below.
|
||||
why: string
|
||||
}
|
||||
|
||||
const CONFUSIONS: Confusion[] = [
|
||||
// 已 / 己 / 以 — three characters that differ by one stroke and share a
|
||||
// syllable. The most productive source of 错别字 there is.
|
||||
{ wrong: '己经', right: '已经', why: '已经 (already) — 己 is the "self" character; the one you want is 已.' },
|
||||
{ wrong: '以经', right: '已经', why: '已经 (already) — 以 is a different word; 已 is the one that means "already".' },
|
||||
{ wrong: '已后', right: '以后', why: '以后 (afterwards) takes 以, not 已.' },
|
||||
|
||||
// 在 / 再 — same pinyin (zài), completely different jobs: one is location and
|
||||
// ongoing action, the other is repetition.
|
||||
{ wrong: '在见', right: '再见', why: '再见 (goodbye) — 再 is "again", which is what "see you again" needs.' },
|
||||
{ wrong: '正再', right: '正在', why: '正在 (in the middle of doing) takes 在, the one about being somewhere.' },
|
||||
{ wrong: '现再', right: '现在', why: '现在 (now) takes 在.' },
|
||||
|
||||
// 做 / 作 — both zuò, both "to do", and which one a compound takes is simply
|
||||
// fixed by convention. A learner cannot reason it out, which is what makes a
|
||||
// reminder worth having.
|
||||
{ wrong: '工做', right: '工作', why: '工作 (work) is written with 作.' },
|
||||
{ wrong: '做业', right: '作业', why: '作业 (homework) is written with 作.' },
|
||||
{ wrong: '做者', right: '作者', why: '作者 (author) is written with 作.' },
|
||||
{ wrong: '做文', right: '作文', why: '作文 (an essay) is written with 作.' },
|
||||
{ wrong: '做用', right: '作用', why: '作用 (effect, function) is written with 作.' },
|
||||
|
||||
// 得 / 的 — the pair everyone knows about. Only the fixed compound is flagged:
|
||||
// deciding 的 against 地 against 得 in the general case needs to know whether
|
||||
// the next word is a verb or a noun, which nothing here can tell.
|
||||
{ wrong: '觉的', right: '觉得', why: '觉得 (to feel, to think) ends in 得.' },
|
||||
|
||||
// 即 / 既 — one stroke apart, opposite meanings ("namely" against "since").
|
||||
{ wrong: '即然', right: '既然', why: '既然 (since, given that) takes 既.' },
|
||||
{ wrong: '既使', right: '即使', why: '即使 (even if) takes 即.' },
|
||||
|
||||
// The rest: ordinary IME slips where the wrong character is a homophone.
|
||||
{ wrong: '因该', right: '应该', why: '应该 (should) — 因 means "because"; the word you want starts with 应.' },
|
||||
{ wrong: '因位', right: '因为', why: '因为 (because) ends in 为.' },
|
||||
{ wrong: '知到', right: '知道', why: '知道 (to know) ends in 道.' },
|
||||
{ wrong: '安照', right: '按照', why: '按照 (according to) takes 按.' },
|
||||
{ wrong: '蜜码', right: '密码', why: '密码 (password) takes 密 — 蜜 is honey.' },
|
||||
{ wrong: '犹其', right: '尤其', why: '尤其 (especially) takes 尤.' },
|
||||
{ wrong: '甘净', right: '干净', why: '干净 (clean) takes 干.' },
|
||||
{ wrong: '什末', right: '什么', why: '什么 (what) ends in 么.' },
|
||||
{ wrong: '一像', right: '一样', why: '一样 (the same) ends in 样 — 像 is "to resemble".' },
|
||||
{ wrong: '必须品', right: '必需品', why: '必需品 (a necessity) takes 需. 必须 is "must", which is a different word.' },
|
||||
]
|
||||
|
||||
// **Gate two — the characters must not already belong to two different words.**
|
||||
//
|
||||
// This is the gate that stops the pack from destroying correct writing, and
|
||||
// without it every rule above is dangerous. 自己经常 ("oneself, often") contains
|
||||
// the string 己经. 睡觉的时候 ("when sleeping") contains 觉的. 不知到底 contains 知到.
|
||||
// A substring match would corrupt all three.
|
||||
//
|
||||
// The segmenter already knows the difference, so the test is: split the text,
|
||||
// and if the two characters land in different tokens *and* either token is a
|
||||
// real multi-character word, this is a word boundary and not an error. Two
|
||||
// adjacent single-character tokens is what the walk produces when it has nothing
|
||||
// better to offer — which is exactly what a mistyped compound looks like.
|
||||
function isWordBoundary(tokens: { word: string; from: number; to: number }[], at: number): boolean {
|
||||
const left = tokens.find((t) => at >= t.from && at < t.to)
|
||||
const right = tokens.find((t) => at + 1 >= t.from && at + 1 < t.to)
|
||||
if (!left || !right || left === right) return false
|
||||
return left.word.length > 1 || right.word.length > 1
|
||||
}
|
||||
|
||||
// hanziFindings returns the 错别字 in a piece of text, as ordinary mechanics
|
||||
// findings — the same shape, the same rail, the same cards, the same accept.
|
||||
//
|
||||
// It needs the segmenter and does nothing without one, which is also the
|
||||
// direction gate: the word list is loaded only for an account learning Chinese
|
||||
// (useSegmenter), so a writer practising English can never be told her quoted
|
||||
// Chinese is wrong. That is not a nicety. Petal deliberately never corrects the
|
||||
// pair language — the fr and es dictionaries are chosen to hold every variety
|
||||
// precisely so they cannot underline correct writing — and a Mandarin native
|
||||
// does not need her own language checked by a rule pack of two dozen entries.
|
||||
export function hanziFindings(text: string, segmenter: Segmenter | null): MechanicsFinding[] {
|
||||
if (!segmenter || !text) return []
|
||||
// One segmentation for the whole text, shared by every rule. The walk is
|
||||
// linear, but running it two dozen times over a long document would not be.
|
||||
const tokens = segmenter.segment(text)
|
||||
const found: MechanicsFinding[] = []
|
||||
|
||||
for (const c of CONFUSIONS) {
|
||||
let from = text.indexOf(c.wrong)
|
||||
while (from !== -1) {
|
||||
// The boundary test is asked at the seam the substitution sits on: the
|
||||
// gap between the first two characters, which is where a mistyped
|
||||
// compound and two adjacent words look different from each other.
|
||||
if (!isWordBoundary(tokens, from)) {
|
||||
found.push({
|
||||
from,
|
||||
to: from + c.wrong.length,
|
||||
original: c.wrong,
|
||||
replacement: c.right,
|
||||
explanation: c.why,
|
||||
type: 'mechanics',
|
||||
})
|
||||
}
|
||||
from = text.indexOf(c.wrong, from + 1)
|
||||
}
|
||||
}
|
||||
|
||||
// Document order, so the rail reads down the page rather than down this file.
|
||||
return found.sort((a, b) => a.from - b.from)
|
||||
}
|
||||
|
||||
// Exported for the tests, which check every pair against the shipped word list.
|
||||
// A pack whose own gate is only described in a comment is a pack whose gate can
|
||||
// rot; this is how the description is made to stay true.
|
||||
export const CONFUSION_PAIRS = CONFUSIONS.map((c) => ({ wrong: c.wrong, right: c.right }))
|
||||
@@ -20,6 +20,11 @@ interface Props {
|
||||
// The signed-in writer, when there is real auth to sign out of. Null in a
|
||||
// local-dev build, where there is nothing to leave.
|
||||
account: { name: string } | null
|
||||
// The account's learner direction and the way to change it, passed straight
|
||||
// through to the language picker in the footer — the sidebar is the drawer,
|
||||
// and the drawer is the only chrome always one tap away on a phone.
|
||||
direction?: string
|
||||
onDirection?: (direction: string) => Promise<void>
|
||||
}
|
||||
|
||||
// Sidebar sort orders. 'recent' keeps the server's updated_at-desc ordering.
|
||||
@@ -43,6 +48,8 @@ export function DocList({
|
||||
onToggleTag,
|
||||
onCreateTag,
|
||||
account,
|
||||
direction,
|
||||
onDirection,
|
||||
}: Props) {
|
||||
const t = usePack()
|
||||
// Active tag filter (null = show all). Cleared automatically if the tag
|
||||
@@ -161,7 +168,7 @@ export function DocList({
|
||||
{/* The pair Petal speaks. Unlike the rows above it this is not about any
|
||||
document, and unlike sign-out it is offered whether or not there is an
|
||||
account behind the session — a local-dev build still has a langpack. */}
|
||||
<LanguagePicker />
|
||||
<LanguagePicker direction={direction} onDirection={onDirection} />
|
||||
|
||||
{/* Who's writing, and the way out. Shown only when there's a real account
|
||||
behind the session — a local-dev build has nobody to sign out as. */}
|
||||
|
||||
@@ -15,15 +15,46 @@ import { setPackLang, shippedPacks, usePack } from '../../i18n'
|
||||
// read a label that says "Portuguese" in Chinese, so the buttons say 中文 and
|
||||
// Português and nothing else — the one place in Petal where bilingual copy would
|
||||
// actively get in the way.
|
||||
export function LanguagePicker() {
|
||||
interface Props {
|
||||
// The account's current direction ('learning_en' | 'learning_pair'), and the
|
||||
// way to change it. Owned by App rather than here, because turning the pair
|
||||
// around changes what the *editor* does — it is what loads the word list —
|
||||
// and this control is only where the writer says so.
|
||||
direction?: string
|
||||
onDirection?: (direction: string) => Promise<void>
|
||||
}
|
||||
|
||||
export function LanguagePicker({ direction, onDirection }: Props = {}) {
|
||||
const t = usePack()
|
||||
const packs = shippedPacks()
|
||||
const [saving, setSaving] = useState<string | null>(null)
|
||||
const [failed, setFailed] = useState(false)
|
||||
const [turning, setTurning] = useState(false)
|
||||
const [turnFailed, setTurnFailed] = useState(false)
|
||||
|
||||
// Nothing to choose between — a deployment with one pack shows no picker
|
||||
// rather than a single button that does nothing.
|
||||
if (packs.length < 2) return null
|
||||
// rather than a single button that does nothing. The direction control is
|
||||
// still worth rendering in that case, so it is checked separately below.
|
||||
const showPacks = packs.length >= 2
|
||||
// `t.learner` is the pack's own statement that this pair can be learned
|
||||
// toward, and the server keeps the matching list (auth.learnerPairs). A pack
|
||||
// without it renders nothing here, which is the same failure mode as a pair
|
||||
// without copy: absent rather than broken.
|
||||
const learner = t.learner
|
||||
if (!showPacks && !learner) return null
|
||||
|
||||
const turn = async (next: string) => {
|
||||
if (!onDirection || next === (direction ?? 'learning_en') || turning) return
|
||||
setTurning(true)
|
||||
setTurnFailed(false)
|
||||
try {
|
||||
await onDirection(next)
|
||||
} catch {
|
||||
setTurnFailed(true)
|
||||
} finally {
|
||||
setTurning(false)
|
||||
}
|
||||
}
|
||||
|
||||
const choose = async (code: string) => {
|
||||
if (code === t.code || saving) return
|
||||
@@ -47,6 +78,8 @@ export function LanguagePicker() {
|
||||
|
||||
return (
|
||||
<div className="flex flex-col gap-1 px-1">
|
||||
{showPacks && (
|
||||
<>
|
||||
{/* Label and buttons wrap as a pair: the label is itself bilingual
|
||||
("Langue · Language"), and three self-naming buttons beside it need
|
||||
more than the drawer is wide in every language Petal ships. When they
|
||||
@@ -89,6 +122,52 @@ export function LanguagePicker() {
|
||||
{t.docs.languageFailed}
|
||||
</span>
|
||||
)}
|
||||
</>
|
||||
)}
|
||||
|
||||
{/* Which way round the pair is being learned. Below the language buttons
|
||||
because it only makes sense once the language is settled, and rendered
|
||||
at all only for a pair Petal has the learner-side data for. */}
|
||||
{learner && onDirection && (
|
||||
<div
|
||||
className="flex flex-wrap items-center gap-x-2 gap-y-1 text-xs"
|
||||
style={{ color: 'var(--color-muted)' }}
|
||||
>
|
||||
<span className="shrink-0 font-semibold">{learner.label}</span>
|
||||
<div className="ml-auto flex shrink-0 gap-1">
|
||||
{[
|
||||
{ code: 'learning_en', text: learner.toEn, en: `learning English` },
|
||||
{ code: 'learning_pair', text: learner.toPair, en: `learning ${t.nativeName}` },
|
||||
].map((opt) => {
|
||||
const active = (direction ?? 'learning_en') === opt.code
|
||||
return (
|
||||
<button
|
||||
key={opt.code}
|
||||
type="button"
|
||||
onClick={() => void turn(opt.code)}
|
||||
disabled={turning}
|
||||
aria-pressed={active}
|
||||
aria-label={`I am ${opt.en}`}
|
||||
className="petal-tap-sm px-2.5 py-1 text-xs font-bold transition-colors disabled:opacity-60"
|
||||
style={{
|
||||
borderRadius: 'var(--radius-pill)',
|
||||
background: active ? 'var(--color-accent)' : 'var(--color-surface)',
|
||||
color: active ? '#fff' : 'var(--color-plum)',
|
||||
boxShadow: active ? 'none' : 'var(--shadow-soft)',
|
||||
}}
|
||||
>
|
||||
{opt.text}
|
||||
</button>
|
||||
)
|
||||
})}
|
||||
</div>
|
||||
</div>
|
||||
)}
|
||||
{turnFailed && learner && (
|
||||
<span className="text-[0.7rem]" style={{ color: 'var(--color-accent)' }}>
|
||||
{learner.failed}
|
||||
</span>
|
||||
)}
|
||||
</div>
|
||||
)
|
||||
}
|
||||
|
||||
@@ -34,6 +34,8 @@ import { planBatch } from './acceptBatch'
|
||||
import { api, type Suggestion, type SuggestionType, type WordInfo } from '../../api/client'
|
||||
import { speak, speechSupported } from '../../audio/speech'
|
||||
import type { SpellChecker } from '../../hooks/useSpellChecker'
|
||||
import type { Segmenter } from '../../lib/segment'
|
||||
import { hanziWordAt, hanziToWordInfo, hanziPinyin } from './hanziWord'
|
||||
import { usePack } from '../../i18n'
|
||||
|
||||
// Breathing room left below the last suggestion card when the rail's stack is what
|
||||
@@ -73,6 +75,11 @@ interface Props {
|
||||
// to the personal dictionary is bubbled up so it persists app-wide.
|
||||
spellChecker: SpellChecker | null
|
||||
onAddWord: (word: string) => void
|
||||
// The Chinese word list, non-null only for a writer learning the pair
|
||||
// language (users.direction = 'learning_pair'). Its presence is what turns on
|
||||
// every Chinese-side behaviour here: hanzi stops being text the editor steps
|
||||
// over and becomes words it can point at.
|
||||
segmenter: Segmenter | null
|
||||
}
|
||||
|
||||
interface MisspellState {
|
||||
@@ -95,6 +102,12 @@ interface WordInfoState {
|
||||
left: number
|
||||
loading: boolean
|
||||
info: WordInfo | null
|
||||
// The word's own pinyin, for a Chinese lookup. Kept beside `info` rather than
|
||||
// inside it because WordInfo is the English dictionary's shape and `phonetic`
|
||||
// there means IPA — printing pinyin between the slashes that say "this is
|
||||
// IPA" would be a small lie in the one place a learner is looking for the
|
||||
// truth about pronunciation.
|
||||
pinyin: string
|
||||
// Garden state: the captured word's id (null until the auto-capture returns or
|
||||
// after it's removed) and whether it's currently in the garden.
|
||||
vocabId: string | null
|
||||
@@ -188,6 +201,10 @@ interface GlossState {
|
||||
gloss: string
|
||||
// The other reading, when the token is a word in her language too.
|
||||
reverse?: string
|
||||
// A line shown *above* the meaning rather than below it: pinyin, for a
|
||||
// Chinese word. Above because it is read first — the meaning of 公园 may
|
||||
// already be clear to someone who cannot yet say it.
|
||||
lead?: string
|
||||
from: number
|
||||
to: number
|
||||
top: number
|
||||
@@ -234,6 +251,7 @@ export function EditorCore({
|
||||
onFocusMode,
|
||||
spellChecker,
|
||||
onAddWord,
|
||||
segmenter,
|
||||
}: Props) {
|
||||
// Her pair's copy — the hover tip labels the second reading with the language's
|
||||
// own name, so it says "português" rather than "pt-PT".
|
||||
@@ -421,6 +439,26 @@ export function EditorCore({
|
||||
// popover would offer a definition of "cora".
|
||||
const wordAlphabet = spellChecker?.extendedAlphabet ?? false
|
||||
|
||||
// "The word under here", for a document that may hold two writing systems at
|
||||
// once — which every document in this pair does, because a learner's Chinese
|
||||
// practice is full of English and her English is full of quoted Chinese.
|
||||
//
|
||||
// Chinese is tried first and Latin second, and the order costs nothing to get
|
||||
// right: the two can never both answer, because a Han character is not a Latin
|
||||
// letter and neither tokenizer will cross into the other's run. `hanzi` rides
|
||||
// along because the two answers go to different dictionaries — the same
|
||||
// string is a word in exactly one of them.
|
||||
const resolveWord = useCallback(
|
||||
(pos: number): { from: number; to: number; word: string; hanzi: boolean } | null => {
|
||||
if (!editor) return null
|
||||
const han = hanziWordAt(editor.state.doc, pos, segmenter)
|
||||
if (han) return { ...han, hanzi: true }
|
||||
const latin = wordAt(editor.state.doc, pos, wordAlphabet)
|
||||
return latin ? { ...latin, hanzi: false } : null
|
||||
},
|
||||
[editor, segmenter, wordAlphabet],
|
||||
)
|
||||
|
||||
// Push the spell checker into its decoration plugin once the dictionary loads
|
||||
// (and again whenever the personal dictionary changes its identity).
|
||||
useEffect(() => {
|
||||
@@ -833,7 +871,7 @@ export function EditorCore({
|
||||
const openWordLookup = useCallback(
|
||||
(pos: number) => {
|
||||
if (!editor) return
|
||||
const range = wordAt(editor.state.doc, pos, wordAlphabet)
|
||||
const range = resolveWord(pos)
|
||||
if (!range) return
|
||||
const wrapper = wrapperRef.current
|
||||
if (!wrapper) return
|
||||
@@ -849,12 +887,18 @@ export function EditorCore({
|
||||
closeCard()
|
||||
setMisspell(null)
|
||||
const token = ++wordReqRef.current
|
||||
setWordInfo({ word: range.word, from: range.from, to: range.to, top, left, loading: true, info: null, vocabId: null, saved: false })
|
||||
setWordInfo({ word: range.word, from: range.from, to: range.to, top, left, loading: true, info: null, pinyin: '', vocabId: null, saved: false })
|
||||
// The sentence the word sits in, for review context in the garden.
|
||||
const example = exampleAt(range.from)
|
||||
api
|
||||
.lookupWord(range.word)
|
||||
.then((info) => {
|
||||
// Two dictionaries, one card. The Chinese lookup answers in English and
|
||||
// the English one answers in her language; which is wanted follows from
|
||||
// which script the word is written in, so nothing here has to consult the
|
||||
// account's direction a second time.
|
||||
const lookup: Promise<{ info: WordInfo; pinyin: string }> = range.hanzi
|
||||
? api.hanziWord(range.word).then((h) => ({ info: hanziToWordInfo(h), pinyin: hanziPinyin(h) }))
|
||||
: api.lookupWord(range.word).then((info) => ({ info, pinyin: '' }))
|
||||
lookup
|
||||
.then(({ info, pinyin }) => {
|
||||
if (token !== wordReqRef.current) return
|
||||
// Auto-capture into the vocabulary garden — only words the dictionary
|
||||
// actually knows (a real gloss or definition), so accidental lookups of
|
||||
@@ -864,14 +908,18 @@ export function EditorCore({
|
||||
// Reflect the saved state optimistically so the heart shows 💚 the
|
||||
// moment a known word loads, rather than flashing 🤍 until the capture
|
||||
// round-trips. vocabId is filled in when recordVocab returns.
|
||||
setWordInfo((w) => (w ? { ...w, loading: false, info, saved: known } : null))
|
||||
setWordInfo((w) => (w ? { ...w, loading: false, info, pinyin, saved: known } : null))
|
||||
if (!known) return
|
||||
api
|
||||
.recordVocab({
|
||||
word: range.word,
|
||||
gloss: info.gloss,
|
||||
definition: info.definitions[0]?.definition ?? '',
|
||||
phonetic: info.phonetic,
|
||||
// The garden's pronunciation field holds whichever this word has:
|
||||
// IPA for an English word, pinyin for a Chinese one. Both answer
|
||||
// the same question on a review card — how do I say this — and a
|
||||
// second column would only be a second thing to keep in sync.
|
||||
phonetic: pinyin || info.phonetic,
|
||||
example,
|
||||
doc_id: docId,
|
||||
})
|
||||
@@ -891,7 +939,7 @@ export function EditorCore({
|
||||
}
|
||||
})
|
||||
},
|
||||
[editor, closeCard, docId],
|
||||
[editor, closeCard, docId, resolveWord, exampleAt],
|
||||
)
|
||||
|
||||
// Toggle a looked-up word in/out of the vocabulary garden from the WordCard
|
||||
@@ -998,7 +1046,7 @@ export function EditorCore({
|
||||
clear()
|
||||
return
|
||||
}
|
||||
const range = wordAt(editor.state.doc, coords.pos, wordAlphabet)
|
||||
const range = resolveWord(coords.pos)
|
||||
if (!range) {
|
||||
clear()
|
||||
return
|
||||
@@ -1007,9 +1055,21 @@ export function EditorCore({
|
||||
if (gloss && gloss.from === range.from && gloss.to === range.to) return
|
||||
clearTimeout(glossTimer.current)
|
||||
const token = ++glossReqRef.current
|
||||
// The Chinese hover carries a second line the English one has no use for:
|
||||
// pinyin above the meaning. It is the thing a learner most often stops to
|
||||
// ask about their own writing — reading a character back is not the same
|
||||
// as being able to say it — and it is why this tooltip is worth having at
|
||||
// all for a script the writer can already read the meaning of half the
|
||||
// time.
|
||||
const ask = (): Promise<{ gloss: string; reverse?: string; lead?: string }> =>
|
||||
range.hanzi
|
||||
? api.hanziWord(range.word).then((h) => ({
|
||||
gloss: h.readings[0]?.senses ?? h.chars.map((c) => `${c.char} ${c.senses}`).join(' · '),
|
||||
lead: hanziPinyin(h),
|
||||
}))
|
||||
: api.glossWord(range.word).then((g) => ({ gloss: g.gloss, reverse: g.reverse }))
|
||||
glossTimer.current = setTimeout(() => {
|
||||
api
|
||||
.glossWord(range.word)
|
||||
ask()
|
||||
.then((g) => {
|
||||
if (token !== glossReqRef.current) return
|
||||
const wrapper = wrapperRef.current
|
||||
@@ -1024,14 +1084,14 @@ export function EditorCore({
|
||||
const wrapRect = wrapper.getBoundingClientRect()
|
||||
const left = Math.max(0, Math.min(start.left - wrapRect.left, wrapper.clientWidth - 280))
|
||||
const top = end.bottom - wrapRect.top + 6
|
||||
setGloss({ word: range.word, gloss: g.gloss, reverse: g.reverse, from: range.from, to: range.to, top, left })
|
||||
setGloss({ word: range.word, gloss: g.gloss, reverse: g.reverse, lead: g.lead, from: range.from, to: range.to, top, left })
|
||||
})
|
||||
.catch(() => {
|
||||
if (token === glossReqRef.current) setGloss(null)
|
||||
})
|
||||
}, 350)
|
||||
},
|
||||
[editor, wordAlphabet, selection, rewrite, misspell, wordInfo, pinned, gloss],
|
||||
[editor, resolveWord, selection, rewrite, misspell, wordInfo, pinned, gloss],
|
||||
)
|
||||
|
||||
// Leaving the editor surface drops any pending/shown gloss.
|
||||
@@ -1255,6 +1315,7 @@ export function EditorCore({
|
||||
{gloss && (
|
||||
<GlossTip
|
||||
gloss={gloss.gloss}
|
||||
lead={gloss.lead}
|
||||
reverse={gloss.reverse}
|
||||
reverseLang={pack.nativeName}
|
||||
style={{ top: gloss.top, left: gloss.left }}
|
||||
@@ -1287,6 +1348,7 @@ export function EditorCore({
|
||||
loading={wordInfo.loading}
|
||||
saved={wordInfo.saved}
|
||||
onToggleSave={toggleSaveWord}
|
||||
pinyin={wordInfo.pinyin}
|
||||
style={{ top: wordInfo.top, left: wordInfo.left }}
|
||||
onReplace={replaceWord}
|
||||
/>
|
||||
|
||||
@@ -7,6 +7,11 @@
|
||||
|
||||
interface Props {
|
||||
gloss: string
|
||||
// A line above the gloss, in a lighter weight: the pinyin of a Chinese word.
|
||||
// It leads because it is what is actually being asked — a learner reading
|
||||
// their own 公园 back may know it means a park and still not know how to say
|
||||
// it, which is the one thing the character does not tell them.
|
||||
lead?: string
|
||||
// The English meaning of the same token read as a word of the writer's own
|
||||
// language, when it is one. On a Latin-script pair "sale" is both, and the
|
||||
// bubble shows the two readings stacked rather than picking one — the same
|
||||
@@ -17,7 +22,7 @@ interface Props {
|
||||
style: React.CSSProperties
|
||||
}
|
||||
|
||||
export function GlossTip({ gloss, reverse, reverseLang, style }: Props) {
|
||||
export function GlossTip({ gloss, lead, reverse, reverseLang, style }: Props) {
|
||||
return (
|
||||
<div
|
||||
className="petal-gloss-tip pointer-events-none absolute z-20 px-2.5 py-1.5 text-sm"
|
||||
@@ -33,6 +38,11 @@ export function GlossTip({ gloss, reverse, reverseLang, style }: Props) {
|
||||
...style,
|
||||
}}
|
||||
>
|
||||
{lead && (
|
||||
<span className="mb-0.5 block font-semibold" style={{ opacity: 0.9 }}>
|
||||
{lead}
|
||||
</span>
|
||||
)}
|
||||
{gloss}
|
||||
{reverse && (
|
||||
<span className="mt-0.5 block" style={{ opacity: 0.72, fontSize: '0.85em' }}>
|
||||
|
||||
@@ -17,11 +17,16 @@ interface Props {
|
||||
// heart toggles it; `onToggleSave` removes/re-adds it.
|
||||
saved: boolean
|
||||
onToggleSave: () => void
|
||||
// A Chinese word's pinyin. Shown in place of the IPA line and *without* the
|
||||
// slashes, because pinyin is not a phonetic transcription — it is how the word
|
||||
// is spelled in letters, and the slashes would say something untrue about it
|
||||
// in the one place a learner is looking for the truth about pronunciation.
|
||||
pinyin?: string
|
||||
style: React.CSSProperties
|
||||
onReplace: (synonym: string) => void
|
||||
}
|
||||
|
||||
export function WordCard({ word, info, loading, saved, onToggleSave, style, onReplace }: Props) {
|
||||
export function WordCard({ word, info, loading, saved, onToggleSave, pinyin, style, onReplace }: Props) {
|
||||
const t = usePack()
|
||||
const definitions = info?.definitions ?? []
|
||||
const synonyms = info?.synonyms ?? []
|
||||
@@ -117,9 +122,10 @@ export function WordCard({ word, info, loading, saved, onToggleSave, style, onRe
|
||||
when she has found a word she likes — "can I use this?". Both are
|
||||
quiet, muted lines: information she can take or leave, never a verdict
|
||||
on her writing. */}
|
||||
{(phonetic || band) && (
|
||||
{(phonetic || pinyin || band) && (
|
||||
<div className="mt-1.5 flex items-center gap-2 text-sm">
|
||||
{phonetic && <span style={{ color: 'var(--color-muted)' }}>/{phonetic}/</span>}
|
||||
{pinyin && <span style={{ color: 'var(--color-muted)' }}>{pinyin}</span>}
|
||||
{!pinyin && phonetic && <span style={{ color: 'var(--color-muted)' }}>/{phonetic}/</span>}
|
||||
{band && (
|
||||
<span
|
||||
className="rounded-full px-2 py-0.5 text-xs font-semibold"
|
||||
|
||||
@@ -0,0 +1,126 @@
|
||||
import type { Node as PMNode } from '@tiptap/pm/model'
|
||||
|
||||
import { mapOffset } from './SuggestionHighlight'
|
||||
import type { Segmenter } from '../../lib/segment'
|
||||
import type { HanziInfo, WordInfo } from '../../api/client'
|
||||
|
||||
// The Chinese counterpart of `wordAt` (SpellCheck.ts): given a position in the
|
||||
// document, which Chinese word is there.
|
||||
//
|
||||
// It lives in its own file rather than as a branch inside `wordAt` because the
|
||||
// two answer the same question by genuinely different means — one runs a regex
|
||||
// over the text, the other runs a shortest-path walk over a 188k-word list it
|
||||
// had to fetch — and only one of them is about spelling at all. What they share
|
||||
// is the part that matters for correctness: the offset→position mapping, which
|
||||
// is `mapOffset`, the same function the suggestion, spell and search decoration
|
||||
// layers all anchor through.
|
||||
|
||||
export interface HanziRange {
|
||||
from: number
|
||||
to: number
|
||||
word: string
|
||||
}
|
||||
|
||||
// blockAt finds the textblock containing pos, along with where that block starts
|
||||
// — everything else here is arithmetic within one block.
|
||||
//
|
||||
// Segmentation is per-block for the same reason the spell tokenizer is: a word
|
||||
// cannot span a paragraph break, and a block is the largest unit whose text is
|
||||
// contiguous in the document.
|
||||
function blockAt(doc: PMNode, pos: number): { node: PMNode; start: number } | null {
|
||||
let found: { node: PMNode; start: number } | null = null
|
||||
doc.descendants((node, nodePos) => {
|
||||
if (found) return false
|
||||
if (!node.isTextblock) return true
|
||||
if (pos <= nodePos || pos >= nodePos + node.nodeSize) return false
|
||||
found = { node, start: nodePos }
|
||||
return false
|
||||
})
|
||||
return found
|
||||
}
|
||||
|
||||
// offsetOf is the inverse of mapOffset: an absolute ProseMirror position to a
|
||||
// character offset within the block's flattened text. Inline atoms (a hard
|
||||
// break) occupy a position and contribute no text, so the two are not the same
|
||||
// number and subtracting the block position would be wrong in any paragraph
|
||||
// containing one.
|
||||
function offsetOf(block: PMNode, blockStart: number, pos: number): number {
|
||||
let textOffset = 0
|
||||
let pmPos = blockStart + 1
|
||||
let result = -1
|
||||
block.forEach((child) => {
|
||||
if (result >= 0) return
|
||||
const len = child.isText ? (child.text?.length ?? 0) : 0
|
||||
if (pos <= pmPos + child.nodeSize) {
|
||||
result = textOffset + Math.max(0, Math.min(pos - pmPos, len))
|
||||
return
|
||||
}
|
||||
textOffset += len
|
||||
pmPos += child.nodeSize
|
||||
})
|
||||
return result >= 0 ? result : textOffset
|
||||
}
|
||||
|
||||
// hanziWordAt resolves the Chinese word at a document position, or null when
|
||||
// there is no Chinese there — which is the ordinary case in a mixed paragraph
|
||||
// and is why the caller falls through to the Latin tokenizer.
|
||||
export function hanziWordAt(doc: PMNode, pos: number, segmenter: Segmenter | null): HanziRange | null {
|
||||
if (!segmenter) return null
|
||||
const block = blockAt(doc, pos)
|
||||
if (!block) return null
|
||||
const text = block.node.textContent
|
||||
if (!text) return null
|
||||
|
||||
const token = segmenter.wordAt(text, offsetOf(block.node, block.start, pos))
|
||||
if (!token) return null
|
||||
return {
|
||||
from: mapOffset(block.node, block.start, token.from),
|
||||
to: mapOffset(block.node, block.start, token.to),
|
||||
word: token.word,
|
||||
}
|
||||
}
|
||||
|
||||
// hanziToWordInfo adapts a Chinese lookup into the shape the word card already
|
||||
// renders.
|
||||
//
|
||||
// An adapter rather than a second card, because everything around the card is
|
||||
// the same in both directions: it opens the same way, anchors the same way,
|
||||
// captures into the same vocabulary garden, and reads aloud through the same
|
||||
// voice — the zh pair already speaks Chinese, so 🔊 needs nothing new to say
|
||||
// 公园 out loud. What differs is only which fields carry what.
|
||||
//
|
||||
// * `definitions` holds one entry per reading, labelled with its pinyin. The
|
||||
// part-of-speech slot is where the card puts a short italic prefix, which
|
||||
// is exactly the shape a reading label wants — and a reading *is* the thing
|
||||
// that distinguishes these senses from each other (得 dé "to obtain" from 得
|
||||
// de, the complement marker).
|
||||
// * `gloss` stays empty. It means "translated into the writer's language",
|
||||
// and for a writer learning Chinese that language is English, which is what
|
||||
// the senses already are. Putting the English there too would print it
|
||||
// twice.
|
||||
// * The per-character fallback fills the same list, labelled by character, so
|
||||
// a compound with no headword still says something true about itself.
|
||||
export function hanziToWordInfo(info: HanziInfo): WordInfo {
|
||||
const definitions =
|
||||
info.readings.length > 0
|
||||
? info.readings.map((r) => ({ part_of_speech: r.pinyin, definition: r.senses }))
|
||||
: info.chars.map((c) => ({ part_of_speech: `${c.char} ${c.pinyin}`, definition: c.senses }))
|
||||
return {
|
||||
word: info.word,
|
||||
gloss: '',
|
||||
phonetic: '',
|
||||
definitions,
|
||||
synonyms: [],
|
||||
frequency: 0,
|
||||
difficulty: -1,
|
||||
etymology: '',
|
||||
}
|
||||
}
|
||||
|
||||
// hanziPinyin is the word's own pronunciation, for the line under the headword.
|
||||
// Empty when only the character fallback answered: the characters' readings are
|
||||
// not the word's reading — 不 is bù alone and bú before a fourth tone — and
|
||||
// printing them joined up would be inventing a pronunciation.
|
||||
export function hanziPinyin(info: HanziInfo): string {
|
||||
return info.readings[0]?.pinyin ?? ''
|
||||
}
|
||||
Binary file not shown.
@@ -0,0 +1,39 @@
|
||||
import { useEffect, useState } from 'react'
|
||||
|
||||
import { loadSegmenter, type Segmenter } from '../lib/segment'
|
||||
|
||||
// Loads the Chinese word list, once per session, and only for a writer who is
|
||||
// going to use it.
|
||||
//
|
||||
// Modelled on useSpellChecker, and gated harder. That hook loads for everyone,
|
||||
// because everyone's English gets spell-checked; this one loads a megabyte for
|
||||
// the one direction that needs it, and an account practising English would
|
||||
// never ask a single question of it. The gate is the writer's own setting rather
|
||||
// than a guess from their text: a Mandarin native drafting English quotes
|
||||
// Chinese in it constantly, and none of that is what this is for.
|
||||
//
|
||||
// A failure resolves to null, which every consumer already handles as "no
|
||||
// segmentation" — the Chinese hover quietly does nothing rather than the editor
|
||||
// refusing to open.
|
||||
export function useSegmenter(enabled: boolean): Segmenter | null {
|
||||
const [segmenter, setSegmenter] = useState<Segmenter | null>(null)
|
||||
|
||||
useEffect(() => {
|
||||
if (!enabled) {
|
||||
// Turning the direction back drops it. It is a megabyte of resident map
|
||||
// whose only consumer just switched off, and re-loading costs one fetch
|
||||
// that the browser cache answers.
|
||||
setSegmenter(null)
|
||||
return
|
||||
}
|
||||
let cancelled = false
|
||||
loadSegmenter().then((seg) => {
|
||||
if (!cancelled) setSegmenter(seg)
|
||||
})
|
||||
return () => {
|
||||
cancelled = true
|
||||
}
|
||||
}, [enabled])
|
||||
|
||||
return segmenter
|
||||
}
|
||||
@@ -42,5 +42,14 @@ export function useSession() {
|
||||
}
|
||||
}, [])
|
||||
|
||||
return { me, signedOut }
|
||||
// Turn the pair around. The account is the source of truth for which
|
||||
// direction the editor is in — it decides whether the word list loads at all —
|
||||
// so the state moves only once the server has agreed, and it moves to what the
|
||||
// server *stored* rather than to what was asked for.
|
||||
const setDirection = async (direction: string) => {
|
||||
const updated = await api.setDirection(direction)
|
||||
setMe(updated)
|
||||
}
|
||||
|
||||
return { me, signedOut, setDirection }
|
||||
}
|
||||
|
||||
@@ -15,6 +15,17 @@ export const zh: Pack = {
|
||||
nativeName: '中文',
|
||||
locale: 'zh-CN',
|
||||
|
||||
// The zh pair is the only one Petal can be *learned* toward, because it is the
|
||||
// only one with a word list and a Chinese→English dictionary (Phase 26). The
|
||||
// two labels are each written for the person who would pick them: she reads
|
||||
// the first, and the English speaker learning her language reads the second.
|
||||
learner: {
|
||||
label: '我在学 · I am learning',
|
||||
toEn: '英文',
|
||||
toPair: 'Chinese 中文',
|
||||
failed: '没能换成功 · Couldn’t switch — nothing changed',
|
||||
},
|
||||
|
||||
app: {
|
||||
duplicateTitle: (title) => `${title} (副本)`,
|
||||
garden: '词汇花园',
|
||||
|
||||
@@ -39,6 +39,29 @@ export interface Pack {
|
||||
// Portuguese voice anyone reaches for is Brazilian.
|
||||
locale: string
|
||||
|
||||
// Copy for turning this pair around — a writer who is native in English and
|
||||
// learning X, rather than the other way round.
|
||||
//
|
||||
// Optional, and its presence is the pack's half of the same fact
|
||||
// auth.learnerPairs holds server-side: a pair can only be learned toward if
|
||||
// Petal has a word list to segment it with and a dictionary that reads from it
|
||||
// into English. Chinese has both; the Latin pairs have neither yet, so their
|
||||
// packs simply leave this out and the control does not render.
|
||||
//
|
||||
// Each label is written in the language of the person who would *choose* it,
|
||||
// for the same reason the pair buttons name themselves: someone on the wrong
|
||||
// side of this switch cannot read the side they are trying to reach.
|
||||
learner?: {
|
||||
// The heading over the two choices.
|
||||
label: string
|
||||
// "I am practising English" — read by the writer who is native in X.
|
||||
toEn: string
|
||||
// "I am learning X" — read by the writer who is native in English.
|
||||
toPair: string
|
||||
// Shown when the server refuses the change.
|
||||
failed: string
|
||||
}
|
||||
|
||||
app: {
|
||||
// A duplicated document's title. A function, not a suffix: where the marker
|
||||
// goes is the pack's business.
|
||||
|
||||
@@ -0,0 +1,203 @@
|
||||
import { readFileSync } from 'node:fs'
|
||||
import { gunzipSync } from 'node:zlib'
|
||||
import { describe, expect, it } from 'vitest'
|
||||
|
||||
import { buildSegmenter, isHan, type Segmenter } from './segment'
|
||||
|
||||
// Segmentation is tested twice over, and the two halves check different things.
|
||||
//
|
||||
// The hand-built dictionaries below pin the *algorithm*: given these words with
|
||||
// these frequencies, this is the split, and the reason is visible in the four
|
||||
// lines above the assertion. They would pass with any word list.
|
||||
//
|
||||
// The block at the bottom pins the *shipped asset*: the real 188,522-word list
|
||||
// this app serves, on the sentences a rebuild would plausibly break. Those are
|
||||
// the cases where being wrong is invisible — the app still works, it just
|
||||
// underlines and glosses the wrong thing.
|
||||
|
||||
// A dictionary written the way the asset is: "word freq" per line.
|
||||
function dict(entries: Record<string, number>): Segmenter {
|
||||
return buildSegmenter(
|
||||
Object.entries(entries)
|
||||
.map(([w, f]) => `${w} ${f}`)
|
||||
.join('\n'),
|
||||
)
|
||||
}
|
||||
|
||||
const words = (seg: Segmenter, text: string) => seg.segment(text).map((t) => t.word)
|
||||
|
||||
describe('isHan', () => {
|
||||
it('accepts Han across the extension blocks, and nothing else', () => {
|
||||
expect(isHan('中')).toBe(true)
|
||||
expect(isHan('龥')).toBe(true)
|
||||
// Beyond the basic block. A character Petal fails to recognise as Chinese is
|
||||
// one the English tokenizer then tries to make sense of.
|
||||
expect(isHan('𠀀')).toBe(true)
|
||||
for (const ch of ['a', '1', ' ', '，', '。', 'あ', '한']) {
|
||||
expect(isHan(ch), ch).toBe(false)
|
||||
}
|
||||
})
|
||||
})
|
||||
|
||||
describe('the walk chooses the likeliest split, not the longest match', () => {
|
||||
// The textbook case, and the reason longest-match is not good enough: 研究生
|
||||
// ("graduate student") is a real word and a longer match than 研究 at position
|
||||
// 0 — but 研究/生命 ("research" + "life") is the likelier path, and it is the
|
||||
// sentence a person would read.
|
||||
it('研究生命的起源', () => {
|
||||
const seg = dict({ 研究: 6000, 研究生: 800, 生命: 4000, 命: 900, 的: 300000, 起源: 700 })
|
||||
expect(words(seg, '研究生命的起源')).toEqual(['研究', '生命', '的', '起源'])
|
||||
})
|
||||
|
||||
it('乒乓球拍卖完了 — the ambiguity is 球拍 against 拍卖', () => {
|
||||
const seg = dict({
|
||||
乒乓球: 500, 乒乓: 400, 球拍: 200, 拍卖: 900, 卖完: 50, 完: 3000, 了: 200000, 球: 2000, 拍: 800,
|
||||
})
|
||||
expect(words(seg, '乒乓球拍卖完了')).toEqual(['乒乓球', '拍卖', '完', '了'])
|
||||
})
|
||||
|
||||
it('keeps particles as their own words', () => {
|
||||
const seg = dict({ 他: 90000, 的: 300000, 中文: 3000, 说: 20000, 得: 60000, 很: 40000, 好: 50000 })
|
||||
expect(words(seg, '他的中文说得很好')).toEqual(['他', '的', '中文', '说', '得', '很', '好'])
|
||||
})
|
||||
})
|
||||
|
||||
describe('what the walk does with what it does not know', () => {
|
||||
// A sentence with an unfamiliar character in it must still segment. Every
|
||||
// position needs *some* path through it, which is why an unknown character
|
||||
// scores badly rather than not scoring at all.
|
||||
it('an unknown character becomes its own token and the rest survives', () => {
|
||||
const seg = dict({ 我: 90000, 喜欢: 5000, 猫: 2000 })
|
||||
expect(words(seg, '我喜欢龥猫')).toEqual(['我', '喜欢', '龥', '猫'])
|
||||
})
|
||||
|
||||
// It must never *invent* a word: an unknown span of two characters is two
|
||||
// unknown characters, not a new headword.
|
||||
it('never joins unknown characters into a word', () => {
|
||||
const seg = dict({ 我: 90000 })
|
||||
expect(words(seg, '我龥龥')).toEqual(['我', '龥', '龥'])
|
||||
})
|
||||
|
||||
// A rare real word still loses to two common ones — this is the property that
|
||||
// lets the shipped list keep 100,000 rare CC-CEDICT headwords without them
|
||||
// distorting ordinary sentences.
|
||||
it('a rare long word loses to two common short ones', () => {
|
||||
const seg = dict({ 公园: 4000, 跑步: 3000, 公园跑: 1 })
|
||||
expect(words(seg, '公园跑步')).toEqual(['公园', '跑步'])
|
||||
})
|
||||
})
|
||||
|
||||
describe('Chinese is not the only thing in the paragraph', () => {
|
||||
const seg = dict({ 我: 90000, 在: 50000, 写: 8000, 英文: 3000 })
|
||||
|
||||
// Latin runs are skipped, not returned. The English tokenizer is still running
|
||||
// over the same text and owns them; returning them here would mean two layers
|
||||
// claiming one word.
|
||||
it('skips Latin and punctuation, keeping offsets into the original string', () => {
|
||||
const tokens = seg.segment('我在写 English 英文。')
|
||||
expect(tokens.map((t) => t.word)).toEqual(['我', '在', '写', '英文'])
|
||||
for (const t of tokens) {
|
||||
expect('我在写 English 英文。'.slice(t.from, t.to)).toBe(t.word)
|
||||
}
|
||||
})
|
||||
|
||||
it('每 token reports the span it actually occupies', () => {
|
||||
const tokens = seg.segment('英文')
|
||||
expect(tokens).toEqual([{ word: '英文', from: 0, to: 2 }])
|
||||
})
|
||||
})
|
||||
|
||||
describe('wordAt — the hover and click path', () => {
|
||||
const seg = dict({ 我: 90000, 今天: 8000, 去: 30000, 公园: 4000, 跑步: 3000, 了: 200000 })
|
||||
const text = '我今天去公园跑步了'
|
||||
|
||||
it('finds the word covering a position anywhere inside it', () => {
|
||||
// 公园 occupies [4,6): either of its characters resolves to the whole word
|
||||
// rather than to one character.
|
||||
for (const i of [4, 5]) {
|
||||
expect(seg.wordAt(text, i)?.word, `index ${i}`).toBe('公园')
|
||||
}
|
||||
expect(seg.wordAt(text, 0)?.word).toBe('我')
|
||||
expect(seg.wordAt(text, 2)?.word).toBe('今天')
|
||||
})
|
||||
|
||||
// A position names a gap; a word covers characters. On a boundary the answer
|
||||
// is the word that *starts* there, because that is the character being pointed
|
||||
// at — index 6 is the 跑 under the mouse, not the 园 behind it.
|
||||
it('a boundary belongs to the word that starts there', () => {
|
||||
expect(seg.wordAt(text, 6)?.word).toBe('跑步')
|
||||
expect(seg.wordAt(text, 4)?.word).toBe('公园')
|
||||
})
|
||||
|
||||
// The caret after a just-typed word belongs to that word. Ctrl/Cmd+D at the
|
||||
// end of 跑步 must look up 跑步, which is the position the caret is actually in
|
||||
// the moment someone finishes typing it.
|
||||
it('a caret at the very end of the text still resolves', () => {
|
||||
expect(seg.wordAt(text, text.length)?.word).toBe('了')
|
||||
})
|
||||
|
||||
it('returns null outside Han text', () => {
|
||||
expect(seg.wordAt('hello world', 3)).toBeNull()
|
||||
expect(seg.wordAt('', 0)).toBeNull()
|
||||
expect(seg.wordAt('我 hello', 4)).toBeNull()
|
||||
})
|
||||
|
||||
// The window exists so that a pasted page of Chinese with no punctuation is
|
||||
// not walked on every hover. It must not change the answer for ordinary text.
|
||||
it('agrees with a full segmentation of the same string', () => {
|
||||
const long = '我今天去公园跑步了'.repeat(20)
|
||||
const full = seg.segment(long)
|
||||
for (const t of full) {
|
||||
expect(seg.wordAt(long, t.from)).toEqual(t)
|
||||
}
|
||||
})
|
||||
})
|
||||
|
||||
// ── the shipped asset ───────────────────────────────────────────────────────
|
||||
// Everything above would pass with a word list built wrong. These read the file
|
||||
// this app actually serves.
|
||||
|
||||
describe('the shipped word list', () => {
|
||||
const raw = gunzipSync(readFileSync(new URL('../../public/dictionaries/zh/words.txt.gz', import.meta.url)))
|
||||
const seg = buildSegmenter(raw.toString('utf8'))
|
||||
|
||||
it('is the size the build script says it is', () => {
|
||||
expect(seg.size).toBeGreaterThan(180_000)
|
||||
})
|
||||
|
||||
it('segments ordinary learner prose the way a reader would', () => {
|
||||
expect(words(seg, '我今天早上去公园跑步了')).toEqual(['我', '今天', '早上', '去', '公园', '跑步', '了'])
|
||||
expect(words(seg, '他的中文说得很好')).toEqual(['他', '的', '中文', '说', '得', '很', '好'])
|
||||
expect(words(seg, '北京大学的学生正在图书馆学习')).toEqual([
|
||||
'北京大学', '的', '学生', '正在', '图书馆', '学习',
|
||||
])
|
||||
})
|
||||
|
||||
it('gets the textbook ambiguities right', () => {
|
||||
expect(words(seg, '研究生命的起源')).toEqual(['研究', '生命', '的', '起源'])
|
||||
expect(words(seg, '乒乓球拍卖完了')).toEqual(['乒乓球', '拍卖', '完', '了'])
|
||||
})
|
||||
|
||||
// The minimal pair, and the one that says the line above was a decision rather
|
||||
// than a bias against long words: the same five characters open both
|
||||
// sentences, and 研究生 is the right answer in one of them.
|
||||
it('finds 研究生 where 研究生 is the word', () => {
|
||||
expect(words(seg, '研究生宿舍')).toEqual(['研究生', '宿舍'])
|
||||
expect(words(seg, '他们正在研究生物')).toEqual(['他们', '正在', '研究', '生物'])
|
||||
})
|
||||
|
||||
// The three particles the 错别字 rules are about have to survive as their own
|
||||
// tokens, or those rules have nothing to anchor to.
|
||||
it('keeps 的 / 地 / 得 separate', () => {
|
||||
expect(words(seg, '她高兴地笑了')).toContain('地')
|
||||
expect(words(seg, '这个问题需要认真地思考')).toContain('地')
|
||||
expect(words(seg, '他跑得很快')).toContain('得')
|
||||
expect(words(seg, '我的书')).toContain('的')
|
||||
})
|
||||
|
||||
it('knows the words the build script asserts it kept', () => {
|
||||
for (const w of ['我', '的', '图书馆', '乒乓球', '公园', '的士']) {
|
||||
expect(seg.has(w), w).toBe(true)
|
||||
}
|
||||
})
|
||||
})
|
||||
@@ -0,0 +1,212 @@
|
||||
// Chinese word segmentation — the thing that has to exist before any of Petal's
|
||||
// ESL surfaces can point at a Chinese word.
|
||||
//
|
||||
// Every one of them is built on `wordAt(doc, pos)`, and `wordAt` is a regex over
|
||||
// runs of Latin letters. That works because English writes its word boundaries
|
||||
// down. Chinese does not: 我今天早上去公园跑步了 is eleven characters and seven
|
||||
// words, and which seven is a question with a real answer that no regex can
|
||||
// reach. Until something answers it there is no "word under the cursor" to
|
||||
// hover, look up, read aloud, or plant in the vocabulary garden.
|
||||
//
|
||||
// **Why the answer is a shortest-path walk and not longest-match.** The obvious
|
||||
// algorithm — take the longest dictionary word at each position and move on —
|
||||
// gets the textbook cases wrong in both directions, because the longest match is
|
||||
// not the likeliest one. The standard fix is to score every possible split by
|
||||
// how probable its words are and take the best-scoring path, which is a
|
||||
// shortest-path problem over a small DAG and is what this does. It is why the
|
||||
// word list ships with a frequency column at all.
|
||||
//
|
||||
// **Why it runs in the browser.** It runs on hover. A round-trip per hover is
|
||||
// not a hover, and the whole point of the offline lexicon (SUGGESTIONS §6) is
|
||||
// that the daily reading aids keep working with the tunnel down.
|
||||
|
||||
// A word found in the text, with the offsets it occupies. Offsets are into the
|
||||
// string that was passed in — the caller maps them to ProseMirror positions the
|
||||
// same way the spell and suggestion layers already do.
|
||||
export interface Token {
|
||||
word: string
|
||||
from: number
|
||||
to: number
|
||||
}
|
||||
|
||||
// Han characters only. Not a hand-rolled U+4E00–U+9FFF range: that misses the
|
||||
// extension blocks, and a character Petal fails to recognise as Chinese is one
|
||||
// the English tokenizer then tries to make sense of.
|
||||
const HAN = /\p{Script=Han}/u
|
||||
|
||||
export function isHan(ch: string): boolean {
|
||||
return HAN.test(ch)
|
||||
}
|
||||
|
||||
// The longest word the walk will consider at any position. The dictionary
|
||||
// contains longer entries (chengyu, place names, a few titles), but the cost of
|
||||
// the walk is linear in this number and the entries beyond it are rare enough
|
||||
// that paying for them on every hover is the wrong trade. Six characters covers
|
||||
// every ordinary word and every four-character idiom.
|
||||
const MAX_WORD_LEN = 6
|
||||
|
||||
// What an unknown single character is worth, as a fraction of one occurrence.
|
||||
// It must be *positive* — every position needs some path through it, or a
|
||||
// sentence containing one unfamiliar character would have no segmentation at
|
||||
// all — and it must be small enough that a real one-character word always wins.
|
||||
// Half an occurrence is below the rarest thing in the list (which is 1) and
|
||||
// above zero, which is the whole specification.
|
||||
const UNKNOWN_WEIGHT = 0.5
|
||||
|
||||
export interface Segmenter {
|
||||
// segment splits a whole string. Runs of non-Han text are skipped rather than
|
||||
// returned: this is the Chinese tokenizer, and the Latin one is still running
|
||||
// over the same paragraph.
|
||||
segment(text: string): Token[]
|
||||
// wordAt returns the token covering `index`, or null when that position is
|
||||
// not inside Han text. This is the hover/click path, and it segments only the
|
||||
// run around the position rather than the whole document.
|
||||
wordAt(text: string, index: number): Token | null
|
||||
// has reports whether a word is in the list — the 错别字 rules ask, to check
|
||||
// that a correction they are about to propose is a real word.
|
||||
has(word: string): boolean
|
||||
size: number
|
||||
}
|
||||
|
||||
// buildSegmenter turns the raw `word freq` list into something that can answer
|
||||
// questions about it. Exported for tests, which build tiny dictionaries by hand;
|
||||
// the app reaches it through loadSegmenter.
|
||||
export function buildSegmenter(source: string): Segmenter {
|
||||
const freq = new Map<string, number>()
|
||||
let total = 0
|
||||
for (const line of source.split('\n')) {
|
||||
if (!line) continue
|
||||
const sp = line.lastIndexOf(' ')
|
||||
if (sp <= 0) continue
|
||||
const word = line.slice(0, sp)
|
||||
const n = Number(line.slice(sp + 1))
|
||||
if (!Number.isFinite(n) || n <= 0) continue
|
||||
freq.set(word, n)
|
||||
total += n
|
||||
}
|
||||
// A dictionary with nothing in it would make every log() below -Infinity.
|
||||
const logTotal = Math.log(Math.max(total, 1))
|
||||
const unknownScore = Math.log(UNKNOWN_WEIGHT) - logTotal
|
||||
|
||||
// The walk, over one run of Han characters.
|
||||
//
|
||||
// `best[i]` is the score of the best segmentation of run[i..], and `next[i]`
|
||||
// is where that segmentation's first word ends. Filling it right-to-left means
|
||||
// each position only ever reads answers that are already final, which is what
|
||||
// makes this linear rather than exponential in the number of possible splits.
|
||||
function walk(run: string, base: number, out: Token[]): void {
|
||||
const n = run.length
|
||||
const best = new Float64Array(n + 1)
|
||||
const next = new Int32Array(n + 1)
|
||||
best[n] = 0
|
||||
for (let i = n - 1; i >= 0; i--) {
|
||||
let bestScore = -Infinity
|
||||
let bestEnd = i + 1
|
||||
const limit = Math.min(n, i + MAX_WORD_LEN)
|
||||
for (let j = i + 1; j <= limit; j++) {
|
||||
const f = freq.get(run.slice(i, j))
|
||||
let score: number
|
||||
if (f === undefined) {
|
||||
// Only a single unknown character is a candidate. Allowing unknown
|
||||
// multi-character spans would let the walk invent words.
|
||||
if (j > i + 1) continue
|
||||
score = unknownScore
|
||||
} else {
|
||||
score = Math.log(f) - logTotal
|
||||
}
|
||||
score += best[j]
|
||||
if (score > bestScore) {
|
||||
bestScore = score
|
||||
bestEnd = j
|
||||
}
|
||||
}
|
||||
best[i] = bestScore
|
||||
next[i] = bestEnd
|
||||
}
|
||||
for (let i = 0; i < n; ) {
|
||||
const end = next[i]
|
||||
out.push({ word: run.slice(i, end), from: base + i, to: base + end })
|
||||
i = end
|
||||
}
|
||||
}
|
||||
|
||||
function segment(text: string): Token[] {
|
||||
const out: Token[] = []
|
||||
let i = 0
|
||||
while (i < text.length) {
|
||||
if (!isHan(text[i])) {
|
||||
i++
|
||||
continue
|
||||
}
|
||||
let j = i
|
||||
while (j < text.length && isHan(text[j])) j++
|
||||
walk(text.slice(i, j), i, out)
|
||||
i = j
|
||||
}
|
||||
return out
|
||||
}
|
||||
|
||||
// How much context a hover segments. The run around the cursor is bounded
|
||||
// because a pasted page of Chinese with no punctuation is one run, and a hover
|
||||
// must not walk it. Segmentation is local enough that a window this size
|
||||
// reaches the same answer as the whole paragraph would: the walk's decisions
|
||||
// are dominated by the two or three characters either side, and a word longer
|
||||
// than MAX_WORD_LEN cannot span the window's edge anyway.
|
||||
const WINDOW = 60
|
||||
|
||||
function wordAt(text: string, index: number): Token | null {
|
||||
if (index < 0 || index > text.length) return null
|
||||
// `index` names a gap between characters; a word covers characters. So the
|
||||
// question is resolved on the character at `index` — the one to the *right*
|
||||
// of the caret — and a boundary belongs to the word that starts there rather
|
||||
// than the one that ends there. For a hover that is simply correct: index 6
|
||||
// of 我今天去公园跑步了 is the 跑 being pointed at.
|
||||
//
|
||||
// The step back covers the case where there is no character to the right:
|
||||
// the caret at the end of the text, or against following punctuation. That
|
||||
// is where the caret sits the instant an IME commits a word, and Ctrl/Cmd+D
|
||||
// there must look up the word just typed.
|
||||
let probe = index
|
||||
if (probe >= text.length || !isHan(text[probe])) {
|
||||
if (probe > 0 && isHan(text[probe - 1])) probe -= 1
|
||||
else return null
|
||||
}
|
||||
let start = probe
|
||||
while (start > 0 && isHan(text[start - 1]) && probe - start < WINDOW) start--
|
||||
let end = probe
|
||||
while (end < text.length && isHan(text[end]) && end - probe < WINDOW) end++
|
||||
|
||||
const tokens: Token[] = []
|
||||
walk(text.slice(start, end), start, tokens)
|
||||
for (const t of tokens) {
|
||||
if (probe >= t.from && probe < t.to) return t
|
||||
}
|
||||
return null
|
||||
}
|
||||
|
||||
return { segment, wordAt, has: (w) => freq.has(w), size: freq.size }
|
||||
}
|
||||
|
||||
// Where the word list lives. Gzipped, like every dictionary Petal ships that is
|
||||
// bigger than English's.
|
||||
const WORDS_URL = '/dictionaries/zh/words.txt.gz'
|
||||
|
||||
// loadSegmenter fetches and builds the segmenter. One per session, like the
|
||||
// spelling dictionaries — the cost is the parse, not the download, and paying it
|
||||
// per document would be paying it per document for no reason.
|
||||
//
|
||||
// A failure resolves to null rather than throwing. Petal without segmentation is
|
||||
// Petal with no Chinese hover, which is a diminished editor; Petal that refused
|
||||
// to open because a static asset 404ed is no editor at all.
|
||||
export async function loadSegmenter(url = WORDS_URL): Promise<Segmenter | null> {
|
||||
try {
|
||||
const res = await fetch(url)
|
||||
if (!res.ok || !res.body) return null
|
||||
const stream = res.body.pipeThrough(new DecompressionStream('gzip'))
|
||||
const text = await new Response(stream).text()
|
||||
const seg = buildSegmenter(text)
|
||||
return seg.size > 0 ? seg : null
|
||||
} catch {
|
||||
return null
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user