Akshara for macOS

A lightweight, ultra-fast, clean-room native Sinhala Input Method Engine (IME) designed specifically for modern macOS.

Akshara brings seamless, high-performance Sinhala typing to macOS. Built from the ground up utilizing Apple's native InputMethodKit (IMK), Carbon TIS (Text Input Source), and SwiftUI, Akshara delivers zero-latency inline text composition without background daemons, memory leaks, or privacy concerns.

Whether you prefer rapid Smart Phonetic, standard Singlish Phonetic, or traditional SLS 1134 (Wijesekara) layout with real-time visual kombuva reordering, Akshara caters to writers, developers, translators, and everyday users alike.

• Zero-Latency Native IME: Engineered in native Objective-C and Swift for instant keystroke processing.
• Three Distinct Input Modes:
  • Akshara - Smart Phonetic: Grammar-correct phonetic typing, with dictionary spelling and suggestions.
  • Akshara - Phonetic: Classic romanized Sinhala transliteration.
  • Akshara - Wijesekara (SLS 1134): Full compliance with Sri Lanka standard SLS 1134 keyboard layout with live visual-to-Unicode reordering.
• Interactive Wijesekara Keyboard Viewer: Live macOS on-screen keyboard viewer with interactive Shift & Option layer visualization.
• Quick Guide & Cheat Sheet: Instant access to phonetic rules and vowel signs directly from the macOS input menu bar.
• Settings App: Akshara Settings in Launchpad / Apps (or Settings… in the input menu): spelling options, suggestions, double-space period, the setup and typing guides, and About.
• Double-Space Period: Pressing Space twice automatically inserts . across all input modes.
• Built-in Auto Updater: Background release checks and convenient in-app update prompts via GitHub Releases.
• Clean, Secure & Private: Fully sandboxed with no analytics, keylogging, telemetry, or external network requests.

┌──────────────────────────────────────┬─────────────────────────────────────────────────────────────┐
│ Input Source (System Settings)       │ Description                                                 │
├──────────────────────────────────────┼─────────────────────────────────────────────────────────────┤
│  Akshara - Smart Phonetic            │ Grammar-correct phonetic typing (e.g. 'honda' ➔ 'හොඳ')      │
│  Akshara - Phonetic                  │ Classic romanized Sinhala transliteration                   │
│  Akshara - Wijesekara (SLS 1134)     │ Standard Wijesekara layout with live vowel reordering       │
└──────────────────────────────────────┴─────────────────────────────────────────────────────────────┘

Smart Phonetic spells Sinhala the grammar-correct way: by the rules of Sinhala orthography from the Sinhala Phonetic Orthography research, the same engine as the Akshara Android keyboard. Hal, yansaya, rakaransaya and ං are written for you, and a bundled word list picks the dictionary spelling of letters that sound alike.

The classic Smart Phonetic keys (d ➔ ඩ, dh ➔ ද …) are one switch away: turn off Grammar-correct Smart Phonetic in the input menu or in Settings….

ai and au are two vowels: ai ➔ අයි, au ➔ අවු. Between vowels the glide is written for you.

A sanyaka letter never starts a word, so zga types ග; inside a word, kazda ➔ කඳ.

• Hal (◌්): written for a consonant with no vowel (k ➔ ක්).
• Gayanukitta (ෘ / ෲ): kru / kR ➔ කෘ, kruu / kRR ➔ කෲ.
• Anusvaraya (ං): x, M or zn (siMhala ➔ සිංහල), and n before k / g (ganga ➔ ගංග).
• Visargaya (ඃ): H (duHkha ➔ දුඃඛ).
• Yansaya and rakaransaya: automatic (kya ➔ ක්‍ය, kra ➔ ක්‍ර); after ම න ල, r keeps a plain hal (dumriya ➔ දුම්රිය).
• Repaya: karma ➔ කර්ම.

