Auto Transliterate by Abdullah Shahneel

• Why this exists
• How it differs from "translation" plugins
• Requirements
• Installation
  • Plugin options
• Usage
  • Switching languages
  • It learns from corrections
• Configuration
  • Configuration reference
  • Providers
  • Local dictionaries
  • Cache maintenance
• HTTP API
• JavaScript API
• Security and privacy
• Upgrading to 0.3
• Troubleshooting
• Development
• Roadmap
• License

Inline, as-you-type transliteration and translation for Filament form inputs.

Type Romanized text (Arabizi, Roman Urdu, Hinglish, …), press space, and the word is rewritten in the target script — without leaving the field, opening a modal, or switching OS keyboards. Built for multilingual data-entry teams who think in Arabic, Urdu, Hindi, Persian, or other non-Latin scripts but type on a standard QWERTY keyboard. 10 target languages ship out of the box (ar by default), switchable from the panel header.

marhaba   ->  مرحبا         (transliterate: Arabic — default)
receiver  ->  ریسیور        (transliterate: Roman Urdu -> Urdu script)
namaste   ->  नमस्ते         (transliterate: Hinglish -> Hindi Devanagari)
receiver  ->  المستلم       (translate: by meaning — opt-in)

#Why this exists

The existing Filament translation plugins are action-based (click a button, fill a per-locale modal) or automate static labels. None of them convert what the user is typing, as they type it. This package fills that gap: it is a keyboard-style input helper, not a content-translation workflow.

#How it differs from "translation" plugins

It ships two distinct modes and keeps them strictly separate:

Transliterate mode never silently falls through to meaning-based translation. That separation is the whole point: a phonetic helper that quietly "translates" a word it didn't recognise is worse than one that leaves it alone.

#Requirements

#Installation

composer require iabduul7/filament-auto-transliterate

# Publishes the config + migrations and offers to run migrations.
php artisan filament-auto-transliterate:install

php artisan filament:assets

