language-fixer

Language Fixer

A flexible macOS utility that retroactively fixes text typed in the wrong keyboard layout. Supports multiple language pairs with configurable hotkeys.

https://github.com/user-attachments/assets/8c7ab90d-cf3f-4473-849a-c14cefea8278

Features

• Multiple Language Support: Hebrew, Arabic, Russian, or create your own
• Configurable Hotkeys: Each language pair can have its own hotkey
• Toggle-Back: Press hotkey again to revert the conversion
• Smart Detection: Automatically detects the source language
• Seamless Integration: Runs quietly in the background
• Configurable Buffer: Adjust how long typed text is remembered
• RTL Support: Properly handles right-to-left text

Requirements

• macOS (tested on macOS 10.14+)
• Python 3.9+

Installation

Option 1: Install with pipx (Recommended)

pipx is the cleanest way to install Python CLI tools:

# Install pipx if you don't have it
python3 -m pip install --user pipx
python3 -m pipx ensurepath

# Close and reopen your terminal, then:
pipx install language-fixer

# Initialize configuration
lang-fix init

# Install as background service
lang-fix service install

Option 2: Install with pip

pip3 install language-fixer

# Initialize configuration
lang-fix init

# Install as background service
lang-fix service install

Note: If you use pip, you may need to add Python's bin directory to your PATH:

export PATH="$HOME/Library/Python/3.9/bin:$PATH"

Add this to your ~/.zshrc or ~/.bash_profile to make it permanent.

Grant Permissions (Important!)

macOS requires TWO permissions for the keyboard listener to work.

First, find the exact Python path to grant permissions to:

lang-fix doctor

This shows the exact Python executable path (e.g., /opt/homebrew/bin/python3 for pipx installations).

Then grant permissions:

1. Input Monitoring (will prompt automatically when first run)

• System Preferences → Security & Privacy → Input Monitoring
• Add the Python path shown by lang-fix doctor

2. Accessibility (must enable manually)

• System Preferences → Security & Privacy → Accessibility
• Click lock to make changes
• Click + and navigate to the Python path
• Add the executable and enable the checkbox

After granting both permissions, restart the service:

lang-fix service restart

Troubleshooting: If conversion doesn't work, run lang-fix doctor to verify the correct Python path is granted permissions.

Option 2: Install from Source

• Clone the repository:

  git clone https://github.com/yourusername/language-fixer.git
  cd language-fixer
  

• Install with uv:

  uv sync
  

• Grant accessibility permissions (same as above)

• Install as service (optional):

  ./scripts/install.sh
  

Quick Start

After installation, initialize the configuration:

lang-fix init

This creates config and mappings in ~/.config/language-fixer/ with Hebrew-English support by default.

Then install as a service:

lang-fix service install

Grant permissions (see Permissions section above), restart, and you're done!

lang-fix service restart

Type in the wrong language and press Cmd+Option+H to fix!

CLI Commands

Language Fixer provides both lang-fix (short) and language-fixer (long) commands:

Setup Commands

# Initialize configuration (first time setup)
lang-fix init

# Diagnose installation and show permission instructions
lang-fix doctor

# View available mappings
lang-fix mapping list

# Create custom language mapping
lang-fix mapping create

# View config file
lang-fix config

# Edit config file
lang-fix config --edit

# Show config file path
lang-fix config --path

Service Management

# Install as background service
lang-fix service install

# Check service status
lang-fix service status

# Restart service (after config changes or granting permissions)
lang-fix service restart

# Stop service
lang-fix service stop

# Uninstall service
lang-fix service uninstall

Run Manually

# Run in foreground (for testing)
lang-fix run

Configuration

Language Fixer stores configuration in ~/.config/language-fixer/:

• config.yaml - Main configuration file
• mappings/ - Language mapping files

Default Configuration

After running lang-fix init, you get Hebrew-English support:

buffer_timeout: 10.0

language_pairs:
  - name: "Hebrew-English"
    mapping_file: "~/.config/language-fixer/mappings/hebrew-english.json"
    hotkey: "cmd+alt+h"
    enabled: true

Adding More Languages

