Best practices for handling global hotkeys and custom shortcuts across non-Latin keyboard layouts?

Anumey Sharma 20 Reputation points
2026-05-08T06:20:10.1233333+00:00

Hi everyone,

I'm currently working on a Windows desktop application (using C++ and WinUI 3), and we are building a multi-lingual system for global hotkeys and user-customizable keyboard shortcuts.

I'm running into a design blocker when dealing with pure non-Latin keyboard layouts (like Arabic, Cyrillic, CJK, etc.), and I'm hoping to get some clarity on Microsoft's recommended approach here.

The Problem: Most universal shortcuts rely on English/Latin virtual key codes. For example, Ctrl + P for Print translates to VK_CONTROL + VK_P.

However, if a user is typing on a pure Arabic physical or virtual keyboard, there is no physical 'P' key, nor is there a phonetic equivalent.

My questions are:

Handling Default Shortcuts: How does the Windows input stack expect us to handle a default binding like Ctrl + P when the active input locale (HKL) lacks that character entirely? Are we expected to map these to the physical layout via Hardware Scan Codes, or should we be dynamically translating them using something like VkKeyScanEx / MapVirtualKeyEx? We want to avoid forcing the user to toggle back to an English layout just to trigger a hotkey.

Saving Custom Hotkeys: We also want users to be able to bind their own custom actions. When a user presses a combination on a non-Latin keyboard to assign a shortcut, what is the standard data point we should serialize to disk? Should we save the Hardware Scan Code (to lock it to the physical key location), the localized Virtual Key code, or the Unicode character?

Recommended APIs: Are there specific input APIs or framework paradigms (like RegisterHotKey, Accelerator Tables, or InputBinding) that are considered the most reliable for this kind of heavy localization?

If anyone has tackled this specific localization issue before, any guidance or documentation pointers would be greatly appreciated.

Thanks!

Windows development | WinUI
0 comments
Answer accepted by question author
Nancy Vo (WICLOUD CORPORATION) 8,155 Reputation points Microsoft External Staff Moderator
2026-05-08T10:13:32.81+00:00

Hello @Anumey Sharma ,

Thanks for your question.

Handling detail shortcuts:

I recommend designing your shortcuts around Virtual Key + modifier combinations, not scan codes or Unicode characters. Windows keyboard layouts are built to map physical keys to virtual keys, then to characters — so defining shortcuts as VK + modifier and letting the active layout handle how those are produced is the correct approach. For non-Latin locales, follow language-specific conventions rather than forcing Latin equivalents. For IME-based languages like Japanese where no Latin equivalent exists, Microsoft recommends keeping the original Latin shortcuts and relying on user familiarity. Use MapVirtualKeyEx and GetKeyboardLayout when you need explicit layout awareness at runtime.

Saving custom hotkeys:

I suggest persisting the Virtual Key + modifier as your primary representation, not Unicode characters. Characters are the result of layout + state and are not stable identifiers across layouts. If a user switches input language between sessions, a stored character may become unresolvable. Store scan codes only when the explicit intent is physical-position binding regardless of layout, such as game controls. Do not use Unicode characters as the primary key for shortcuts under any circumstance.

Recommended APIs:

I recommend using RegisterHotKey for global scope and KeyboardAccelerator for in-app scope. Drop Accelerator Tables entirely for new WinUI 3 work.

I hope this addresses your question. If this response was helpful, please consider following the guidance to provide feedback.

Was this answer helpful?

1 person found this answer helpful.
0 comments

1 additional answer

