The best way to control Claude Code, Codex and more from any computer or phone
fix(mobile): use preferred languages for on-device iPhone dictation (#31800)
Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
Julius Marminge committed
Nov 5, 2026 at 22:08 UTC
2785e55fe8555d9c112e3571aebe0a03c395cf3a
3 files changed
+136
-17
apps/mobile/src/native/voiceTranscription.ios.test.ts
+98
-7
@@ -8,6 +8,12 @@ const mocks = vi.hoisted(() => ({
8
prepare: vi.fn<(locale: string) => Promise<string>>(),
9
transcribe: vi.fn<(audio: ArrayBufferLike, locale: string) => Promise<TranscriptionResult>>(),
10
readAudio: vi.fn<() => Promise<ArrayBuffer>>(),
11
+ preferredLanguages: [] as unknown,
12
+}));
13
+
14
+// iOS exposes the user's ordered Language & Region list through NSUserDefaults.
15
+vi.mock("react-native", () => ({
16
+ Settings: { get: (key: string) => (key === "AppleLanguages" ? mocks.preferredLanguages : null) },
17
}));
18
19
vi.mock("@react-native-ai/apple/src/NativeAppleTranscription", () => ({
@@ -35,16 +41,33 @@ const nativeTranscript: TranscriptionResult = {
41
],
42
};
43
38
-function deferred<T>() {
39
- let resolve!: (value: T) => void;
40
- const promise = new Promise<T>((next) => {
41
- resolve = next;
44
+const unsupportedLocale = () =>
45
+ Object.assign(new Error("unsupported"), { code: "AppleTranscriptionUnsupportedLocale" });
46
+
47
+function useLanguages(preferred: ReadonlyArray<string>, appLocale: string) {
48
+ mocks.preferredLanguages = preferred;
49
+ const resolvedOptions = Intl.DateTimeFormat().resolvedOptions();
50
+ vi.spyOn(Intl.DateTimeFormat.prototype, "resolvedOptions").mockReturnValue({
51
+ ...resolvedOptions,
52
+ locale: appLocale,
53
});
43
- return { promise, resolve };
54
+}
55
+
56
+/** Prepares and transcribes one recording, resolving with the error when either step fails. */
57
+async function transcribeOnce(signal = new AbortController().signal) {
58
+ const transcriber = (await getLocalVoiceTranscriber())!;
59
+ return transcriber
60
+ .prepare({ signal })
61
+ .then(async (prepared) => {
62
+ const text = await prepared.transcribe("file:///voice.m4a", { signal });
63
+ return { text, locale: prepared.locale };
64
+ })
65
+ .catch((error: unknown) => error);
66
}
67
68
beforeEach(() => {
69
vi.resetAllMocks();
70
+ useLanguages([], "sv-SE");
71
mocks.isAvailable.mockReturnValue(true);
72
mocks.prepare.mockResolvedValue("sv-SE");
73
mocks.readAudio.mockResolvedValue(audio);
@@ -56,9 +79,77 @@ afterEach(() => {
79
});
80
81
describe("getLocalVoiceTranscriber", () => {
82
+ it.each([
83
+ {
84
+ case: "a spoken language ahead of the English app locale",
85
+ preferred: ["ko-KR", "en-US"],
86
+ supported: ["ko-KR", "en-US"],
87
+ tried: ["ko-KR"],
88
+ },
89
+ {
90
+ case: "the next preferred language after an unsupported one",
91
+ preferred: ["gsw-CH", "de-CH", "en-US"],
92
+ supported: ["de-CH", "en-US"],
93
+ tried: ["gsw-CH", "de-CH"],
94
+ },
95
+ {
96
+ case: "the app locale when no preferred language is supported",
97
+ preferred: ["gsw-CH", "yi"],
98
+ supported: ["en-US"],
99
+ tried: ["gsw-CH", "yi", "en-US"],
100
+ },
101
+ ])("prepares $case", async ({ preferred, supported, tried }) => {
102
+ useLanguages(preferred, "en-US");
103
+ mocks.prepare.mockImplementation(async (candidate) => {
104
+ if (!supported.includes(candidate)) throw unsupportedLocale();
105
+ return candidate;
106
+ });
107
+
108
+ const locale = tried.at(-1)!;
109
+ expect(await transcribeOnce()).toEqual({ text: "Hej världen.", locale });
110
+ expect(mocks.prepare.mock.calls.map(([candidate]) => candidate)).toEqual(tried);
111
+ expect(mocks.transcribe).toHaveBeenCalledWith(audio, locale);
112
+ });
113
+
114
+ it("reports an unsupported language when neither preferred nor app locales are supported", async () => {
115
+ useLanguages(["gsw-CH"], "yi");
116
+ mocks.prepare.mockRejectedValue(unsupportedLocale());
117
+
118
+ expect(await transcribeOnce()).toMatchObject({ code: "unsupported-locale" });
119
+ expect(mocks.prepare.mock.calls.map(([candidate]) => candidate)).toEqual(["gsw-CH", "yi"]);
120
+ });
121
+
122
+ it.each(["cancellation", "a model failure"] as const)(
123
+ "does not fall back to another language after %s",
124
+ async (failure) => {
125
+ useLanguages(["ko-KR", "ja-JP"], "en-US");
126
+ const entered = Promise.withResolvers<void>();
127
+ const nativePrepare = Promise.withResolvers<string>();
128
+ mocks.prepare.mockImplementation(() => {
129
+ entered.resolve();
130
+ return nativePrepare.promise;
131
+ });
132
+ const controller = new AbortController();
133
+ const result = transcribeOnce(controller.signal);
134
+
135
+ await entered.promise;
136
+ if (failure === "cancellation") {
137
+ controller.abort();
138
+ nativePrepare.reject(unsupportedLocale());
139
+ } else {
140
+ nativePrepare.reject(Object.assign(new Error("download failed"), { code: "Network" }));
141
+ }
142
+
143
+ expect(await result).toMatchObject({
144
+ code: failure === "cancellation" ? "cancelled" : "preparation-failed",
145
+ });
146
+ expect(mocks.prepare.mock.calls.map(([candidate]) => candidate)).toEqual(["ko-KR"]);
147
+ },
148
+ );
149
+
150
it("does not start native transcription after cancellation during a file read", async () => {
60
- const enteredRead = deferred<void>();
61
- const readResult = deferred<ArrayBuffer>();
151
+ const enteredRead = Promise.withResolvers<void>();
152
+ const readResult = Promise.withResolvers<ArrayBuffer>();
153
mocks.readAudio.mockImplementation(() => {
154
enteredRead.resolve();
155
return readResult.promise;
apps/mobile/src/native/voiceTranscription.ios.ts
+33
-8
@@ -1,6 +1,7 @@
1
import * as Schema from "effect/Schema";
2
import AppleTranscription from "@react-native-ai/apple/src/NativeAppleTranscription";
3
import { File } from "expo-file-system";
4
+import { Settings } from "react-native";
5
6
import {
7
VoiceTranscriptionError,
@@ -12,8 +13,15 @@ import {
13
14
const isVoiceTranscriptionError = Schema.is(VoiceTranscriptionError);
15
15
-function getDeviceLocale(): string {
16
- return Intl.DateTimeFormat().resolvedOptions().locale;
16
+/** The user's ordered Language & Region list, then the app locale; the app ships in English only. */
17
+function getPreferredLocales(): string[] {
18
+ const languages: unknown = Settings.get("AppleLanguages");
19
+ const preferred = Array.isArray(languages)
20
+ ? languages.filter(
21
+ (language): language is string => typeof language === "string" && language.length > 0,
22
+ )
23
+ : [];
24
+ return [...new Set([...preferred, Intl.DateTimeFormat().resolvedOptions().locale])];
25
}
26
27
function wrapError(
@@ -37,23 +45,40 @@ function getNativeErrorCode(error: unknown): string | undefined {
45
}
46
47
export async function getLocalVoiceTranscriber(): Promise<VoiceTranscriber | null> {
40
- const locale = getDeviceLocale();
41
- if (!AppleTranscription.isAvailable(locale)) return null;
42
- return { prepare: (options) => prepareVoiceTranscription(locale, options) };
48
+ const locales = getPreferredLocales();
49
+ // Availability is a device and OS check; which languages have a model only `prepare` knows.
50
+ if (!AppleTranscription.isAvailable(locales[0]!)) return null;
51
+ return { prepare: (options) => prepareVoiceTranscription(locales, options) };
52
}
53
54
async function prepareVoiceTranscription(
46
- locale: string,
55
+ locales: readonly string[],
56
{ signal }: VoiceTranscriptionOptions,
57
): Promise<PreparedVoiceTranscription> {
58
throwIfVoiceTranscriptionAborted(signal);
50
- if (!AppleTranscription.isAvailable(locale)) {
59
+ if (!AppleTranscription.isAvailable(locales[0]!)) {
60
throw new VoiceTranscriptionError({
61
code: "unavailable",
62
message: "Voice transcription requires a supported device with iOS 26 or later.",
63
});
64
}
65
66
+ let unsupported: VoiceTranscriptionError | undefined;
67
+ for (const locale of locales) {
68
+ try {
69
+ return await prepareLocale(locale, signal);
70
+ } catch (error) {
71
+ if (!isVoiceTranscriptionError(error) || error.code !== "unsupported-locale") throw error;
72
+ unsupported = error;
73
+ }
74
+ }
75
+ throw unsupported!;
76
+}
77
+
78
+async function prepareLocale(
79
+ locale: string,
80
+ signal: AbortSignal,
81
+): Promise<PreparedVoiceTranscription> {
82
try {
83
const supportedLocale = await AppleTranscription.prepare(locale);
84
throwIfVoiceTranscriptionAborted(signal);
@@ -66,7 +91,7 @@ async function prepareVoiceTranscription(
91
if (getNativeErrorCode(error) === "AppleTranscriptionUnsupportedLocale") {
92
throw new VoiceTranscriptionError({
93
code: "unsupported-locale",
69
- message: "Voice transcription does not support this device language.",
94
+ message: "Voice transcription does not support any of your languages.",
95
cause: error,
96
});
97
}
docs/user/composer.md
+5
-2
@@ -206,8 +206,11 @@ switches hosts. Choose **This device** to revoke access and discard pending audi
206
On Android, keep T3 Code open while recording and transcribing.
207
208
On-device dictation may need a network connection to download a speech model the
209
-first time. After that it works offline for that language. Android transcribes on
210
-the device while you record and finishes after you stop. Recordings can be up to five
209
+first time. After that it works offline for that language. iPhone dictates in the
210
+first of your preferred languages (**Settings → General → Language & Region**)
211
+that Apple’s speech model supports. If none is supported, it tries the app’s
212
+language. Android transcribes on the device while you
213
+record and finishes after you stop. Recordings can be up to five
214
minutes long. Canceling or an audio interruption discards the recording and
215
preserves your existing draft. Navigating to another screen keeps dictation active;
216
use the floating controls to finish or cancel. While recording, the screen stays