README

A Laravel package to automatically extract translation keys from your views and generate language files. Say goodbye to manually creating translation files!

Features

🔍 Automatic Extraction: Scans your views for __(), trans(), and @lang() functions
🤖 AI-Powered Translation: Automatically translate extracted keys using OpenAI, DeepL, or Google Translate
🌍 Multi-locale Support: Generate translation files for any locale
📁 Configurable Paths: Scan custom directories beyond just views
🔄 Preserve Existing: Keeps your existing translations intact when re-running
📊 Statistics: Shows translation progress and completion percentage
🎯 Context-Aware: Groups related keys for consistent terminology
⚙️ Highly Configurable: Customize function names, paths, and more

Requirements

PHP 8.1 or higher
Laravel 10.x, 11.x, or 12.x

Installation

You can install the package via composer:

composer require silalahi/laravel-translation-extractor

Publish the configuration file:

php artisan vendor:publish --tag=translation-extractor-config

This will create a config/translation-extractor.php file.

Usage

Basic Usage

Extract translations for the default locale (configured in config file):

php artisan translations:extract

Extract for Specific Locale

php artisan translations:extract --locale=id

Force Overwrite

By default, existing translations are preserved. Use --force to overwrite:

php artisan translations:extract --force

AI-Powered Translation

Automatically translate extracted keys using AI providers:

php artisan translations:extract --locale=id --translate

Supported Providers:

OpenAI (GPT-4, GPT-3.5)
DeepL
Google Translate

Setup:

Add API keys to your .env file:

# For OpenAI
TRANSLATION_AI_ENABLED=true
TRANSLATION_AI_PROVIDER=openai
OPENAI_API_KEY=sk-...

# For DeepL
TRANSLATION_AI_PROVIDER=deepl
DEEPL_API_KEY=your-deepl-key

# For Google Translate
TRANSLATION_AI_PROVIDER=google
GOOGLE_TRANSLATE_API_KEY=your-google-key

Optional: Add domain context for better accuracy:

TRANSLATION_AI_DOMAIN="medical clinic management"

Features:

Only translates keys with empty values (preserves manual edits)
Groups related keys for consistent terminology
Graceful error handling with detailed logs
Batch processing for API efficiency

How It Works

The package scans your view files looking for translation function calls:

// In your Blade views
__('I love programming.')
{{ __('Welcome to our website') }}
@lang('Hello World')
trans('Good morning')

It then generates a JSON file in your lang directory:

// lang/id.json
{
    "Good morning": "",
    "Hello World": "",
    "I love programming.": "",
    "Welcome to our website": ""
}

You can then add your translations:

// lang/id.json
{
    "Good morning": "Selamat pagi",
    "Hello World": "Halo Dunia",
    "I love programming.": "Saya suka pemrograman",
    "Welcome to our website": "Selamat datang di website kami"
}

Configuration

The config/translation-extractor.php file provides extensive configuration options:

return [
    // Default locale for extraction (creates lang/{locale}.json)
    'locale' => 'id',

    // Directories to scan
    'paths' => [
        resource_path('views'),
        // Add more paths as needed
    ],

    // Translation functions to look for
    'functions' => [
        '__',
        'trans',
        '@lang',
    ],

    // File extensions to scan
    'extensions' => [
        'php',
        'blade.php',
    ],

    // Directories to exclude
    'exclude' => [
        'vendor',
        'node_modules',
        'storage',
    ],

    // Preserve existing translations
    'preserve_existing' => true,

    // Sort keys alphabetically
    'sort_keys' => true,
];

Advanced Usage

Scanning Custom Directories

You can scan additional directories by modifying the config:

'paths' => [
    resource_path('views'),
    app_path('Http/Controllers'), // Scan controllers too
    app_path('Services'),
],

Custom Translation Functions

If you use custom translation helper functions:

'functions' => [
    '__',
    'trans',
    '@lang',
    'translate', // Your custom function
    'my_trans',
],

Multiple Locales Workflow

Extract for multiple locales in sequence:

php artisan translations:extract --locale=id
php artisan translations:extract --locale=es
php artisan translations:extract --locale=fr

Tips & Best Practices

Run Regularly: Extract translations during development to catch new keys
Version Control: Commit the generated files to track translation progress
CI/CD Integration: Add extraction to your CI pipeline to ensure no keys are missed
Translation Services: The generated JSON files are compatible with most translation services
Keep Keys Simple: Use clear, descriptive translation keys in English

Example Output

🔍 Scanning for translation keys...

✅ Found 24 unique translation keys.

📝 Sample keys:
   - Welcome to our application
   - Login to continue
   - Email Address
   - Password
   - Remember Me
   ... and 19 more

💾 Translations saved to: /path/to/your/project/lang/id.json

📊 Statistics:
+--------------+-------+
| Metric       | Value |
+--------------+-------+
| Total Keys   | 24    |
| Translated   | 18    |
| Untranslated | 6     |
| Progress     | 75%   |
+--------------+-------+

💡 Tip: Edit /path/to/your/project/lang/id.json to add translations for untranslated keys.

Testing

composer test

Security

If you discover any security related issues, please email your.email@example.com instead of using the issue tracker.

License

The MIT License (MIT). Please see License File for more information.

Support

If you find this package helpful, please consider:

⭐ Starring the repository
🐛 Reporting bugs
💡 Suggesting new features
🔀 Submitting pull requests

Roadmap

Automatic translation using AI (OpenAI, DeepL, Google Translate) ✅
Integration with translation services (OpenAI, DeepL, Google Translate) ✅
Support for nested translation keys (dot notation)
GUI for managing translations
Support for pluralization rules
Vue.js and React component scanning

silalahi / laravel-translation-extractor

Maintainers

Details