Edit ~/.config/language-fixer/config.yaml:

buffer_timeout: 10.0

language_pairs:
  - name: "Hebrew-English"
    mapping_file: "~/.config/language-fixer/mappings/hebrew-english.json"
    hotkey: "cmd+alt+h"
    enabled: true

  - name: "Arabic-English"
    mapping_file: "~/.config/language-fixer/mappings/arabic-english.json"
    hotkey: "cmd+alt+a"
    enabled: true

  - name: "Russian-English"
    mapping_file: "~/.config/language-fixer/mappings/russian-english.json"
    hotkey: "cmd+alt+r"
    enabled: true

Create Custom Mapping

lang-fix mapping create

This will:

• Ask for language pair details (e.g., "Spanish-English")
• Guide you through mapping each keyboard key
• Save to ~/.config/language-fixer/mappings/your-language.json
• Show you how to add it to config

All languages work exactly the same way!

Usage Examples

Basic Usage

• Type text in wrong language: akuo (meant to type שלום)
• Press Cmd+Option+H
• Text converts to: שלום

Toggle Back

• Type: hello → Press Cmd+Option+H → Converts to: יקךךם
• Press Cmd+Option+H again (immediately) → Reverts to: hello

Multiple Languages

With config enabled for multiple languages:

• Cmd+Option+H for Hebrew-English
• Cmd+Option+A for Arabic-English
• Cmd+Option+R for Russian-English

Viewing Logs

If you need to troubleshoot:

# View error logs
tail -f /tmp/languagefixer.err

# View output logs
tail -f /tmp/languagefixer.out

How It Works

Language Fixer monitors your keyboard input and maintains a buffer of recently typed characters. When you press a hotkey:

• Detects the source language of the buffered text
• Maps each character to its equivalent on the target keyboard layout
• Deletes the original text
• Pastes the converted text

The conversion is based on physical keyboard positions, so each key maps to its equivalent character in the other language.

Uninstallation

For pipx installation:

lang-fix service uninstall
pipx uninstall language-fixer

For pip installation:

lang-fix service uninstall
pip3 uninstall language-fixer

Remove configuration (optional):

rm -rf ~/.config/language-fixer

Development

Running tests

uv run pytest

Project structure

language-fixer/
├── src/language_fixer/
│   ├── __init__.py
│   ├── cli.py                # Main CLI interface
│   ├── config.py             # Configuration management
│   ├── converter.py          # Text conversion logic
│   ├── listener.py           # Keyboard listener
│   ├── generate_mapping.py   # Mapping generator tool
│   └── install_service.py    # Service installation
├── mappings/
│   ├── hebrew-english.json
│   ├── arabic-english.json
│   └── russian-english.json
├── tests/
│   ├── test_converter.py
│   └── test_listener.py
├── scripts/                  # Legacy scripts for source installation
├── pyproject.toml
└── README.md

License

MIT License - see LICENSE file for details

Troubleshooting

The hotkey doesn't work:

• Make sure you've granted Accessibility permissions to your terminal app
• Try restarting the application
• Check that your hotkey doesn't conflict with other apps

Text isn't converting correctly:

• The buffer has a timeout (default 10 seconds) - press the hotkey within this window
• The converter works on buffered text only - if you've pressed Enter, Tab, or arrow keys, the buffer is cleared

Service won't start:

• Check the error logs: cat /tmp/languagefixer.err
• Make sure uv is installed and in your PATH
• Verify the paths in ~/Library/LaunchAgents/com.languagefixer.plist are correct

Config file errors:

• Make sure PyYAML is installed: uv sync
• Check your config.yaml syntax is valid YAML
• Verify mapping file paths are correct and files exist

Custom mapping not working:

• Ensure the mapping file is valid JSON
• Check that the mapping file path in config.yaml is correct
• Make sure the language pair is enabled in config

Contributing

Contributions are welcome! Feel free to:

• Add new language mappings
• Report bugs
• Suggest features
• Submit pull requests

Roadmap

Future improvements:

• Visual feedback when conversion happens
• App-specific exclusions
• Smart word boundary detection
• Additional platform support