README

A powerful Laravel package that automatically detects untranslated strings in your application and provides automatic translation capabilities using free translation services.

✨ Features

🔍 Smart Detection: Scans your entire Laravel application for untranslated strings
🌐 Free Auto Translation: Uses LibreTranslate and MyMemory (completely free, no API keys needed!)
📊 Translation Statistics: Get detailed insights about your translation coverage
🔧 Flexible Configuration: Customizable scan paths, file formats, and translation patterns
🎯 Multiple File Formats: Support for both JSON and PHP translation files
📱 Rich Console Interface: Beautiful command-line interface with progress indicators
🛡️ Safe Operation: Dry-run mode to preview changes before applying them

🚀 Quick Start (5 minutes!)

1. Install the Package

composer require nabila/laravel-translation-sync

2. Publish Configuration

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

3. Start Translating! (No API keys needed!)

# Scan and auto-translate using FREE services
php artisan translations:sync --translate --auto

# Check your translation coverage
php artisan translations:sync --stats

That's it! 🎉 Your Laravel app now has automatic translation capabilities using completely free services.

Requirements

PHP: >= 8.0
Laravel: 9.x, 10.x, 11.x, 12.x
Composer: Latest stable version

🚀 Quick Start (5 minutes!)

Installation

Install the package via Composer:

composer require nabila/laravel-translation-sync

Publish the configuration file:

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

⚡ Zero-Configuration Setup

The package comes pre-configured to work with free translation services. No API keys, no billing setup required!

# Your .env file (these are the defaults)
TRANSLATION_SERVICE=libretranslate  # Free service!
TRANSLATION_AUTO_TRANSLATE=true

Start using it immediately:

php artisan translations:sync --translate --auto

🧪 Testing Your Installation

After installation, test that everything works:

# Run the test script
php test-package.php

# Or test with Laravel commands
php artisan translations:sync --stats
php artisan translations:sync --translate --dry-run

Configuration

The package comes with a comprehensive configuration file. Here are the key settings:

// config/translation-sync.php

return [
    // Translation service: 'libretranslate', 'mymemory', 'google', 'dummy'
    'service' => env('TRANSLATION_SERVICE', 'libretranslate'),

    // Source language (language of your translation keys)
    'source_language' => env('TRANSLATION_SOURCE_LANG', 'en'),

    // Target languages (defaults to Arabic - change as needed!)
    'target_languages' => env('TRANSLATION_TARGET_LANGS', ['ar']),

    // File format: 'php' (Laravel default) or 'json'
    'file_format' => env('TRANSLATION_FILE_FORMAT', 'php'),

    // Enable automatic translation
    'auto_translate' => env('TRANSLATION_AUTO_TRANSLATE', false),

    // Translation service configurations
    'services' => [
        'libretranslate' => [], // No config needed - FREE!
        'mymemory' => [], // No config needed - FREE!
        'google' => [
            'api_key' => env('GOOGLE_TRANSLATE_API_KEY', null),
        ],
        'freetranslateapi' => [
            'url' => env('FREETRANSLATEAPI_URL', 'http://localhost:5000'),
        ],
        // ... other services
    ],
];

Environment Variables

Add these to your .env file:

TRANSLATION_SERVICE=libretranslate  # FREE - No API key needed!
TRANSLATION_SOURCE_LANG=en
TRANSLATION_AUTO_TRANSLATE=true
# No API key needed for free services!

🎉 No billing, no API keys, no setup required! The package uses free translation services by default.

📋 Need help getting a Google Translate API key? Check out our Quick Setup Guide for step-by-step instructions!

Usage

Basic Scanning

Scan for missing translations:

php artisan translations:sync

Automatic Translation

Enable automatic translation with the --translate flag:

php artisan translations:sync --translate

Advanced Options

# Auto-approve all translations without confirmation
php artisan translations:sync --auto --translate

# Use a specific translation service
php artisan translations:sync --translate --service=google

