Skip to content

Add Simplified Chinese speech and navigation rules - #712

Merged
NSoiffer merged 342 commits into
daisy:zh-cnfrom
cary-rowen:work/zh-cn-textbook-audit
Nov 17, 2026
Merged

NSoiffer merged 342 commits into
daisy:zh-cnfrom
cary-rowen:work/zh-cn-textbook-audit

Conversation

@cary-rowen

@cary-rowen cary-rowen commented Aug 22, 2026 •

Copy link
Copy Markdown
Contributor

Summary

This PR adds a complete Simplified Chinese translation for MathCAT's speech and navigation rules.

The current English rules were used as the source, but the spoken text was rewritten in natural Mainland Mandarin rather than translated word for word. Terminology follows common usage in Mainland Chinese mathematics education.

The rules are placed directly under Rules/Languages/zh, allowing zh-CN and similar locales to use them through MathCAT's normal locale fallback. The existing Traditional Chinese overrides under Rules/Languages/zh/tw remain unchanged.

Coverage

The translation includes:

  • ClearSpeak, SimpleSpeak, and LiteralSpeak output
  • arithmetic, calculus, geometry, and linear algebra rules
  • fractions, roots, powers, matrices, sets, intervals, coordinates, units, and common chemistry notation
  • mathematical intents and common and extended Unicode symbols (including MathType and MathJax private-use mappings)
  • overview descriptions and mathematical navigation
  • locale fallback and Simplified Chinese regression tests

All 12 required language rule files are included, and verified translations use MathCAT's T: marker.

Translation choices

The wording is kept concise and follows forms familiar to students and screen reader users in Mainland China.

  • Fractions use denominator-first order, such as 2 分之 1.
  • Powers and roots use natural Chinese word order, such as x 的 n 次方 and x 的 n 次方根.
  • Set, interval, and logic notation uses established textbook readings such as 空集, 属于, 左闭右开区间, 实数集, 任意, 且, 或, and 推出.
  • Geometry notation uses semantic readings such as 三角形, 平行四边形, 相似于, 全等于, 直角三角形, and 圆 O.
  • dot-product(a,b) is read as a 与 b 的数量积, while cross-product(a,b) is read as a 与 b 的叉积. Ordinary infix operators remain 点乘 and 叉乘.
  • Independent or prefix ± and ∓ are read as 正或负 and 负或正; binary operations are read as 加或减 and 减或加.
  • Variants of the less-than-or-equal and greater-than-or-equal signs use 小于等于 and 大于等于 instead of visual descriptions of the glyphs.

Context-dependent symbols

Some symbols have more than one mathematical meaning and are handled according to context.

A bare ∆ is read as 增量, while an expression with the explicit laplacian intent is read as 拉普拉斯算子. Likewise, ⊙O is read as 圆 O, while a binary expression such as a ⊙ b keeps the generic reading 带圈点运算符.

Symbols such as ∼ and □ are not assigned a single specialized meaning where the presentation alone is insufficient to determine their use.

References

Terminology and symbol readings were checked against:

Validation

The Chinese language test suite passes with 381 tests and no failures (both with filesystem rules and with --features include-zip). Overlap between unicode.yaml and unicode-full.yaml has been eliminated, and audit-translations zh across all 12 rule files reports 0 untranslated strings and 0 definition issues (its single nominal missing-rule notice is an intentional split of the grouped Greek key "ΪΫϏ" into individual characters). The diff also passes whitespace validation.

Scope