• Space picks the dictionary spelling of letters that sound alike: honda ➔ හොඳ, bada ➔ බඩ, lamaya ➔ ළමයා. Backspace right after puts back what you typed.
• Suggestions under the word show sound-alikes and completions; pick one with 1–5 or a click.
• Settings… (input menu) has the spelling options: rakaransaya + u (kruura ➔ ක්‍රූර), joined repaya (කර්‍ම), classical conjuncts (අක්‍ෂර) and archaic letters, plus suggestions and double-space period.
• Double Space: Pressing Space twice inserts a full stop (. ).

Provides standard romanized Sinhala transliteration:

• amma ➔ අම්ම
• mama ➔ මම
• sri ➔ ස්රි
• siMhala ➔ සිංහල
• aa, ae, ii, uu, ee, ai, oo, au produce extended and compound vowels.
• Use M for anusvara (ං) and H for visarga (ඃ).

Full adherence to the official Sri Lanka Standard SLS 1134 specification with automated visual-to-Unicode order transposition:

• Visual Order Composition: Type kombuva first, then the consonant — Akshara reorders them into canonical Unicode order seamlessly:
  • ෙ + ක + ා ➔ කො
  • ෙ + ක + ා + ් ➔ කෝ
  • ෙ + ක + ් ➔ කේ
  • ෙ + ක + ෟ ➔ කෞ
  • ෙ + ෙ + ක ➔ කෛ
  • ෙ + ෙ + ක + ෙ ➔ කෛ plus a pending kombuwa for the next syllable
  • අ + ැ ➔ ඇ
  • අ + ා ➔ ආ
  • ඉ + ී ➔ ඊ
  • උ + ූ ➔ ඌ
  • එ + ් ➔ ඒ
  • ඔ + ් ➔ ඕ

The SLS mode also supports the public Wijesekara/SLS control symbols for yansaya, rakaransaya, repaya, join/touching letters, sanyakaya forms, visargaya, kunddaliya, non-breaking/invisible spaces, and common AltGr entries.

1. Download the latest Akshara.pkg installer from the Releases page.
2. Run the installer package and follow the setup wizard.
3. Open System Settings ➔ Keyboard ➔ Input Sources, click Edit... (or +), search for Sinhala, and add Akshara.

• macOS 12.0 (Monterey) or later
• Xcode Command Line Tools (xcode-select --install)
• Apple Developer ID certificates (only required for signed release packages)

# Clone the repository
git clone https://github.com/AksharaOrg/akshara-mac.git
cd akshara-mac

# Build the app bundle (staged at dist/Akshara.app)
./script/build_and_run.sh

# Install locally
./script/install.sh

Then log out and back in, or restart the macOS Text Input system:

killall TextInputMenuAgent

Open System Settings, add an input source for Sinhala, and select one of the Akshara modes.

1. Open System Settings (or System Preferences on older macOS versions).
2. Navigate to Keyboard ➔ Text Input ➔ Input Sources (Click Edit...).
3. Click the + button at the bottom left.
4. Select Sinhala (සිංහල) from the language list.
5. Select your desired input source:
   • Akshara - Smart Phonetic
   • Akshara - Phonetic
   • Akshara - Wijesekara
6. Click Add. Switch between input sources anytime using ⌃ Control + Space or via the menu bar input menu!
7. Open Akshara Settings from Launchpad / Apps or Spotlight for settings and the typing guides.

The project includes build and maintenance scripts in script/:

# Run unit & transliteration tests (including 500-word SLS lexicon stress test)
./script/test.sh

# Validate the required install/build prerequisites before packaging
./script/validate_install.sh

# Build the app bundle to dist/Akshara.app
./script/build_and_run.sh build

# Build and test run immediately
./script/build_and_run.sh run

# Verify the installed app starts cleanly after install
./script/build_and_run.sh --verify

# Create a signed/distributable .pkg installer package
./script/package.sh

# Rebuild the app and menu-bar icons from support/IconSource
./script/generate_icons.sh

# Uninstall user-level installation
./script/uninstall.sh

# Uninstall system-wide package installation
./script/uninstall.sh --system

The uninstall script unregisters the input method and restarts the text-input services. Log out and back in if Akshara remains listed in Input Sources.

Build a distributable installer package:

./script/package.sh