Sort by: Most helpful
Most helpful Newest Oldest

  1. AI answer

    2026-05-08T06:20:30.1833333+00:00

    Windows keyboard input and shortcuts are defined in terms of virtual keys and keyboard layouts, not characters. For multilingual and non‑Latin layouts, the recommended approach is to design around virtual keys and layouts, and only fall back to scan codes when character‑independent behavior is required.

    Handling default shortcuts (for example, Ctrl+P)

    1. Shortcuts should be defined in terms of virtual keys, not characters.
      • Windows keyboard layouts map physical keys (scan codes) to virtual keys and then to characters for a given input language and layout.
      • A keyboard layout “determines the character values generated by pressing those keys and key combinations” and “each layout identifies the current input language and determines which character values are generated by which keys and key combinations.”
      • Applications are generally not expected to manipulate input languages directly; users configure language/layout combinations and switch among them. When focus moves to text of a different language, applications can call ActivateKeyboardLayout to activate the user’s default layout for that language.
    2. For common commands, follow language‑specific conventions instead of forcing English letters.
      • Actions such as saving, copying, or bold formatting are common across apps. “By convention, applications in a single language use the same shortcut for the same action.”
      • “Applications in a language other than English might use a different shortcut than the English shortcut but be consistent in the use of that shortcut. For example, the shortcut for applying bold formatting is Ctrl+B in English and Ctrl+G in French.”
      • For non‑Latin locales that require an IME (for example, Japanese), “it’s best to use the original keyboard shortcuts,” meaning the Latin‑key conventions are often kept.
    3. For layouts where a Latin letter is not present at all:
      • Treat the shortcut as a virtual key combination that may or may not be reachable on that layout. If the target language uses a non‑Latin writing system with an IME, keep the original shortcuts (for example, Ctrl+P) and document them.
      • Do not remap system‑wide conventions arbitrarily to other characters; instead, localize shortcuts in coordination with localization teams so that they choose appropriate keys per language.
    4. Avoid relying on scan codes for general shortcuts.
      • Scan codes are layout‑independent and are useful “when you need to know which key is pressed regardless of the current keyboard layout,” for example, WASD in games to preserve physical positions across US QWERTY and French AZERTY.
      • For typical application commands, use virtual keys and let the active layout define how those are produced.

    Saving custom hotkeys

    1. Persist virtual key + modifier combinations, not characters.
      • Keyboard shortcuts (accelerators) are defined as “key combinations that consist of two kinds of keys: modifiers and nonmodifiers.” Modifiers include Shift/Ctrl; nonmodifiers include alphanumeric keys, Delete, Spacebar, and so on.
      • Persist the virtual key (for example, VK_F5, VK_OEM_1, etc.) plus modifiers (Ctrl/Alt/Shift) as the primary representation.
    2. Use scan codes only when the intent is to bind to physical key locations.
      • The guidance notes that scan codes “might be required in specific cases when you need to know which key is pressed regardless of the current keyboard layout,” with WASD as the example.
      • If the design explicitly wants “this physical key regardless of layout,” store the scan code as well. Otherwise, prefer virtual keys so that the shortcut respects the user’s active layout.
    3. Do not store Unicode characters as the primary key for shortcuts.
      • Characters are the result of layout + modifiers + state (for example, IME), and are not stable identifiers for shortcuts across layouts.
    4. Localization of shortcuts requires explicit planning.
      • “When the names of actions are localized, you should also update the shortcut keys to maintain the ease of use.”
      • Localizing keyboard shortcuts involves: exposing shortcuts to localization, coordinating between development and localization, ensuring the localization team has enough context to choose appropriate shortcuts, and verifying that shortcuts are functional and not duplicated.

    Recommended APIs and patterns

    1. Use standard keyboard events and accelerator mechanisms.
      • In WinUI 3 (Windows App SDK), keyboard input is handled via Microsoft.UI.Xaml.UIElement events such as KeyDown, KeyUp, and CharacterReceived. This replaces the UWP CoreWindow model and allows handling at the control level.
      • Keyboard accelerators (shortcut keys) are the standard way to define shortcut key combinations. They are defined as modifier + nonmodifier virtual keys.
    2. Use layout APIs when layout awareness is needed.
      • GetKeyboardLayout / GetKeyboardLayoutList to inspect active layouts.
      • ActivateKeyboardLayout to set the input language for the current task.
      • LoadKeyboardLayout to load layouts and optionally activate or reorder them. Use flags such as KLF_ACTIVATE, KLF_REORDER, KLF_SUBSTITUTE_OK, and for multilingual scenarios KLF_REPLACELANG / KLF_NOTELLSHELL as described.
      • GetKeyboardLayoutName to retrieve the name of the active layout (note that it may not distinguish different layouts with the same primary language; use GetKeyboardLayout for input language identification).
    3. Follow keyboard shortcut design guidelines.
      • Do not distinguish between key locations (left/right Shift, Ctrl, etc.) for shortcuts; assigning behavior to only one location is “confusing and unexpected.”
      • Do not use the Windows logo key or Application key as shortcut modifiers.
      • Do not use Alt+alphanumeric combinations for shortcut keys, as they may conflict with access keys.
      • Avoid complex combinations (three or more keys) and avoid Ctrl+Alt combinations because some language versions interpret Ctrl+Alt as AltGr, which generates characters.
      • Do not use characters like @ $ {} [] \ ~ | ^ ' < > for shortcut keys, because they require different key combinations across languages or are locale‑specific.
    4. Localization‑specific guidance for shortcuts.
      • For Latin‑based locales: localize shortcuts so that they use the first character of the localized action name or another mnemonic character, and ensure consistency with other applications in that language.
      • For non‑Latin locales requiring IMEs (for example, Japanese): “it’s best to use the original keyboard shortcuts,” meaning keep the Latin‑based shortcuts and rely on users’ familiarity with them.

    Summary design pattern

    • Represent shortcuts internally as (modifiers + virtual key).
    • For physical‑position‑based bindings (for example, game controls), additionally store scan codes.
    • Do not store Unicode characters as the primary identifier for shortcuts.
    • Use WinUI 3 UIElement keyboard events and keyboard accelerators for implementation.
    • Use keyboard layout APIs only when layout awareness is required; otherwise let the user’s configured layouts and conventions drive how virtual keys are produced.
    • Coordinate shortcut localization with localization teams; follow per‑language conventions and keep Latin shortcuts for IME‑based non‑Latin languages.

    References:

    AI-generated content may be incorrect. Read our transparency notes for more information.

    Was this answer helpful?

Your answer

Answers can be marked as 'Accepted' by the question author and 'Recommended' by moderators, which helps users know the answer solved the author's problem.