Skip to content

Localization settings for macOS VMs (language, region, time zone, keyboard) and layout-aware typing #42

Open

Description

@digitall-it

Description

Let users and agents choose a VM's localization, and make text input work with any keyboard layout.

  1. 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
  2. Agent access to the same settings, for example a vmpal_set_localization tool or a localization section in vmpal_status. It would run through VMPal Tools, so no admin password or System Settings dialog is needed.
  3. Layout-aware text input in vmpal_act type:
    • map each character to the keys of the active layout, including dead keys and Option combinations;
    • or offer a Unicode text injection method (the auto method) that works with any layout and any language.
  4. Reliable layout detection at startup, so typing.layout is never "not known yet".
  5. (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 use vmpal_exec_admin. The System Settings route stops at the password dialog.
  • Non-English text can't be typed.
    • On the US layout, type refuses 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_status reports typing.layout: "not known yet (US until VMPal reads it)" and typing.methods: ["keys"].

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

  1. nangtrongvuon commented on Oct 12, 2026

    @nangtrongvuon
    Collaborator

    Hi, thank you for the suggestions, we're working on it

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions