Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

[BUG] Apple Speech always transcribes Chinese as Simplified (zh-CN); Traditional Chinese (zh-TW / zh-HK) cannot be selected

Open
  • Is something wrong?
#1,202 2 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
56/100
Issue type
Bug
Clarity
Clearly specified
Activity status
Active
Tech stack
macos, swift
Domain
backend, developer-experience

Research direction

Start with Voice Engine settings and Sources/Fluid/Persistence/VoiceEngineLanguageCatalog.swift, then trace how AppleSpeechProvider, AppleSpeechAnalyzerProvider, and SettingsStore.selectedAppleSpeechLocale use the selected locale. Check the engines’ supported locale lists and existing locale download path. Done means users can select an appropriate Chinese locale in settings and both Apple engines use that saved choice.

Written by the indexing model from the issue text.

Description

Describe the bug

With either Apple engine selected ("Apple Speech - macOS 26+", which uses SpeechTranscriber, or "Apple ASR Legacy", which uses SFSpeechRecognizer), Chinese dictation always comes out in Simplified Chinese. Users in Taiwan and Hong Kong need Traditional Chinese.

macOS supports Traditional Chinese for both engines, but FluidVoice gives no way to choose it:

  • The language catalog maps Chinese to one locale only. In Sources/Fluid/Persistence/VoiceEngineLanguageCatalog.swift, appleSpeechAnalyzerLocaleMap has "zh": "zh-CN". The legacy preference list is ["zh-CN", "zh-TW", "zh-HK"], but the code takes the first supported entry, so it also always picks zh-CN.
  • Only onboarding sets SelectedAppleSpeechLocaleIdentifier (through VoiceEngineLanguageCatalog.apply). The Voice Engine settings page has a language picker for Whisper only, and onboarding cannot be reopened after it finishes. A user who chose Mandarin is stuck on zh-CN.

Both engines read the same key: AppleSpeechProvider (legacy) and AppleSpeechAnalyzerProvider both build their locale from SettingsStore.selectedAppleSpeechLocale. I have only tested "Apple Speech - macOS 26+".

In #185 (https://github.com/altic-dev/FluidVoice/issues/185) another user asked for Mandarin (Taiwan) and Cantonese (Hong Kong) on Apple Speech. That issue was closed with the reply that Apple doesn't offer many locales. On my Mac, both APIs do list them, and the zh-TW model for SpeechTranscriber is already installed. I got these lists by calling SFSpeechRecognizer.supportedLocales(), SpeechTranscriber.supportedLocales and SpeechTranscriber.installedLocales from a small Swift script (swift list_locales.swift), filtered to Chinese:

SFSpeechRecognizer.supportedLocales:  yue-CN, zh-CN, zh-HK, zh-TW
SpeechTranscriber.supportedLocales:   yue-CN, zh-CN, zh-HK, zh-TW
SpeechTranscriber.installedLocales:   zh-CN, zh-TW
list_locales.swift 
import Speech
print("legacy:", SFSpeechRecognizer.supportedLocales().map{$0.identifier}.filter{$0.hasPrefix("zh")||$0.hasPrefix("yue")}.sorted())
if #available(macOS 26, *) {
  let s = await SpeechTranscriber.supportedLocales
  print("analyzer:", s.map{$0.identifier(.bcp47)}.filter{$0.hasPrefix("zh")||$0.hasPrefix("yue")}.sorted())
  let i = await SpeechTranscriber.installedLocales
  print("installed:", i.map{$0.identifier(.bcp47)}.sorted())
}

Workaround that works for me: quit FluidVoice, run the command below, and relaunch. Dictation then comes out in Traditional Chinese, and the setting persists across launches.

defaults write com.FluidApp.app SelectedAppleSpeechLocaleIdentifier zh-TW

Reproduction steps

  1. In onboarding, choose Mandarin as the language and "Apple Speech - macOS 26+" as the model.
  2. Dictate a sentence in Mandarin. The text uses Simplified characters (for example 这/说 instead of 這/說).
  3. Run defaults read com.FluidApp.app SelectedAppleSpeechLocaleIdentifier. It prints zh-CN.
  4. Open Voice Engine settings. Apple Speech shows no language or region option.

Expected behavior

In Voice Engine settings, I can choose the Apple Speech locale for Chinese, for example zh-TW to get Traditional Chinese output.

Actual behavior

Chinese always uses zh-CN, so the output is Simplified. There is no UI to change it.

Suggested fix

Add a locale picker for the Apple engines in Voice Engine settings, filled from the selected engine's supportedLocales and filtered to the current language (for Mandarin, the zh-* locales). Show it only when the language has more than one locale. The picker writes the same SelectedAppleSpeechLocaleIdentifier key that onboarding writes, so both stay in sync. For a locale that isn't installed yet, the existing download path in AppleSpeechAnalyzerProvider (AssetInventory.assetInstallationRequest) already handles it. Onboarding can stay as it is.

I have only tested zh-TW. I haven't checked whether Apple's zh-HK model recognizes Mandarin or Cantonese. yue-CN is Cantonese (China mainland), and offering it could also cover the Cantonese part of #185.

I'm happy to send a PR if this approach works for you.

App Version

1.6.11

macOS Version

macOS 27.0.1, build 26A434 (as printed by sw_vers)

Architecture

Apple Silicon

Dominant language
Swift
Stars
11.9k
Forks
863
Avg merge
1d 12h
Merged PRs (30d)
37

Getting set up

This project ships no dev container, Dockerfile or contributing guide, so setting up is up to you: start from its README, and see our first-contribution guide for the general steps.

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from altic-dev/FluidVoice

All issues in altic-dev/FluidVoice

Similar issues

More Swift issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.