Repository navigation
Localization settings for macOS VMs (language, region, time zone, keyboard) and layout-aware typing #42
Description
Description
Let users and agents choose a VM's localization, and make text input work with any keyboard layout.
- Localization options when a VM is created and in its settings, applied by VMPal:
- UI language and preferred language order
- Region and locale, including currency
- Date format, 24-hour clock, first day of the week
- Measurement units and temperature
- Time zone, or automatic from the host
- Keyboard layouts and input sources, plus which one is active
- Optionally: copy all of these from the host in one click
- Agent access to the same settings, for example a
vmpal_set_localizationtool or alocalizationsection invmpal_status. It would run through VMPal Tools, so no admin password or System Settings dialog is needed. - Layout-aware text input in
vmpal_acttype:- map each character to the keys of the active layout, including dead keys and Option combinations;
- or offer a Unicode text injection method (the
automethod) that works with any layout and any language.
- Reliable layout detection at startup, so
typing.layoutis never "not known yet". - (Smaller) Language-independent targets in
vmpal_act: text targets currently depend on the UI language ("Save" vs "Salva"). Targeting by accessibility role or identifier would make agent scripts reusable across locales.
Environment: host Apple M2 Max, macOS 27.0.1. Guest macOS 27.0.1 (26A434), VMPal Tools 0.37.
Why this feature/change is important?
Setting up a VM for a non-US user is a manual, multi-step job today, and part of it is impossible for an agent driving the VM through the MCP tools.
- Wrong defaults. A new VM starts as
en_US, with time zone US/Pacific and the "ABC" (US) layout. Language, region, formats and time zone all had to be fixed by hand. - Time zone needs an admin password. With
adminExecutionAvailable: false, the agent can't usevmpal_exec_admin. The System Settings route stops at the password dialog. - Non-English text can't be typed.
- On the US layout,
typerefuses accented letters, even though macOS produces them with dead keys:A US keyboard can't type "è", "È", "é": leave them out, or type them another way in the VM.
- After switching the guest to "Italian - Pro", VMPal detects the layout but refuses to type any text, even plain ASCII:
This VM's keyboard layout is com.apple.keylayout.Italian-Pro, and VMPal types text as a US keyboard does, so it would type other characters.
- The only workarounds are pressing physical keys one at a time (which requires knowing where every character sits on that layout) or pasting from the clipboard.
vmpal_statusreportstyping.layout: "not known yet (US until VMPal reads it)"andtyping.methods: ["keys"].
- On the US layout,
In practice, users who don't work in US English must choose between a correctly localized VM and an agent that can type in it. Built-in localization settings and layout-aware input would remove that trade-off for every non-US user. That includes anyone testing localized apps or websites, where dates, currencies and text input are exactly what needs checking.
Activity
nangtrongvuon commentedon Oct 12, 2026
Hi, thank you for the suggestions, we're working on it