This PR adds the base Simplified Chinese rules under Rules/Languages/zh and regression tests under tests/Languages/zh/cn, without changing the existing Traditional Chinese rules (Rules/Languages/zh/tw) or braille rules. It also includes two small supporting fixes uncovered during validation:

  • src/shim_filesystem.rs: prevent find_files_in_dir_that_ends_with_shim (used when include-zip is enabled) from returning regional subdirectory *_Rules.yaml files such as zh/tw/*_Rules.yaml when querying the base zh directory.
  • Rules/Intent/general.yaml and Rules/definitions.yaml: include U+1F8D1 (🣑) alongside U+1F8D2–U+1F8D4 in the Unicode 17 chemical equilibrium arrows list.

@moritz-gross
moritz-gross requested a review from NSoiffer August 22, 2026 21:31
@moritz-gross moritz-gross added enhancement New feature or request rules Pertains to Rules translation Language translation of math/code labels Aug 22, 2026
@moritz-gross moritz-gross moved this from Triage to In review in MathCAT Project Board Aug 22, 2026
@NSoiffer
NSoiffer changed the base branch from main to zh-cn August 23, 2026 22:11

@NSoiffer NSoiffer left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for for doing this!

It looks like you used AI to generate this. Have you looked through the tests and/or the unicode files to make sure the AI made the appropriate translantion? At least for other languages, it struggles to get the math terminolgy correct. For the tests, it tends to just make the expected results match the computed ones.

FYI: I changed the merge target to daisy:zh-cn (which I updated to merge).

@cary-rowen

Copy link
Copy Markdown
Contributor Author

Yes, a significant part of the work involved AI assistance. To ensure translation accuracy, I provided extensive reference context (as listed in the PR description, including national standards and official textbooks). I have reviewed the test cases and haven't found issues so far. However, I'd like to keep this PR as a draft for now while I double-check everything thoroughly. Once ready, I will mark it as ready for review.

@cary-rowen
cary-rowen marked this pull request as draft August 24, 2026 05:55
@NSoiffer

Copy link
Copy Markdown
Collaborator

I'm glad to hear that you are reviewing them. AI is really helpful, and it is what we are now using to seed the speech for other languages. But most translators report that they have to change over half the strings so that the speech is what is expected.

@cary-rowen
cary-rowen force-pushed the work/zh-cn-textbook-audit branch from 63d8dba to 1147ce7 Compare September 1, 2026 12:26
@cary-rowen
cary-rowen force-pushed the work/zh-cn-textbook-audit branch from 1d4d6c0 to 5ed7296 Compare September 18, 2026 22:26
moritz-gross and others added 16 commits September 22, 2026 15:54
Added back the info on how to use MathCAT as an addon to NVDA, which was accidentally removed.
…ks into a single history vector (daisy#776)

* Refactor navigation state management: unify position and command stacks into a single history vector

* fix cargo clippy no-unsafe
* Refactor `read_prefs_file` to simplify error handling and optimize section processing

* use with_context(..) from anyhow-crate for error-handling
NSoiffer and others added 13 commits November 14, 2026 23:35
A leaf intent such as <mo intent="plus"> falls through to default-text,
which spoke its English intent name: 191 of the 216 ja IntentMappings
names came out in English as leaves. The same happened to the leaves
dot-product and cross-product that the intent rules infer for · and ×
between vectors. default-text now speaks the IntentMappings word, taking
the first entry as add_fixity does; a name that is not in IntentMappings
is spoken as before. The :literal: branch is unchanged, so LiteralSpeak
still reads the character.


Claude-Session: https://claude.ai/code/session_01PxieeP42iufiDrdBqZ3hn3

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
…aml; say 波形の and 一対の (daisy#1030)

Mark the 63 U+21xx entries that MathJax can produce, directly or through
mathvariant, as T: after checking them against en and Open JTalk.
Open JTalk reads 波形 at the start of a word as なみかた and 対の as たいの,
so the wave arrows are 波形の … and the paired arrows are 一対の ….


Claude-Session: https://claude.ai/code/session_01PxieeP42iufiDrdBqZ3hn3

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
… 隅 (daisy#1031)

Mark the ten U+23xx entries still unverified that MathJax produces from
TeX (the ceiling, floor and corner brackets, frown and smile) as
verified, and also the angle brackets at U+2329 and U+232A, which daisy#1028
named 山カッコ like those at U+27E8 and U+27E9. The corner brackets were
左上角 and so on, and Open JTalk read 角 there inconsistently (カク,
スミ, スミ, カク), so they are 左上隅 and so on, which it reads スミ
every time; 隅 is already used for a corner position, as in
⦍ 上隅短線付き角かっこ.


Claude-Session: https://claude.ai/code/session_01PxieeP42iufiDrdBqZ3hn3

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Bumps [html-escape](https://github.com/magiclen/html-escape) from 0.3.0 to 0.3.1.
- [Commits](magiclen/html-escape@v0.3.0...v0.3.1)

---
updated-dependencies:
- dependency-name: html-escape
  dependency-version: 0.3.1
  dependency-type: direct:production
  update-type: version-update:semver-patch
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
…l.yaml (daisy#1037)

Mark the eight U+26xx entries still unverified that MathJax produces
from TeX (★, the suits ♠ ♡ ♢ ♣ and the music signs ♭ ♮ ♯) as verified.
The names stay: Open JTalk reads all eight as intended, and the suits
keep 黒 and 白 as en keeps black and white, so ♡ stays apart from ♥.
The new test writes them as mi, as MathJax does.


Claude-Session: https://claude.ai/code/session_01PxieePZDtjAQxDTwKoDE1t

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
…y#1038)

Mark as verified the unicode-full entries in U+24xx, U+29xx and U+2Exx
that MathJax produces from TeX: the circled letters (\circledS),
⧫ (\blacklozenge), ⧸ (\notChar) and ⸘ (\textinterrobangdown). The names
stay, since Open JTalk reads them as intended. The uppercase
circled-letter range was keyed "Ⓐ-ⓩ", which runs on through ⓐ-ⓩ, so the
lowercase letters were defined twice; it is now "Ⓐ-Ⓩ" as in en.


Claude-Session: https://claude.ai/code/session_01PxieePZDtjAQxDTwKoDE1t

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
…code-full.yaml (daisy#1039)

Mark as verified the 38 math alphanumeric entries a mathvariant reaches
through canonicalize (bold, bold italic, script, bold script, fraktur,
bold fraktur, double-struck, the bold sans-serif forms, their Greek and
digits, and the bold and italic nablas). The words stay, since the short
table already uses 黒板太字, スクリプト and フラクトゥール and Open JTalk
reads them and 太字 as intended. Bold now comes first for bold script and
bold fraktur, as in 太字 イタリック ナブラ, and the commented-out bold
italic is 太字 イタリック instead of the machine translation
大胆なイタリック.


Claude-Session: https://claude.ai/code/session_01PxieePZDtjAQxDTwKoDE1t

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
@NSoiffer

Copy link
Copy Markdown
Collaborator

@cary-rowen: a little nudge that the code freeze happens in two weeks. It would be great to get this into the next version of MathCAT.

hammera and others added 5 commits November 16, 2026 13:17
…y#944)

* Rules/Languages/hu/SharedRules/default.yaml: added mtable related change with commas related, basic with english change

Signed-off-by: Attila Hammer <hammera@pickup.hu>

* tests/Languages/hu/mtable.rs: update mtable related change, added new tests based with new english tests

Signed-off-by: Attila Hammer <hammera@pickup.hu>

* Rules/Languages/hu/ClearSpeak_Rules.yaml, Rules/Languages/hu/Simplespeak_rules.yaml, Rules/Languages/hu/unicode.yaml, Rules/Languages/hu/unicode-full.yaml, Rules/Languages/hu/definitions.yaml: handle translator audit difference changes

Signed-off-by: Attila Hammer <hammera@pickup.hu>

* tests/Languages/hu/shared.rs, Tests/Languages/hu/units.rs: fix expected output with right strings

Signed-off-by: Attila Hammer <hammera@pickup.hu>

* Rules/Languages/hu/ClearSpeak_Rules.yaml, Rules/Languages/hu/Simplespeak_rules.yaml: handle audit match differences in per-fraction rule

Signed-off-by: Attila Hammer <hammera@pickup.hu>

---------

Signed-off-by: Attila Hammer <hammera@pickup.hu>
@cary-rowen
cary-rowen marked this pull request as ready for review November 17, 2026 04:29
@cary-rowen

Copy link
Copy Markdown
Contributor Author

Hi @NSoiffer, thanks for the reminder! I've finished syncing with main, expanding and reorganizing the test suite, and completing the terminology and Unicode audit. Everything is passing now, so I'm marking this PR ready for review ahead of the Dec 1 code freeze.

(Also a quick heads-up: since this branch is synced with main, daisy:zh-cn may need to be updated from main to clear the upstream commits from the diff.)

@github-actions

Copy link
Copy Markdown
Contributor
Linux library size: 0.60 MiB (-0.03%)
Revision Release liblibmathcat.so
Base (fc07fed) 0.60 MiB (624,928 bytes)
PR (f82fed0) 0.60 MiB (624,752 bytes)
Change -176 bytes (-0.03%)

Built with default features, Rust 1.96.0, and Ubuntu 24.04. Workflow run.

@NSoiffer
NSoiffer merged commit 149f19e into daisy:zh-cn Nov 17, 2026
14 checks passed
@github-project-automation github-project-automation Bot moved this from In review to Done in MathCAT Project Board Nov 17, 2026
@NSoiffer

Copy link
Copy Markdown
Collaborator

@cary-rowen: I needed to back out of this merge because I saw that you accidentally put the SharedRules in the wrong directory: Rules/Languages/zh/SharedRules instead of Rules/Languages/zh/cn/SharedRules. Can you fix that?

Also, I suggest doing a PR directly to main.

@cary-rowen

Copy link
Copy Markdown
Contributor Author

Hi @NSoiffer
I have opened #1056. Sorry for the confusion.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request rules Pertains to Rules translation Language translation of math/code

Projects

Status: Done

Development

Successfully merging this pull request may close these issues.