Skip to content

ADR-v2-142 — Localize command grammars, not command semantics

Status: Proposed (2026-09-20)
Context: Chinese voice commands; commands/grammar.py; CommandIntent; application profiles.

Context

YazSes command recognition is currently English-specific. Tier 1 contains English regexes and English number-word normalization, while dispatch consumes language-neutral semantic actions such as:

  • undo
  • save
  • copy
  • go_to_line
  • select_all

Chinese dictation without Chinese command recognition would type phrases such as “撤销” or “保存文件” instead of performing the corresponding action.

A naive implementation could duplicate the whole command/dispatch subsystem for Chinese. That would create separate behavior, safety fixes and editor mappings per language.

There is also an existing CommandsConfig.profile, but it represents application/editor behavior. Reusing it for spoken language would conflate two dimensions.

Decision

Keep semantic command IDs and dispatch language-neutral. Add language-specific Tier-1 grammars that map spoken phrases into the existing CommandIntent model.

Add a dedicated command-language setting:

[commands]
language = "auto"

Semantics:

  • auto follows the configured STT speech language when a grammar exists;
  • en forces English spoken commands;
  • zh forces Chinese spoken commands.

CommandsConfig.profile retains its current application/editor meaning.

The classifier tier order remains:

user macro -> localized deterministic grammar -> optional local SLM -> dictate

P1 Chinese support does not require a Chinese SLM.

Grammar organization

grammar.classify() remains the stable public API.

Internally, move/encapsulate English rules behind a grammar registry and add Chinese rules. The exact file layout may vary, but dispatch and action names must not be copied.

Locale-specific normalization

Chinese command parsing may normalize:

  • terminal Chinese punctuation;
  • ASR spacing around digits/Latin text;
  • common Chinese numerals needed by commands;
  • explicitly reviewed Simplified/Traditional phrase variants.

Normalization applies only to the command candidate. It must not rewrite ordinary dictation.

Consequences

Positive

  • English and Chinese commands execute identical semantic actions.
  • Safety fixes in dispatch apply once.
  • More spoken languages can be added without duplicating action logic.
  • Users can dictate in Chinese while deliberately keeping English commands, or vice versa.
  • Application profile and spoken language remain orthogonal.

Costs

  • The current monolithic English rule table must be refactored carefully.
  • Phrase sets need native-speaker review.
  • Chinese numeral parsing adds locale-specific logic.
  • Contract vectors need a language dimension.

Alternatives considered

Translate text to English before the current grammar

Rejected. It adds an ML/translation dependency to a deterministic <5 ms path, creates privacy/latency complexity, and makes exact command safety harder to reason about.

Put Chinese alternatives into every existing English regex

Rejected. Mixed-language regexes become unreadable, untestable and difficult for contributors to own.

Duplicate grammar + dispatch for Chinese

Rejected. Semantic behavior would drift and every platform/safety fix would need duplication.

Reuse CommandsConfig.profile

Rejected. “VS Code” and “Chinese” are different axes. Overloading the field would make combinations impossible.

Acceptance constraints

  • Existing English contract vectors remain valid.
  • Chinese equivalent phrases emit the same action IDs/arguments.
  • Unknown Chinese utterances remain dictation, never fuzzy commands.
  • No Chinese rule invokes shell actions more broadly than its English semantic equivalent.
  • Traditional/Simplified aliases are explicitly tested.
  • Command parser changes do not globally normalize injected prose.