Download the PHP package syriable/localizator without Composer

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

• 🔍 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

• PHP 8.3 or higher
• Laravel 12.0 or higher
• Composer

📦 Installation

Install the package via Composer:

Publish the configuration file:

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

⚙️ Configuration

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

Environment Variables

Add these to your .env file:

🛠️ Usage

Automatic Generation (Recommended)

Generate all translation files automatically without any interactive prompts:

Interactive Scanning

Scan your application with interactive prompts and review options:

Advanced Options

The scan command supports various options for different use cases:

Command Comparison

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

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

🔍 What Gets Scanned

The package automatically detects and extracts translation keys from:

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:

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

PHP Files

Blade Templates

Vue.js Components

JavaScript Files

🏗️ Intelligent Nested Structure

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

How It Works

Translation Key → Generated File Structure

• auth.login.title → resources/lang/en/auth.php

• validation.custom.email.required → resources/lang/en/validation.php

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

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

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

Before & After Example

Before (your source code changed):

Translation file before cleanup:

After running --remove-missing:

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

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

Provide context to improve AI translations:

Batch Processing

AI translations are processed in batches to optimize API usage:

Validation

Automatic validation ensures translation quality:

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

📁 Output Formats

JSON Format

PHP Array Format

Nested Structure (Default)

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

Flat Structure (Legacy)

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

🧪 Testing

Run the package tests:

Run static analysis:

Fix code style:

Run all quality checks:

📈 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

• 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

Custom Translation Functions

Add your own translation function patterns:

File Exclusion

Exclude specific files or directories:

Custom Output Settings

Customize the generated files:

🚨 Troubleshooting

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

Enable verbose output for debugging:

Log Analysis

Check Laravel logs for detailed error information:

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

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

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

🔒 Security

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

📝 License

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

🙏 Credits

• Syriable Team
• All Contributors
• Inspired by amiranagram/localizator

🔗 Related Packages

• Laravel Localization
• Laravel Translation Manager
• Laravel Lang

💡 Tips & Best Practices

1. Organize Translation Keys

Use dot notation for hierarchical organization:

2. Use Placeholders

Keep translations flexible with placeholders:

3. Review AI Translations

Always review AI-generated translations for:

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

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

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