# Set source and target languages
php artisan translations:sync --translate --source=en --targets=ar,en

# Or use the --locales alias
php artisan translations:sync --translate --locales=ar,en

# Dry run (preview changes without making them)
php artisan translations:sync --dry-run

# Show translation statistics
php artisan translations:sync --stats

# Use PHP files instead of JSON
php artisan translations:sync --format=php

Translation Services

🚀 Free Services (No API Keys Required!)

LibreTranslate (Default - Recommended)

Completely free, open-source translation service

TRANSLATION_SERVICE=libretranslate

✅ No API key required
✅ No billing needed
✅ Open source and self-hosted
✅ Supports 50+ languages
✅ Fast and reliable

MyMemory

Community-driven translation service

TRANSLATION_SERVICE=mymemory

✅ No API key required
✅ No billing needed
✅ Community translations
✅ Supports 80+ languages

💰 Paid Services

Google Translate

Professional translation service

TRANSLATION_SERVICE=google
GOOGLE_TRANSLATE_API_KEY=your-api-key

✅ High quality translations
✅ Supports all major languages
⚠️ Requires billing setup
⚠️ API key required

📋 Need help with Google Translate API? Check out our Quick Setup Guide

Follow these steps to obtain your Google Translate API key:

Go to Google Cloud Console
- Visit Google Cloud Console
- Sign in with your Google account
Create or Select a Project
- Click on the project dropdown at the top
- Either select an existing project or click "New Project"
- If creating new: Enter project name and click "Create"
Enable the Cloud Translation API
- In the left sidebar, go to "APIs & Services" > "Library"
- Search for "Cloud Translation API"
- Click on "Cloud Translation API" from the results
- Click the "Enable" button
Create API Credentials
- Go to "APIs & Services" > "Credentials"
- Click "Create Credentials" > "API key"
- Your API key will be generated and displayed
- Important: Copy and save this key securely
Secure Your API Key (Recommended)
- Click on the API key name to edit it
- Under "API restrictions", select "Restrict key"
- Choose "Cloud Translation API" from the list
- Under "Application restrictions", you can:
  - Set HTTP referrers for web apps
  - Set IP addresses for server apps
  - Or leave unrestricted for development
Set Up Billing (Required)
- Google Translate API requires a billing account
- Go to "Billing" in the left sidebar
- Link a billing account or create a new one
- Note: Google provides free credits for new accounts

Add to Your Environment

GOOGLE_TRANSLATE_API_KEY=AIzaSyD...your-actual-key-here

Pricing Information

Free Tier: $300 in free credits for new Google Cloud accounts
Cost: $20 per 1 million characters translated
Monthly Free Usage: First 500,000 characters per month are free
Check current pricing at Google Cloud Pricing

API Limits

Default Quota: 1,000,000 characters per 100 seconds
Character Limit: 30,000 characters per request
Rate Limit: Can be increased by requesting quota increases

🧪 Testing Service

Dummy Service

For development and testing

TRANSLATION_SERVICE=dummy

The dummy service is useful for testing and development. It simply appends the target language code to the original text.

🆓 Using FreeTranslateApi (Self-hosted, Free)

1. Host the API

Clone https://github.com/ismalzikri/free-translate-api
Follow its README to run locally (npm install && npm start) or deploy to a server.

2. Configure the Package

In your .env file, set:

TRANSLATION_SERVICE=freetranslateapi
FREETRANSLATEAPI_URL=http://localhost:5000

(Change the URL if hosted elsewhere.)

In config/translation-sync.php, ensure:

'service' => env('TRANSLATION_SERVICE', 'freetranslateapi'),

'services' => [
    // ...existing code...
    'freetranslateapi' => [
        'url' => env('FREETRANSLATEAPI_URL', 'http://localhost:5000'),
    ],
],

3. Usage

Run your translation sync commands as usual.
The package will use your FreeTranslateApi instance for translations.

4. Notes

