aar/laravel-auto-translator

aar/laravel-auto-translator

A production-ready, high-performance translation management system for Laravel.
Handles 10,000+ translation keys with AI-powered translations, a modern dashboard, CLI tools, and full database storage.

✅ Ready for GitHub and Packagist — composer require aar/laravel-auto-translator

Features

Requirements

• PHP 8.1+
• Laravel 10, 11, or 12
• Composer

Installation

composer require aar/laravel-auto-translator

Publish Configuration

php artisan vendor:publish --tag=aar-translator-config

Run Migrations

php artisan migrate

Configuration

The config file is at config/aar-translator.php after publishing.

Key Settings

return [
    'locales'       => ['en', 'ar', 'fr', 'es'],
    'source_locale' => 'en',
    'storage'       => 'both',          // 'file', 'database', or 'both'
    'scan_paths'    => ['app', 'resources'],
    'excluded_dirs' => ['vendor', 'node_modules', 'storage'],
    'translator'    => env('AAR_TRANSLATOR_PROVIDER', 'libretranslate'),
    'memory'        => ['enabled' => true, 'driver' => 'database'],
    'dashboard'     => [
        'enabled'    => true,
        'path'       => 'admin/translations',
        'middleware' => ['web'],
    ],
];

AI Translation Setup

LibreTranslate (Free, Open-Source – Default)

AAR_TRANSLATOR_PROVIDER=libretranslate
LIBRETRANSLATE_URL=https://libretranslate.com
LIBRETRANSLATE_API_KEY=your-optional-api-key

Self-host for free: pip install libretranslate && libretranslate --host 0.0.0.0 --port 5000

DeepL

AAR_TRANSLATOR_PROVIDER=deepl
DEEPL_API_KEY=your-deepl-api-key
DEEPL_FREE_API=true

Google Translate

AAR_TRANSLATOR_PROVIDER=google
GOOGLE_TRANSLATE_API_KEY=your-google-api-key

OpenAI (GPT-4o-mini or better)

AAR_TRANSLATOR_PROVIDER=openai
OPENAI_API_KEY=your-openai-key
OPENAI_MODEL=gpt-4o-mini

CLI Commands

All commands use the aar: prefix.

Scan Project

# Incremental scan (skips unchanged files)
php artisan aar:scan

# Full scan (clears file hash cache)
php artisan aar:scan --fresh

# Scan and immediately export to language files
php artisan aar:scan --export

Auto-Translate Missing Keys

# Translate all missing keys for all locales
php artisan aar:auto

# Translate a specific locale only
php artisan aar:auto --locale=ar

# Override the provider for this run
php artisan aar:auto --provider=deepl

# Translate and export to files
php artisan aar:auto --export

Clean Dead Keys

# Preview dead keys without deleting (dry run)
php artisan aar:clean --dry-run

# Delete dead keys (with confirmation prompt)
php artisan aar:clean

# Delete without confirmation
php artisan aar:clean --force

Export Translations

php artisan aar:export               # JSON (default)
php artisan aar:export --format=csv  # CSV
php artisan aar:export --format=zip  # ZIP (one JSON per locale)
php artisan aar:export --locale=ar   # Export single locale

Import Translations

php artisan aar:import translations.json
php artisan aar:import translations.csv

Translation Status

php artisan aar:status

Example output:

📊 Translation Status

  Total Keys : 142
  Dead Keys  : 3

 Locale  Translated  Missing  Total  Progress
 EN      142         0        142    100.0% [████████████████████]
 AR      87          55       142    61.3%  [████████████░░░░░░░░]
 FR      130         12       142    91.5%  [██████████████████░░]

Manage Locales

# Add a new locale
php artisan aar:lang add de

# Remove a locale
php artisan aar:lang remove es

Dashboard

Access the web dashboard at /admin/translations (configurable).

Dashboard Features

• Overview: Total keys, dead keys, missing translations, locale completion bars
• Keys List: Paginated table with search, group filter, missing-only filter
• Inline Editing: Click any translation to edit it directly in the browser
• Bulk Actions: Delete all dead keys, trigger scan, trigger auto-translate
• Export: Download JSON, CSV, or ZIP directly from the browser
• Import: Upload a JSON or CSV file to import translations

Securing the Dashboard

Edit config/aar-translator.php:

'dashboard' => [
    'enabled'    => true,
    'path'       => 'admin/translations',
    'middleware' => ['web', 'auth'],        // Require authenticated users
    // Or with permissions:
    // 'middleware' => ['web', 'can:manage-translations'],
],

Publishing Assets

# Publish config
php artisan vendor:publish --tag=aar-translator-config

# Publish migrations
php artisan vendor:publish --tag=aar-translator-migrations

# Publish views (to customise the dashboard)
php artisan vendor:publish --tag=aar-translator-views

Database Tables

The package creates three tables:

Translation Memory

Translation memory prevents duplicate API calls by caching phrase-to-phrase translations.

// config/aar-translator.php
'memory' => [
    'enabled' => true,
    'driver'  => 'database',   // 'database' or 'cache'
],

Use 'driver' => 'cache' for Redis-backed memory in high-traffic apps.

Incremental Scanning

File hashes are cached in storage/app/aar-translator/file-cache.json. Only modified files are re-scanned on subsequent runs, making it fast even for large codebases.

Package Structure

aar/laravel-auto-translator/
├── config/
│   └── aar-translator.php          # Main configuration
├── database/
│   └── migrations/
│       ├── ...create_translation_keys_table.php
│       ├── ...create_translation_values_table.php
│       └── ...create_translation_memory_table.php
├── resources/
│   └── views/
│       └── dashboard/
│           ├── layout.blade.php
│           ├── index.blade.php     # Dashboard overview
│           └── keys.blade.php      # Keys management
├── routes/
│   └── web.php
├── src/
│   ├── AarTranslatorServiceProvider.php
│   ├── Console/Commands/           # All CLI commands
│   ├── Dashboard/Controllers/      # Web dashboard
│   ├── Export/                     # Export & Import services
│   ├── Memory/                     # Translation memory
│   ├── Models/                     # Eloquent models
│   ├── Scanners/                   # Project file scanner
│   ├── Services/                   # Core business logic
│   └── Translators/                # AI provider adapters
└── tests/
    ├── Feature/                    # Integration tests
    └── Unit/                       # Unit tests

Testing

# Run all tests
./vendor/bin/phpunit --testdox

# Run only unit tests
./vendor/bin/phpunit --testsuite Unit --testdox

# Run only feature tests
./vendor/bin/phpunit --testsuite Feature --testdox

Tests use Orchestra Testbench with an in-memory SQLite database — no external services required.

Extending

Adding a Custom Translator

Implement Aar\AutoTranslator\Translators\TranslatorInterface:

use Aar\AutoTranslator\Translators\TranslatorInterface;

class MyCustomTranslator implements TranslatorInterface
{
    public function translate(string $text, string $targetLang, string $sourceLang = 'en'): string
    {
        // your implementation
    }

    public function translateBatch(array $texts, string $targetLang, string $sourceLang = 'en'): array
    {
        return array_map(fn($t) => $this->translate($t, $targetLang, $sourceLang), $texts);
    }

    public function getProviderName(): string
    {
        return 'my-custom-translator';
    }
}

Changelog

See CHANGELOG.md for release history.

License

MIT — see LICENSE for details.

Contributing

Pull requests are welcome. For major changes, please open an issue first.

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

Credits

Built with ❤️ using Laravel, TailwindCSS, and Alpine.js.