README

A powerful Laravel package for managing translations with ease. Scan your codebase for translation keys, export them to Excel for translators, and import them back seamlessly. Supports both PHP array files and JSON translations.

Installation

You can install the package via composer:

composer require beliven-it/laravel-i18n

Features

• 🔍 Scan - Automatically scan your codebase for translation keys (__(), trans(), @lang())
• 📤 Export - Export all translations to Excel format for easy editing by translators
• 📥 Import - Import translations back from Excel with merge or overwrite modes
• 🌐 Dual Format Support - Handles both PHP array files and JSON translations
• 🎯 Smart Detection - Automatically distinguishes between structured (PHP) and simple (JSON) translations
• 📊 Excel Integration - Uses PhpSpreadsheet for reliable Excel file handling

How It Works

The package intelligently handles two types of translations:

PHP Array Files (Structured Translations)

Keys with dots are stored in PHP array files with nested structure:

__('messages.welcome')        // → lang/en/messages.php
__('clinic/detail.title')     // → lang/en/clinic/detail.php

JSON Files (Simple String Translations)

Keys without dots are stored in JSON files:

__('Welcome')                 // → lang/en.json
__('My Translation')          // → lang/en.json

Usage

Scanning for Translation Keys

Scan your application code to find all translation keys:

# Scan and add missing keys to all locales
php artisan i18n:manage scan

# Scan for a specific locale only
php artisan i18n:manage scan --locale=en

The scanner will:

• Find all __(), trans(), and @lang() calls in your code
• Create appropriate translation files (PHP or JSON)
• Add missing keys to existing files
• Show a summary of created files and added keys

Example output:

Scanning for translation keys...
  ✓ Created en/messages.php -> welcome
  + Added en/clinic.php -> detail.title
  
Scan complete!
┌────────────────────────┬───────┐
│ Metric                 │ Count │
├────────────────────────┼───────┤
│ Total keys found       │ 45    │
│ Files created          │ 2     │
│ Keys added             │ 12    │
│ Keys already existing  │ 33    │
└────────────────────────┴───────┘

Exporting Translations

Export all translations to an Excel file for translators:

# Export to default location (storage/app/translations.xlsx)
php artisan i18n:manage export

# Export to custom location
php artisan i18n:manage export --output=/path/to/translations.xlsx

The Excel file will contain:

• Locale - The language code (en, it, fr, etc.)
• Path - The file path (lang/en/messages.php or lang/en.json)
• Key - The translation key
• Value - The translation value

Importing Translations

Import translations back from Excel:

# Import with merge mode (default - keeps existing translations)
php artisan i18n:manage import --input=/path/to/translations.xlsx

# Import with overwrite mode (replaces entire files)
php artisan i18n:manage import --input=/path/to/translations.xlsx --overwrite

Example output:

Importing translations from: /path/to/translations.xlsx (mode: merge)

Import complete!
┌────────────────┬───────┐
│ Metric         │ Count │
├────────────────┼───────┤
│ Files created  │ 1     │
│ Keys added     │ 15    │
│ Keys updated   │ 8     │
└────────────────┴───────┘

Programmatic Usage

You can also use the services directly in your code:

Scanning

use Beliven\I18n\Services\TranslationScanner;
use Beliven\I18n\Services\TranslationFileManager;

$scanner = app(TranslationScanner::class);
$fileManager = app(TranslationFileManager::class);

// Scan for translation keys
$foundKeys = $scanner->scan(['app', 'resources']);

// Parse a key to determine its type
$parsed = $scanner->parseKey('messages.welcome');
// Returns: ['type' => 'php', 'file' => 'messages', 'key' => 'welcome']

$parsed = $scanner->parseKey('Welcome');
// Returns: ['type' => 'json', 'file' => null, 'key' => 'Welcome']

Managing Translation Files

use Beliven\I18n\Services\TranslationFileManager;

$manager = app(TranslationFileManager::class);

// PHP files
$manager->addKey('en', 'messages', 'welcome', 'Welcome!');
$translations = $manager->loadFile('en', 'messages');

// JSON files
$manager->addJsonKey('en', 'Welcome', 'Welcome!');
$jsonTranslations = $manager->loadJsonFile('en');

Exporting

use Beliven\I18n\Services\TranslationExporter;

$exporter = app(TranslationExporter::class);
$result = $exporter->export('/path/to/output.xlsx');

// Returns:
// [
//     'locales' => 3,
//     'rows' => 150,
//     'file' => '/path/to/output.xlsx'
// ]

Importing

use Beliven\I18n\Services\TranslationImporter;

$importer = app(TranslationImporter::class);

// Merge mode
$stats = $importer->import('/path/to/input.xlsx', false);

// Overwrite mode
$stats = $importer->import('/path/to/input.xlsx', true);

// Returns:
// [
//     'files_created' => 2,
//     'keys_added' => 25,
//     'keys_updated' => 10
// ]

Workflow Example

Here's a typical workflow for managing translations:

1. Develop - Write your code using translation functions:

   echo __('Welcome');                    // Simple string
   echo __('messages.greeting', ['name' => $user->name]);  // Structured

2. Scan - Find all translation keys in your codebase:

   php artisan i18n:manage scan

3. Export - Export to Excel for your translators:

   php artisan i18n:manage export --output=translations.xlsx

4. Translate - Send the Excel file to translators

5. Import - Import the translated file back:

   php artisan i18n:manage import --input=translated.xlsx

6. Done - Your application now has all translations!

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Fabrizio Gortani
• All Contributors

License

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