FreeTranslateApi is free and self-hosted, so you control usage and limits.
Make sure your API server is running and accessible from your Laravel app.

Supported Translation Patterns

The package automatically detects these translation patterns in your code:

__('key') - Laravel's __() helper
@lang('key') - Blade directive
trans('key') - Laravel's trans() helper
Lang::get('key') - Facade usage

File Formats

JSON Format (default)

{
    "Welcome": "Bienvenido",
    "Hello World": "Hola Mundo"
}

PHP Format

<?php

return [
    'Welcome' => 'Bienvenido',
    'Hello World' => 'Hola Mundo',
];

Advanced Features

Translation Statistics

Get detailed statistics about your translation coverage:

php artisan translations:sync --stats

This shows:

Total translation keys found
Missing translations
Coverage percentage
Translation service status

Context-Aware Detection

The package provides context for each missing translation, showing:

Files where the translation key was found
Code context around the usage
Multiple occurrences across your application

Placeholder Preservation

The package intelligently handles Laravel translation placeholders:

// Original
__('Welcome :name to our site')

// After translation (Spanish)
'Welcome :name to our site' => 'Bienvenido :name a nuestro sitio'

Examples

Basic Usage

// In your Blade template
<h1>{{ __('Welcome to our site') }}</h1>
<p>{{ __('This is a new feature') }}</p>

// In your controller
return response()->json([
    'message' => __('Data saved successfully')
]);

Run the sync command:

php artisan translations:sync --translate --auto

This will:

Detect the missing translations
Automatically translate them to your configured target languages
Save them to your translation files

Configuration Example

// config/translation-sync.php

return [
    'service' => 'google',
    'source_language' => 'en',
    'target_languages' => ['es', 'fr', 'de', 'it'],
    'auto_translate' => true,
    
    'scan_paths' => [
        'app',
        'resources',
        'routes',
        'custom-modules', // Add custom paths
    ],
    
    'patterns' => [
        "/__\(['\"](.+?)['\"]\)/",
        "/@lang\(['\"](.+?)['\"]\)/",
        "/trans\(['\"](.+?)['\"]\)/",
        "/Lang::get\(['\"](.+?)['\"]\)/",
        "/CustomHelper::translate\(['\"](.+?)['\"]\)/", // Custom pattern
    ],
];

Troubleshooting

Common Issues and Solutions

1. Google Translate API Key Issues

Problem: "Google Translate service is not properly configured"

Solutions:

Verify your API key is correct in .env file
Ensure the Cloud Translation API is enabled in Google Cloud Console
Check that billing is set up for your Google Cloud project
Verify your API key has the correct restrictions (if any)

Test your API key:

# Test if your API key works
curl -X POST \
  "https://translation.googleapis.com/language/translate/v2?key=YOUR_API_KEY" \
  -d "q=Hello World&target=es&source=en"

2. Permission Issues

Problem: "Failed to create translation file" or permission errors

Solutions:

# Make sure Laravel can write to the lang directory
chmod -R 755 resources/lang/
chown -R www-data:www-data resources/lang/  # On Linux servers

3. Missing Translations Not Detected

Problem: Known untranslated strings are not being found

Solutions:

Check if your translation patterns are in the scan paths
Verify file extensions are included in configuration
Use custom patterns for non-standard translation methods:

// config/translation-sync.php
'patterns' => [
    "/__\(['\"](.+?)['\"]\)/",
    "/@lang\(['\"](.+?)['\"]\)/",
    "/YourCustomHelper::trans\(['\"](.+?)['\"]\)/", // Add custom patterns
],

4. Quota Exceeded Errors

Problem: "Quota exceeded" or rate limit errors

Solutions:

Check your Google Cloud Console quotas
Request quota increases if needed
Use smaller batches with the --dry-run flag first
Consider using the dummy service for development:

TRANSLATION_SERVICE=dummy  # For development/testing

5. Composer Dependencies

Problem: Package installation fails

Solutions:

# Install required dependencies
composer require guzzlehttp/guzzle
composer require stichoza/google-translate-php