The package is written to dist/Akshara-<version>-<arch>.pkg (the version comes from support/Info.plist unless AKSHARA_VERSION is set). It installs Akshara to /Library/Input Methods/Akshara.app and Akshara Settings to /Applications, registers the bundle with macOS, and restarts Text Input services. After installation, add Akshara - Wijesekara or Akshara - Phonetic from System Settings ➔ Keyboard ➔ Input Sources.

The local package is ad-hoc signed for development. For public distribution, sign the app with a Developer ID Application certificate, sign the package with a Developer ID Installer certificate, notarize it with Apple, and staple the notarization ticket.

Release signing is supported with environment variables:

AKSHARA_APP_SIGN_IDENTITY="Developer ID Application: Your Name (TEAMID)" \
AKSHARA_PKG_SIGN_IDENTITY="Developer ID Installer: Your Name (TEAMID)" \
AKSHARA_NOTARY_PROFILE="notarytool-profile-name" \
./script/package.sh

Omit AKSHARA_NOTARY_PROFILE to build a signed package without notarizing.

Pushing a tag such as v0.1.0 runs the signed-release workflow. It uses the protected release environment and requires these GitHub Actions secrets:

• MACOS_APP_SIGNING_CERTIFICATE_BASE64: a password-protected .p12 export of the Developer ID Application certificate and private key, Base64 encoded.
• MACOS_INSTALLER_SIGNING_CERTIFICATE_BASE64: the equivalent Developer ID Installer .p12 export.
• MACOS_CERTIFICATE_PASSWORD: the password used for both .p12 exports.
• APPLE_NOTARY_API_KEY_BASE64: a Base64-encoded App Store Connect API-key .p8 file with access to notarization.
• APPLE_NOTARY_KEY_ID and APPLE_NOTARY_ISSUER_ID: the matching API-key identifiers.

The workflow signs the app and installer, notarizes and staples the package, then publishes it as a GitHub Release asset. Keep the GitHub Environment restricted to trusted release approvers; never commit any of these values.

akshara-mac/
├── src/
│   ├── SinhalaInputController.m     # Core IMK input method controller & event loop
│   ├── SinhalaTransliterator.m      # SLS 1134 & Phonetic transliteration engine
│   ├── SmartPhoneticMaps.m          # Classic Smart Phonetic key maps
│   ├── SmartPhoneticV2.swift        # Grammar-correct Smart Phonetic (port of the research reference)
│   ├── SoundLexicon.swift           # Sound-alike dictionary lookup for Smart Phonetic
│   ├── SmartPhoneticService.swift   # Smart Phonetic settings, word list and Space choice
│   ├── Preferences.swift            # Other settings (suggestions, double-space period)
│   ├── SettingsView.swift           # SwiftUI Settings window
│   ├── SmartPhoneticV2Guide.swift   # Typing guide for grammar-correct Smart Phonetic
│   ├── WelcomeView.swift            # SwiftUI onboarding wizard & activation checker
│   ├── WelcomeWindowManager.swift   # NSWindow container for SwiftUI views
│   ├── PhoneticGuideView.swift      # Interactive menu bar guide
│   ├── AutoUpdater.m                # Background GitHub Releases update checker
│   └── main.m                       # App initialization, IMKServer entrypoint & akshara:// links
├── launcher/
│   └── main.swift                   # Akshara Settings: opens the input method's Settings (akshara://settings)
├── support/
│   ├── Info.plist                   # Input method bundle metadata and mode declarations
│   ├── Launcher/Info.plist          # Akshara Settings bundle metadata
│   ├── IconSource/                  # The Akshara icon shared with Android and iOS (icon masters)
│   └── Resources/                   # Icons, .icns, graphics, word list, contributors & .keylayout
├── script/                          # Build, install, package, and test scripts
└── tests/                           # Unit tests, SLS lexicon stress test & Smart Phonetic golden file

Contributions, bug reports, and suggestions are welcome!

• Review CONTRIBUTING.md for development workflows.
• Run ./script/test.sh to verify all transliterator and parser stress tests pass before submitting pull requests.

Many thanks to all the Akshara contributors! 🚀

Akshara is released under the MIT License. See LICENSE.