The migrations ship as publishable stubs, so use the install command above (php artisan migrate alone won't create the cache table until the migrations are published). To publish manually instead:

php artisan vendor:publish --tag="filament-auto-transliterate-migrations"
php artisan migrate

Add the plugin to a panel:

use Iabduul7\FilamentAutoTransliterate\FilamentAutoTransliteratePlugin;

public function panel(Panel $panel): Panel
{
    return $panel
        ->plugin(FilamentAutoTransliteratePlugin::make());
}

That registers the header on/off toggle (next to global search) and injects the assets. Nothing else to wire up.

#Plugin options

FilamentAutoTransliteratePlugin::make()
    ->showToggle(false)                               // hide the header on/off toggle
    ->languageSwitcher(false)                         // hide the language chip/dropdown
    ->injectCsrfMeta(false)                           // your layout already has <meta name="csrf-token">
    ->toggleRenderHook(PanelsRenderHook::TOPBAR_END)  // move the toggle
    ->scriptNonce(fn () => Vite::cspNonce());         // CSP nonce for the inline config script

use Illuminate\Http\Request;

FilamentAutoTransliteratePlugin::authorizeUsing(
    fn (Request $request) => $request->user()?->can('use-transliteration')
);

#Usage

Mark any text field, textarea, etc. as translatable:

use Filament\Forms\Components\TextInput;

TextInput::make('receiver_name')
    ->translatable();                 // uses the default mode

TextInput::make('description')
    ->translatable(mode: 'translate'); // convert by meaning instead

TextInput::make('name_hi')
    ->translatable(target: 'hi');      // pinned to Hindi, ignores the header switcher

->autoTransliterate() is an identical alias, for hosts that already define their own translatable macro. Both throw a LogicException on components that aren't inputs (no extraInputAttributes()).

Turn the feature on with the header toggle. Focus a marked field, type a Roman word, press space — done. State persists per browser.

When a word is converted:

• Triggers: space, Enter in a textarea, Tab, and blur. Pasted text is left untouched.
• Skipped: emails, URLs, numbers, and text already in the target script.
• Safe to type with: IME/composition-aware, works with mobile keyboards, and native undo (Ctrl/Cmd+Z) still reverts a conversion.

#Switching languages

When more than one language is configured, a language chip appears next to the header toggle showing the active language's native name (e.g. العربية). Click it to switch (it is keyboard-accessible); the choice persists per browser. Fields pinned with ->translatable(target: ...) show a badge and always use their pinned language. Hide the chip with ->languageSwitcher(false) on the plugin.

10 languages ship enabled by default — Arabic, Urdu, Persian, Hindi, Marathi, Nepali, Bengali, Punjabi, Russian, and Greek. Trim or extend the list via the languages config key (each entry carries its label, native name, RTL flag, and Unicode script ranges used to detect already-converted text) — any other language Google Input Tools supports (Gujarati, Tamil, Telugu, Kannada, Malayalam, Sinhala, Amharic, Hebrew, …) is one config entry away.

#It learns from corrections

When a user fixes a word the package applied (e.g. it wrote مکن and they correct it to مکان), the correction is stored — authenticated, validated, and stamped with the correcting user's id — as a high-confidence cache entry that wins over provider output on every future request. The more the package is used, the better and faster it gets, at zero API cost. Disable with 'learn' => ['enabled' => false].

#Configuration

Publish the config to customise providers, modes, language, route, and limits:

php artisan vendor:publish --tag="filament-auto-transliterate-config"

#Configuration reference

Every key in config/filament-auto-transliterate.php:

#Providers

Out of the box: Google Input Tools (transliteration), and MyMemory, LibreTranslate, Microsoft, Google plus local JSON dictionaries. Unconfigured providers (missing API keys) are skipped automatically. Every successful conversion is cached permanently in the database, so repeats are instant and free — and user corrections outrank everything. Add your own by implementing Contracts\TranslationProvider, registering it in provider_map, and adding its key to a mode's chain.

Free-service resilience is built in. A provider outcome is either a miss (it worked but has no answer: unknown word, no candidates, quota-warning text) or an error (transport failure, timeout, any non-2xx including 429, malformed payload). Only errors count towards the circuit breaker: a provider that errors provider_failure_threshold times in a row is skipped for provider_failure_cooldown seconds instead of eating a timeout per word. The client de-duplicates concurrent requests, remembers misses for the session, and backs off after 429 / auth / server errors.

#Local dictionaries

Two separate files, one per mode (so a meaning-glossary can never answer a phonetic query):

// translate mode: meanings
'dictionary_path' => resource_path('dictionaries/en-{target}.json'),

// transliterate mode: romanization → script, checked before any network provider
'transliterate_dictionary_path' => resource_path('dictionaries/roman-{target}.json'),

Both are { "source word": "target word" } JSON maps with a {target} placeholder to ship one file per language. A missing file is a miss, not an error. A dictionary only returns a hit when every word of a short phrase is known, so it never partially mangles input.

#Cache maintenance

Provider results can be pruned by age; user corrections never are:

php artisan filament-auto-transliterate:prune --days=90   # or set cache_ttl_days and omit --days

#HTTP API

Five routes under route.prefix (default filament-auto-transliterate), named filament-auto-transliterate.{translate,batch,learn,status,stats}. All are auth-gated (web + auth, or auth:<guard>), optionally gated again by authorizeUsing(), and rate-limited by the named limiter filament-auto-transliterate (route.throttle; /learn also gets filament-auto-transliterate-learn). They are JSON endpoints that use Laravel's CSRF protection.

POST /translate — body { "text": "receiver", "target_lang": "ur", "mode": "transliterate" } (target_lang and mode optional; target_lang must be a configured language code, mode must be in allowed_modes).

{ "success": true, "translated": "ریسیور", "source": "google_input_tools", "confidence": 0.9,
  "processing_time": 120.5, "original": null, "message": null, "alternatives": ["رسیور"] }

A no-op or miss is success: false with the original text and a message ("No translation needed", "Text too short", "No translation available"); the field is simply left unchanged.

POST /batch-translate — body { "texts": ["a", "b"], "target_lang": "ur", "mode": "transliterate" }.

{ "success": true, "results": { "0": { "...": "per-item result as above" } }, "total": 2, "successful": 1 }

Top-level success is true when at least one item succeeded.

POST /learn — body { "original": "makan", "corrected": "مکان", "target_lang": "ur", "mode": "transliterate" }. original must not already be in the target script (max learn.max_original_length), corrected must differ and be in the target script (learn.min_script_ratio). Returns { "success": true, "target_lang": "ur", "mode": "transliterate" }.

GET /provider-status — one entry per provider_map key:

{ "success": true, "probed": false, "timestamp": "...",
  "providers": { "mymemory": { "configured": true, "circuit_open": false } } }

With ops_endpoints.probe_providers on, each entry also has ok (bool) and error (null or "unavailable") from a live test call, and probed is true. Provider/exception text is never returned.

Errors

#JavaScript API

The overlay is a singleton at window.FilamentAutoTransliterate (re-evaluating the bundle on wire:navigate reuses it).

Storage: localStorage keys fat_enabled ("true"/"false") and fat_target_lang.

window.fatConfig — injected at HEAD_END: { languages, defaultTarget, learnEnabled }.

Events — CustomEvents dispatched on window; the payload is in event.detail:

window.addEventListener('fat:applied', (e) => console.log(e.detail.original, '->', e.detail.applied));

Field attributes — set by the macro, read by the overlay:

There is intentionally no JSON attribute: Laravel's attribute bag does not HTML-escape values (it turns " into \"), which would truncate it. Inputs tagged by hand with a legacy data-fat-config JSON attribute (and no data-fat-endpoint) are still read.

Client error handling: 401/403/419 shows "Session expired" and pauses requests for 30s; 429 pauses for 15s; 5xx/network errors pause for 5s; 422 is remembered as a miss.

#Security and privacy

• Typed text leaves your server. It is sent to whichever providers you configure (Google, Microsoft, MyMemory, LibreTranslate, …). Use only providers you are comfortable sharing it with, or restrict the chains to the local dictionary providers.
• The endpoints are an auth-gated, throttled proxy to those APIs — keep them authenticated. Restrict allowed_modes to ['transliterate'] if you don't want users spending translate-provider quota.
• Nothing is logged unless log_requests is explicitly on; provider/exception text never reaches API responses.
• Provider API keys stay in your server config and are never sent to the browser.
• Cached conversions and corrections live in your own database table.

Report vulnerabilities privately — see SECURITY.md.

#Upgrading to 0.3

1. Publish and run the new migration (adds user_id and makes the cache lookup index UNIQUE; duplicates are collapsed, keeping corrections; it is a no-op on fresh installs):

   php artisan vendor:publish --tag="filament-auto-transliterate-migrations"
   php artisan migrate
   

   Only the add_user_id_and_unique_index_to_translation_cache_table stub is new; skip re-publishing the create migration if you already have it.

2. /provider-status response shape changed (breaking): each provider is now { configured, circuit_open } (plus ok / error when probing) and the response has a top-level probed. Update anything consuming the old shape.

3. /stats and /provider-status are off by default. Set ops_endpoints.enabled to bring them back; live probing needs ops_endpoints.probe_providers.

4. route.middleware now defaults to null (stack built from route.guard). A published config with an explicit array keeps working verbatim; to use the new guard option, set middleware to null. Throttling now comes from the named limiter / route.throttle.

5. allowed_modes is new (default: both modes). Requests with a mode outside it get a 422.

6. Run php artisan filament:assets so the new JS/CSS is served, and re-publish the config if you want the new keys visible (all have defaults).

#Troubleshooting

#Development

composer install && npm install

composer test      # Pest (199 tests, in-memory SQLite, all HTTP faked)
composer lint      # Pint, check only
composer format    # Pint, apply fixes
composer analyse   # PHPStan / Larastan, level 5

npm run build      # rebuild resources/dist (committed; CI fails if stale)

The compiled JS/CSS ship in resources/dist. See CONTRIBUTING.md for the branch flow.

#Roadmap

Design documents for shipped and upcoming work live in docs/.

• Learn-from-correction — shipped (see above).
• First-class support for additional target languages and scripts — shipped (10 languages + header switcher).
• Client-side preload of the most common learned words (no network round-trip at all).
• Candidate picker UI for Google Input Tools alternatives (the API plumbing already returns them).
• A cache/glossary-management Filament resource.

#License

MIT. See LICENSE.md.