VinaKey Extension

A browser extension that enables Vietnamese typing using the powerful anvim engine. VinaKey allows users to seamlessly type Vietnamese text on any website with support for multiple input methods.

Features

• Multiple Input Methods: Support for Off/Auto/Telex/VNI/VIQR input methods via anvim
• Smart Site Management: Enable/disable the extension per website
• Universal Compatibility: Works on all text input fields across the web
• Modern UI: Clean interface built with Bulma CSS
• Comprehensive Testing: End-to-end tests with Playwright

Input Methods

• Off: Disable Vietnamese typing
• Auto: Automatic detection and conversion
• Telex: Popular Vietnamese input method (aw → ă, oo → ơ, etc.)
• VNI: Numeric-based input method
• VIQR: ASCII-based Vietnamese input method

Quick Start

Prerequisites

• Node.js 18+
• Yarn package manager
• Modern web browser (Chrome/Firefox/Edge)

Installation

# Clone the repository
git clone <repository-url>
cd vinakey-extension

# Install dependencies
yarn install

# Build the extension
yarn build

# Load in browser (Chrome example)
# 1. Open chrome://extensions/
# 2. Enable "Developer mode"
# 3. Click "Load unpacked"
# 4. Select the dist/ folder

Development

# Start development server with hot reload
yarn dev

# Run tests
yarn test

# Run end-to-end tests
yarn test:e2e

# Lint code
yarn lint

# Type checking
yarn type-check

Project Structure

vinakey-extension/
├── src/
│   ├── content/          # Content scripts
│   ├── popup/           # Extension popup UI (HTML + vanilla JS)
│   ├── background/      # Background scripts (service worker)
│   ├── options/         # Options page (HTML + vanilla JS)
│   ├── utils/           # Utility functions
│   └── types/           # TypeScript types
├── public/              # Static assets
├── tests/               # Test files
├── docs/                # Documentation
└── dist/                # Built extension

Architecture

Core Components

1. Content Script: Injected into web pages to handle text input
2. Background Script: Manages extension state and settings
3. Popup UI: Quick access to settings and toggle
4. Options Page: Detailed configuration interface

Key Technologies

• anvim: Vietnamese input method engine
• Bulma CSS: Modern CSS framework
• Vanilla JavaScript: Lightweight UI implementation
• Playwright: End-to-end testing framework
• TypeScript: Type-safe development
• Yarn: Package management

Usage

1. Enable Extension: Click the VinaKey icon in your browser toolbar
2. Select Input Method: Choose from Off/Auto/Telex/VNI/VIQR
3. Configure Sites: Add websites to enable/disable list
4. Start Typing: Begin typing Vietnamese on any text field

Configuration

Input Method Settings

Access via extension popup or options page:

• Default Method: Set preferred input method (Auto, Telex, VNI, VIQR, or Off)
• Global Toggle: Enable/disable the extension globally
• Per-site Control: Enable/disable for specific websites

Site Management

• Whitelist Mode: Only work on specified sites
• Blacklist Mode: Work everywhere except specified sites
• Domain Patterns: Support for wildcards and subdomains

Development Guide

See DEVELOPMENT.md for detailed development instructions.

Testing

See TESTING.md for testing guidelines and setup.

API Reference

See API.md for detailed API documentation.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

License

MIT License - see LICENSE file for details.

Support

• Issues: Report bugs and feature requests
• Documentation: Comprehensive guides in /docs
• Community: Join our discussions

---

Built with ❤️ for the Vietnamese developer community