Skip to content

README_EN.md

Latest commit

 

History

History
179 lines (137 loc) · 7.17 KB

README_EN.md

File metadata and controls

179 lines (137 loc) · 7.17 KB

MacVimSwitch

Except for the code from macism, all other parts of this project are generated by AI, as I don't know Swift.

中文 | English | 日本語 | 한국어

MacVimSwitch is a utility for macOS that automatically switches input sources, designed specifically for Vim users and those who frequently switch between CJKV(Chinese/Japanese/Korean/Vietnamese) input methods. Thx to macism for the input method switching solution.

Features

  • Automatically switches to ABC input method when pressing ESC
  • Optional jk chord to trigger the same ESC switching, matching common Vim insert-mode mappings
  • Built-in Shift key switching feature (enabled by default), switch between ABC English input method and Chinese/Japanese/Korean/Vietnamese input method
    • Important: Before using, please disable the "Use Shift to switch between English and Chinese/Japanese/Korean/Vietnamese" option in your input method settings
    • Can be disabled in the status bar menu if needed
  • If you don't want to use Shift key switching, on Mac, CapsLock short press to switch input method, long press for caps lock
  • Runs in the background with a status bar icon
  • Auto-starts on system login (can be disabled from menu bar)
  • Recommend: Use inputsource.pro to automatically switch input method for each application. You can set a default input method for each application, for example, set the default input method to English in the browser and to Chinese in Vim.
Image

Known Issues

1. Insert Mode Input Method Switching

When switching back to insert mode from normal mode, it cannot automatically switch back to the previous input method - it defaults to English. See issue

My personal solution is to press shift to switch back to Chinese. After getting used to it, it works fine, especially since it's quite common to stay in English input method when entering insert mode for coding.

2. Accessibility Permission Required After Updates

Issue: After downloading a new version of MacVimSwitch, you need to re-grant accessibility permissions

Reason: The app uses self-signing (rather than an Apple Developer certificate), so each build has a different signature identity. macOS treats it as a different application, requiring re-authorization

Solution Steps:

  1. Open System Settings → Privacy & Security → Accessibility
  2. Remove the old MacVimSwitch entry (click the - button)
  3. Add the new MacVimSwitch (click the + button and select the new version)
  4. Ensure the toggle is enabled
  5. Restart the MacVimSwitch app

Future Plan: If someone kind would sponsor an Apple Developer account ($99/year), I'll sign with an official certificate so updates won't require re-authorization 😄

Installation

Download from GitHub Releases and install it manually.

Usage

  1. First Launch:

    • Unzip and open MacVimSwitch
    • Grant Accessibility permissions when prompted
    • Go to System Preferences → Security & Privacy → Privacy → Accessibility
    • Add and enable MacVimSwitch
    • Restart the app

  2. Important first-time setup:

    • Disable the "Use Shift to switch between English and Chinese" option in your input method settings
    • You can select your preferred Chinese input method from the status bar menu
    • You must enable the MacOS keyboard shortcut for "Select the previous input source", which can be found in "Preference -> Keyboard -> Shortcuts -> Input Source".
    • The shortcut can be anything as your wish, macism will read the shortcut from that entry and trigger it by emulation when needed. Just to make sure you have already enabled the shortcut.

  3. Menu Bar Options:

    • Click the keyboard icon in the menu bar to:
      • View instructions
      • Select your preferred Chinese input method
      • Enable/Disable Shift key switching
      • Enable/Disable jk ESC mode
      • Select the applications that you want to enable Esc to switch input source, by default, vscode, terminal, obsidian, cursor, windsurf, warp are enabled.
      • Enable/Disable launch at login
      • Quit the application

Why MacVimSwitch?

MacVimSwitch offers several advantages over other input source switching solutions:

  1. Universal Compatibility

    • Works across all applications (VSCode, Terminal, Obsidian, Cursor, etc.)
    • No need for application-specific configurations
    • No plugins required for different editors

  2. Input Method Agnostic

    • Works with any Chinese/Japanese/Korean/Vietnamese input method
    • Supports popular input methods like Sogou, iFlytek, WeChat Input, etc.
    • Easy to switch between different input methods

  3. Flexible Switching Options

    • Use Shift key for quick switching (enabled by default)
    • Or use CapsLock if you prefer (macOS built-in feature)
    • ESC key always switches to ABC input method (perfect for Vim users)

Input Method Switching Options

  1. Using Shift (Default)

    • Quick and convenient
    • Similar to CapsLock behavior
    • Can be disabled if not needed

  2. Using CapsLock (Built-in macOS Feature)

    • System-level feature
    • Short press to switch input methods
    • Long press for caps lock
    • Works alongside MacVimSwitch

Choose the method that best suits your workflow!

For Developers

How to Release

  1. Create GitHub Repository Create a new repository at github.com/jackiexiao/macvimswitch
  2. Clone and initialize the repository
git clone https://github.com/jackiexiao/macvimswitch.git
cd macvimswitch
  1. Release
Tag the release
git tag -a v1.0.0
git push origin v1.0.0
  1. Formula
bash
1. Create a new repository: github.com/jackiexiao/homebrew-tap (if not exists)
2. Clone the repository

git clone https://github.com/jackiexiao/homebrew-tap.git cd homebrew-tap

3. Update the SHA256 in macvimswitch.rb with the one from GitHub Release
4. Commit and push the formula
git add macvimswitch.rb
git commit -m "Update MacVimSwitch formula to v1.0.0"
git push origin main
  1. Apply for a tap

Development

To build and test locally:

./build.sh
pkill -f MacVimSwitch
./dist/MacVimSwitch.app/Contents/MacOS/MacVimSwitch
# first, open MacVimSwitch, delete permissions
open dist/MacVimSwitch.app
# second, open MacVimSwitch, allow permissions
open dist/MacVimSwitch.app
# third, open MacVimSwitch, now it works
open dist/MacVimSwitch.app

Build for release

./build.sh --create-dmg
tccutil reset All com.jackiexiao.macvimswitch # Reset permissions
# open MacVimSwitch.dmg

Contributing

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add some amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

  • macism for the input method switching solution