PHPackages                             syriable/localizator - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Localization & i18n](/categories/localization)
4. /
5. syriable/localizator

ActiveLibrary[Localization & i18n](/categories/localization)

syriable/localizator
====================

AI-powered Laravel package for automatic translation scanning and generation

v1.4.0(8mo ago)010MITPHPPHP ^8.3

Since Aug 29Pushed 8mo agoCompare

[ Source](https://github.com/syriable/localizator)[ Packagist](https://packagist.org/packages/syriable/localizator)[ RSS](/packages/syriable-localizator/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (7)Dependencies (9)Versions (10)Used By (0)

Syriable Localizator
====================

[](#syriable-localizator)

[![Latest Version on Packagist](https://camo.githubusercontent.com/443c74aea6d8e747004a87bafabac7fa94c9697700057978de68f2b793b7484a/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f7379726961626c652f6c6f63616c697a61746f722e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/syriable/localizator)[![GitHub Tests Action Status](https://camo.githubusercontent.com/75c21917f2d3900d2fab8b7968b54be04b046b2e4900e60b9edefcd7ec9d174f/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f7379726961626c652f6c6f63616c697a61746f722f72756e2d74657374732e796d6c3f6272616e63683d6d61696e266c6162656c3d7465737473267374796c653d666c61742d737175617265)](https://github.com/syriable/localizator/actions?query=workflow%3Arun-tests+branch%3Amain)[![GitHub Code Style Action Status](https://camo.githubusercontent.com/462e964c453b7b289ee7ea5ab9d548a6d226d2acc13ae50837d0c2e91daccf52/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f7379726961626c652f6c6f63616c697a61746f722f6669782d7068702d636f64652d7374796c652d6973737565732e796d6c3f6272616e63683d6d61696e266c6162656c3d636f64652532307374796c65267374796c653d666c61742d737175617265)](https://github.com/syriable/localizator/actions?query=workflow%3A%22Fix+PHP+code+style+issues%22+branch%3Amain)[![Total Downloads](https://camo.githubusercontent.com/bbaabf6e4049ab9d2bbf4fc6ad1fb4a394e4d7c3fc7e4c35639de3662d19b0dc/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f7379726961626c652f6c6f63616c697a61746f722e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/syriable/localizator)

An advanced Laravel package for automatic translation scanning and AI-powered translation generation. Built for Laravel 12+ with modern PHP standards and FilamentPHP 4 compatibility.

🚀 Features
----------

[](#-features)

- **🔍 Comprehensive Scanning**: Automatically scan PHP, Blade, Vue.js, and JavaScript files for translation functions
- **🚫 Smart Comment Detection**: Automatically skip translation keys in comments (`/* {{ __('key') }} */`)
- **🧹 Remove Missing Keys**: Clean up unused translation keys from language files with `--remove-missing`
- **🤖 AI-Powered Translations**: Generate translations using OpenAI, Claude, Google Translate, or Azure Translator
- **📁 Multiple Formats**: Support for both JSON and PHP array translation files
- **⚙️ Highly Configurable**: Extensive configuration options for customizing behavior
- **🧪 Production Ready**: Built with PSR standards, PHPStan level 8, and comprehensive testing
- **🔧 Developer Friendly**: Interactive CLI commands with progress indicators and validation
- **💾 Safe Operations**: Automatic backups and dry-run capabilities

📋 Requirements
--------------

[](#-requirements)

- PHP 8.3 or higher
- Laravel 12.0 or higher
- Composer

📦 Installation
--------------

[](#-installation)

Install the package via Composer:

```
composer require syriable/localizator
```

Publish the configuration file:

```
php artisan vendor:publish --tag="localizator-config"
```

This will publish the configuration file to `config/localizator.php`.

⚙️ Configuration
----------------

[](#️-configuration)

The package comes with extensive configuration options. Here are the key settings:

```
// config/localizator.php
return [
    // Translation file type: 'default' (PHP) or 'json'
    'localize' => env('LOCALIZATOR_TYPE', 'default'),

    // Source language for AI translations
    'source_language' => env('LOCALIZATOR_SOURCE_LANG', 'en'),

    // Use nested array structure for dot notation keys
    'nested' => true,

    // Directories to scan for translation functions
    'dirs' => [
        app_path(),
        resource_path('views'),
        resource_path('js'),
        resource_path('vue'),
        base_path('routes'),
    ],

    // File patterns to include
    'patterns' => [
        '*.php',
        '*.blade.php',
        '*.vue',
        '*.js',
        '*.ts',
    ],

    // Translation functions to look for
    'functions' => [
        '__',
        'trans',
        'trans_choice',
        '@lang',
        '@choice',
        'Lang::get',
        'Lang::choice',
        '$t',  // Vue i18n
        '$tc', // Vue i18n choice
    ],

    // AI translation settings
    'ai' => [
        'provider' => env('LOCALIZATOR_AI_PROVIDER', 'openai'),
        'openai' => [
            'api_key' => env('OPENAI_API_KEY'),
            'model' => env('OPENAI_MODEL', 'gpt-3.5-turbo'),
        ],
        'claude' => [
            'api_key' => env('ANTHROPIC_API_KEY'),
            'model' => env('CLAUDE_MODEL', 'claude-3-sonnet-20240229'),
        ],
        // ... more AI provider configurations
    ],
];
```

### Environment Variables

[](#environment-variables)

Add these to your `.env` file:

```
# Basic Configuration
LOCALIZATOR_TYPE=default
LOCALIZATOR_SOURCE_LANG=en

# AI Provider (choose one)
LOCALIZATOR_AI_PROVIDER=openai

# OpenAI Configuration
OPENAI_API_KEY=your-openai-api-key
OPENAI_MODEL=gpt-3.5-turbo

# Or Claude Configuration
ANTHROPIC_API_KEY=your-anthropic-api-key
CLAUDE_MODEL=claude-3-sonnet-20240229

# Or Google Translate Configuration
GOOGLE_TRANSLATE_API_KEY=your-google-api-key
GOOGLE_CLOUD_PROJECT_ID=your-project-id

# Or Azure Translator Configuration
AZURE_TRANSLATOR_KEY=your-azure-key
AZURE_TRANSLATOR_REGION=your-region
AZURE_TRANSLATOR_ENDPOINT=your-endpoint
```

🛠️ Usage
--------

[](#️-usage)

### Automatic Generation (Recommended)

[](#automatic-generation-recommended)

Generate all translation files automatically without any interactive prompts:

```
# Generate for default locales (configured in config/localizator.php)
php artisan localizator:generate

# Generate for specific locales
php artisan localizator:generate en es fr de

# Silent mode (no output except errors)
php artisan localizator:generate --silent

# With AI auto-translation
php artisan localizator:generate es fr --auto-translate

# Generate JSON files instead of PHP
php artisan localizator:generate en --format=json

# Force overwrite without backup
php artisan localizator:generate en --force
```

### Interactive Scanning

[](#interactive-scanning)

Scan your application with interactive prompts and review options:

```
php artisan localizator:scan en es fr de
```

### Advanced Options

[](#advanced-options)

The scan command supports various options for different use cases:

```
# Dry run - see what would be done without making changes
php artisan localizator:scan en --dry-run

# Remove missing translation keys (clean up unused keys)
php artisan localizator:scan en --remove-missing

# Sort translation keys alphabetically
php artisan localizator:scan en --sort

# Enable AI-powered auto-translation
php artisan localizator:scan es fr --auto-translate

# Auto-translate with review process
php artisan localizator:scan es --auto-translate --review

# Specify AI provider and source language
php artisan localizator:scan es --auto-translate --provider=claude --source-lang=en

# Custom batch size for AI translations
php artisan localizator:scan es --auto-translate --batch-size=25

# Generate JSON files instead of PHP
php artisan localizator:scan en --format=json

# Create backups of existing files
php artisan localizator:scan en --backup

# Verbose output for debugging
php artisan localizator:scan en -v
```

### Command Comparison

[](#command-comparison)

Feature`localizator:generate``localizator:scan`**Interaction**Fully automatic, zero promptsInteractive with prompts and choices**Locale Selection**Uses config defaults or argumentsPrompts for locale selection if not specified**AI Review**Auto-accepts all translationsOptional review process for AI translations**Best for**CI/CD, automated workflowsManual control, reviewing translations**Speed**Fast, no waiting for inputSlower due to interactive prompts**Silent Mode**Yes (`--silent` flag)No**Configuration**Uses `locales` from configAlways prompts if no arguments**Recommendation**: Use `localizator:generate` for most cases, especially in automated environments. Use `localizator:scan` when you need to review and approve translations manually.

### Interactive Mode

[](#interactive-mode)

When you run the command without specifying locales, it will prompt you to select from supported languages:

```
php artisan localizator:scan
```

🔍 What Gets Scanned
-------------------

[](#-what-gets-scanned)

The package automatically detects and extracts translation keys from:

### Comment Detection & Skipping

[](#comment-detection--skipping)

**NEW in v1.4.0**: The package now automatically skips translation keys found in comments, preventing disabled or temporary keys from being added to your language files.

**Supported Comment Types:**

```
// C-style comments
/* {{ __('disabled.key') }} */

// Single-line comments
// {{ __('commented.key') }}

// Blade comments
{{-- {{ __('blade.disabled.key') }} --}}

// HTML comments

// Multiline comments
/*
 * {{ __('multiline.disabled.key1') }}
 * {{ __('multiline.disabled.key2') }}
 */
```

**Why This Matters:**

- ✅ Prevents cluttering language files with temporary/disabled keys
- ✅ Keeps your translations clean and organized
- ✅ Allows developers to comment out translations without affecting builds
- ✅ Works automatically - no configuration needed

### File Types Scanned

[](#file-types-scanned)

### PHP Files

[](#php-files)

```
__('auth.login.title')           // → resources/lang/en/auth.php: ['login' => ['title' => '...']]
trans('validation.email.required') // → resources/lang/en/validation.php: ['email' => ['required' => '...']]
trans_choice('messages.items', $count)
Lang::get('dashboard.widgets.summary')
Lang::choice('items.count', 5)
```

### Blade Templates

[](#blade-templates)

```
@lang('app.title')
@choice('messages.items', $itemCount)
{{ __('buttons.submit') }}
{{ trans('labels.name') }}
```

### Vue.js Components

[](#vuejs-components)

```

  {{ $t('dashboard.title') }}
  {{ $tc('users.count', userCount) }}

this.$t('notifications.success')
this.$tc('items.found', itemsFound)

```

### JavaScript Files

[](#javascript-files)

```
$t('messages.welcome')
$tc('items.selected', selectedCount)
```

🏗️ Intelligent Nested Structure
-------------------------------

[](#️-intelligent-nested-structure)

The package automatically organizes translation files based on dot notation keys, following Laravel's best practices:

### How It Works

[](#how-it-works)

**Translation Key** → **Generated File Structure**

- `auth.login.title` → `resources/lang/en/auth.php`

    ```
    return [
        'login' => [
            'title' => 'Login Title'
        ]
    ];
    ```
- `validation.custom.email.required` → `resources/lang/en/validation.php`

    ```
    return [
        'custom' => [
            'email' => [
                'required' => 'Email is required'
            ]
        ]
    ];
    ```

### Key Benefits

[](#key-benefits)

✅ **Organized Structure**: Files are automatically organized by context
✅ **Laravel Standard**: Follows Laravel's recommended translation file structure
✅ **Deep Nesting**: Supports unlimited nesting levels (`auth.forms.login.validation.required`)
✅ **Backward Compatible**: Can be disabled with `'nested' => false`
✅ **Merge Existing**: Intelligently merges with existing translation files

🧹 Remove Missing Keys
---------------------

[](#-remove-missing-keys)

**NEW in v1.4.0**: The `--remove-missing` option has been improved to properly clean up unused translation keys from your language files.

### How It Works

[](#how-it-works-1)

When you delete translation keys from your source code, they remain in your language files. The `--remove-missing` flag solves this by:

1. **Scanning** your codebase for currently used translation keys
2. **Comparing** with existing translation files
3. **Removing** keys that no longer exist in your source code
4. **Preserving** all keys that are still in use

### Usage Examples

[](#usage-examples)

```
# Remove unused keys from English translations
php artisan localizator:scan en --remove-missing

# Remove unused keys and create backups
php artisan localizator:scan en --remove-missing --backup

# See what would be removed without making changes
php artisan localizator:scan en --remove-missing --dry-run

# Remove unused keys from multiple locales
php artisan localizator:scan en es fr --remove-missing
```

### Before & After Example

[](#before--after-example)

**Before** (your source code changed):

```
// You removed this from your Blade file:
// {{ __('auth.old_feature') }}

// But kept this:
{{ __('auth.login.title') }}
```

**Translation file before cleanup:**

```
// resources/lang/en/auth.php
return [
    'login' => ['title' => 'Login'],
    'old_feature' => 'This is no longer used',  // ← Will be removed
];
```

**After running `--remove-missing`:**

```
// resources/lang/en/auth.php
return [
    'login' => ['title' => 'Login'],  // ← Preserved
    // 'old_feature' removed automatically
];
```

### Safety Features

[](#safety-features)

- ✅ **Dry Run**: Use `--dry-run` to preview changes before applying
- ✅ **Backups**: Use `--backup` to create timestamped backups
- ✅ **Incremental**: Only removes unused keys, preserves translations
- ✅ **Multi-format**: Works with both PHP and JSON translation files

🤖 AI Translation Features
-------------------------

[](#-ai-translation-features)

### Supported AI Providers

[](#supported-ai-providers)

- **OpenAI**: GPT-3.5 Turbo, GPT-4, and other models
- **Anthropic Claude**: Claude 3 Sonnet, Haiku, and Opus models
- **Google Translate**: Google Cloud Translation API
- **Azure Translator**: Microsoft Azure Translator Text API

### Translation Context

[](#translation-context)

Provide context to improve AI translations:

```
// config/localizator.php
'ai' => [
    'context' => [
        'domain' => 'e-commerce',      // Business domain
        'tone' => 'friendly',          // Communication tone
        'additional_context' => 'This is a Laravel application for online shopping',
    ],
],
```

### Batch Processing

[](#batch-processing)

AI translations are processed in batches to optimize API usage:

```
'ai' => [
    'batch_size' => 50,          // Translations per batch
    'rate_limit' => 60,          // Requests per minute
],
```

### Validation

[](#validation)

Automatic validation ensures translation quality:

- Placeholder preservation (`:name`, `{count}`, etc.)
- Length validation
- Key naming convention checks

📁 Output Formats
----------------

[](#-output-formats)

### JSON Format

[](#json-format)

```
{
    "welcome.message": "Welcome to our application",
    "auth.failed": "These credentials do not match our records",
    "dashboard.title": "Dashboard"
}
```

### PHP Array Format

[](#php-array-format)

#### Nested Structure (Default)

[](#nested-structure-default)

With `'nested' => true` in configuration, translation keys use dot notation to create organized, nested file structures:

```
// For keys like 'auth.login.title', 'auth.login.button'
// File: resources/lang/en/auth.php
return [
    'login' => [
        'title' => 'Login',
        'button' => 'Sign In',
        'failed' => 'These credentials do not match our records.',
    ],
    'register' => [
        'title' => 'Create Account',
        'button' => 'Sign Up',
    ],
    'logout' => 'Sign Out', // Single-level key
];

// For keys like 'validation.custom.email.required'
// File: resources/lang/en/validation.php
return [
    'custom' => [
        'email' => [
            'required' => 'Email is required',
            'email' => 'Must be a valid email',
        ],
        'password' => [
            'min' => 'Password must be at least 8 characters',
        ],
    ],
    'attributes' => [
        'first_name' => 'First Name',
        'last_name' => 'Last Name',
    ],
];
```

#### Flat Structure (Legacy)

[](#flat-structure-legacy)

With `'nested' => false`, keys remain flat within files:

```
// File: resources/lang/en/auth.php
return [
    'login.title' => 'Login',
    'login.button' => 'Sign In',
    'register.title' => 'Create Account',
];
```

🧪 Testing
---------

[](#-testing)

Run the package tests:

```
composer test
```

Run static analysis:

```
composer analyse
```

Fix code style:

```
composer format
```

Run all quality checks:

```
composer test && composer analyse && composer format
```

📈 Performance
-------------

[](#-performance)

The package is optimized for large codebases:

- **Efficient File Scanning**: Uses Symfony Finder for fast directory traversal
- **Regex Optimization**: Compiled patterns for translation function detection
- **Memory Management**: Processes files in chunks to handle large projects
- **Caching**: Optional caching of scan results to speed up subsequent runs

🛡️ Security
-----------

[](#️-security)

- Validates all translation keys against configurable patterns
- Sanitizes file paths and prevents directory traversal
- Respects Laravel's security practices for file operations
- API keys are stored securely in environment variables

🔧 Advanced Configuration
------------------------

[](#-advanced-configuration)

### Custom Translation Functions

[](#custom-translation-functions)

Add your own translation function patterns:

```
'functions' => [
    '__',
    'trans',
    'myCustomTransFunction',  // Your custom function
    'MyClass::translate',     // Static method
],
```

### File Exclusion

[](#file-exclusion)

Exclude specific files or directories:

```
'exclude' => [
    'vendor',
    'node_modules',
    'storage',
    'specific-file.php',
    'temp-directory',
],
```

### Custom Output Settings

[](#custom-output-settings)

Customize the generated files:

```
'output' => [
    'indent' => 2,              // Spaces for indentation
    'line_length' => 80,        // Maximum line length
    'comments' => true,         // Include generation comments
    'backup' => true,           // Create backups
],
```

🚨 Troubleshooting
-----------------

[](#-troubleshooting)

### Common Issues

[](#common-issues)

**1. No translation keys found**

- Check that your `functions` configuration includes all translation methods used in your codebase
- Verify that the `dirs` and `patterns` settings cover your file locations
- Ensure keys aren't all commented out (v1.4.0+ automatically skips commented keys)
- Use `--dry-run -v` to see detailed scanning information

**2. AI translation failures**

- Verify your API keys are correctly set in `.env`
- Check your API quotas and rate limits
- Use smaller batch sizes if encountering timeout errors

**3. --remove-missing not working**

- Ensure the command completed successfully (exit code 0)
- Check that translation keys were actually removed from your source code
- Use `--dry-run` to see what keys would be removed before running
- Verify you're scanning the correct directories with `--dry-run -v`

**4. Permission errors**

- Ensure Laravel has write permissions to the `resources/lang` directory
- Check file ownership and permissions

### Debug Mode

[](#debug-mode)

Enable verbose output for debugging:

```
php artisan localizator:scan en -v
```

### Log Analysis

[](#log-analysis)

Check Laravel logs for detailed error information:

```
tail -f storage/logs/laravel.log
```

🤝 Contributing
--------------

[](#-contributing)

We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

### Development Setup

[](#development-setup)

1. Clone the repository
2. Install dependencies: `composer install`
3. Run tests: `composer test`
4. Run static analysis: `composer analyse`
5. Fix code style: `composer format`

📄 Changelog
-----------

[](#-changelog)

Please see [CHANGELOG.md](CHANGELOG.md) for more information on what has changed recently.

🔒 Security
----------

[](#-security)

If you discover any security-related issues, please email  instead of using the issue tracker.

📝 License
---------

[](#-license)

The MIT License (MIT). Please see [License File](LICENSE.md) for more information.

🙏 Credits
---------

[](#-credits)

- [Syriable Team](https://github.com/syriable)
- [All Contributors](../../contributors)
- Inspired by [amiranagram/localizator](https://github.com/amiranagram/localizator)

🔗 Related Packages
------------------

[](#-related-packages)

- [Laravel Localization](https://github.com/mcamara/laravel-localization)
- [Laravel Translation Manager](https://github.com/barryvdh/laravel-translation-manager)
- [Laravel Lang](https://github.com/Laravel-Lang/lang)

💡 Tips & Best Practices
---------------------------

[](#-tips--best-practices)

### 1. Organize Translation Keys

[](#1-organize-translation-keys)

Use dot notation for hierarchical organization:

```
__('dashboard.widgets.sales.title')
__('forms.validation.required')
__('emails.welcome.subject')
```

### 2. Use Placeholders

[](#2-use-placeholders)

Keep translations flexible with placeholders:

```
__('welcome.greeting', ['name' => $user->name])
__('items.count', ['count' => $itemCount])
```

### 3. Review AI Translations

[](#3-review-ai-translations)

Always review AI-generated translations for:

- Cultural appropriateness
- Context accuracy
- Technical terminology
- Brand consistency

### 4. Version Control

[](#4-version-control)

Include translation files in version control but consider:

- Using separate branches for translation updates
- Implementing review processes for translation changes
- Automated testing for translation completeness

### 5. Performance Optimization

[](#5-performance-optimization)

For large applications:

- Use JSON format for better performance
- Enable caching in production
- Consider splitting translations into smaller, feature-specific files

---

Made with ❤️ by [Syriable](https://github.com/syriable)

###  Health Score

34

—

LowBetter than 77% of packages

Maintenance60

Regular maintenance activity

Popularity5

Limited adoption so far

Community2

Small or concentrated contributor base

Maturity56

Maturing project, gaining track record

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~0 days

Total

9

Last Release

255d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/41c7a871bce3ec9340de5018a05289674455998045dd9cb36fcc1df9c7be06c2?d=identicon)[syriable](/maintainers/syriable)

---

Tags

laravellocalizationi18ntranslationai

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StyleLaravel Pint

Type Coverage Yes

### Embed Badge

![Health badge](/badges/syriable-localizator/health.svg)

```
[![Health](https://phpackages.com/badges/syriable-localizator/health.svg)](https://phpackages.com/packages/syriable-localizator)
```

###  Alternatives

[mariuzzo/laravel-js-localization

Laravel Localization in JavaScript

6073.9M3](/packages/mariuzzo-laravel-js-localization)[kkomelin/laravel-translatable-string-exporter

Translatable String Exporter for Laravel

3291.4M10](/packages/kkomelin-laravel-translatable-string-exporter)[laravel-lang/publisher

Localization publisher for your Laravel application

2167.7M24](/packages/laravel-lang-publisher)[laravel-zero/framework

The Laravel Zero Framework.

3371.4M369](/packages/laravel-zero-framework)[tio/laravel

Add this package to localize your Laravel application (PHP, JSON or GetText).

170318.5k](/packages/tio-laravel)[aedart/athenaeum

Athenaeum is a mono repository; a collection of various PHP packages

255.2k](/packages/aedart-athenaeum)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)