# If you get version conflicts, try:
composer update --with-dependencies

6. Configuration Not Loading

Problem: Configuration changes not taking effect

Solutions:

# Clear config cache
php artisan config:clear
php artisan config:cache

# Re-publish config if needed
php artisan vendor:publish --tag=translation-sync-config --force

Debugging Commands

# Check translation statistics
php artisan translations:sync --stats

# See what would be translated without making changes
php artisan translations:sync --dry-run

# Test with dummy service
php artisan translations:sync --service=dummy --translate

# Check service status
php artisan tinker
# Then run: app(Nabila\TranslationSync\Services\TranslationWriter::class)->isTranslationServiceAvailable()

Environment Validation

Create a simple test to validate your setup:

// In tinker or a test route
use Nabila\TranslationSync\Services\Translation\TranslationServiceFactory;

$service = TranslationServiceFactory::create('google');
if ($service->isConfigured()) {
    echo "✅ Google Translate is configured correctly\n";
    $result = $service->translate('Hello', 'es');
    echo "Test translation: {$result}\n";
} else {
    echo "❌ Google Translate is not configured\n";
}

Error Handling

The package includes comprehensive error handling:

Translation Service Errors: Falls back to original text or configured fallback strategy
File Permission Issues: Clear error messages with suggested solutions
API Quota Limits: Graceful handling with retry suggestions
Network Issues: Timeout handling and fallback options

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This package is open-sourced software licensed under the MIT license.

Support

If you discover any security vulnerabilities or bugs, please send an e-mail to the package maintainer.

Changelog

v2.0.1 (Compatibility Update)

🔧 Broader Laravel Support: Now compatible with Laravel 9.x, 10.x, 11.x, and 12.x
📦 Updated Dependencies: More flexible version constraints for better compatibility
🧪 Enhanced Testing: Support for multiple PHPUnit and Testbench versions

v2.0.0 (Enhanced Version)

✨ FREE Translation Services: Added LibreTranslate and MyMemory (no API keys needed!)
🌐 Zero-Configuration: Works out-of-the-box with free services
📦 Packagist Ready: Proper versioning and composer configuration
🔧 Enhanced Configuration: LibreTranslate as default free service
🎯 Improved Documentation: Clear installation and usage guides
🧪 Better Testing: Support for free service testing

v1.0.0 (Original Version)

🔍 Basic translation key detection
📁 Simple file writing capabilities
🎯 Basic console command

nabila / laravel-translation-sync

Maintainers

Details

README

✨ Features

🚀 Quick Start (5 minutes!)

1. Install the Package

2. Publish Configuration

3. Start Translating! (No API keys needed!)

Requirements

🚀 Quick Start (5 minutes!)

Installation

⚡ Zero-Configuration Setup

🧪 Testing Your Installation

Configuration

Environment Variables

Usage

Basic Scanning

Automatic Translation

Advanced Options

Translation Services

🚀 Free Services (No API Keys Required!)

LibreTranslate (Default - Recommended)

MyMemory

💰 Paid Services

Google Translate

Pricing Information

API Limits

🧪 Testing Service

Dummy Service

🆓 Using FreeTranslateApi (Self-hosted, Free)

1. Host the API

2. Configure the Package

3. Usage

4. Notes

Supported Translation Patterns

File Formats

JSON Format (default)

PHP Format

Advanced Features

Translation Statistics

Context-Aware Detection

Placeholder Preservation

Examples

Basic Usage

Configuration Example

Troubleshooting

Common Issues and Solutions

1. Google Translate API Key Issues

2. Permission Issues

3. Missing Translations Not Detected

4. Quota Exceeded Errors

5. Composer Dependencies

6. Configuration Not Loading

Debugging Commands

Environment Validation

Error Handling

Contributing

License

Support

Changelog

v2.0.1 (Compatibility Update)

v2.0.0 (Enhanced Version)

v1.0.0 (Original Version)