README

A comprehensive Laravel package that provides an intuitive web interface for managing translation files and overrides. Features a modern Bootstrap 5 UI with advanced tools for comparing, editing, and synchronizing language files across multiple locales.

🚀 Features

Core Translation Management

Visual File Comparison: Side-by-side comparison of translation keys across multiple languages
Missing Key Detection: Automatically identifies missing translations with visual indicators
Real-time Editing: Edit translation values directly in the browser with instant validation
File Status Overview: Quick overview of translation completeness for each file

Advanced Override System

Translation Overrides: Create custom translation overrides without modifying core files
Searchable Key Selection: Select2-powered search through all translation keys across files
CRUD Operations: Complete create, read, update, delete functionality for overrides
Individual Record Management: Manage each override independently with precise control

Modern User Interface

Bootstrap 5 Design: Clean, responsive interface that works on all devices
Interactive Components: Modern modals, dropdowns, and form elements
Visual Feedback: SweetAlert2 notifications for all user actions
File Organization: Intelligent file sorting with priority for files containing missing keys

Technical Features

Laravel 10+ Compatible: Full support for modern Laravel versions
PHP 8.0+ Support: Built with modern PHP features and type declarations
Middleware Protection: Configurable middleware for route protection
Asset Management: Organized CSS/JS assets with proper Laravel asset handling
Database Integration: Efficient database storage for translation overrides

📦 Installation

Step 1: Install via Composer

composer require mikailfaruqali/localization

Step 2: Publish Configuration

php artisan vendor:publish --tag=snawbar-localization-config

Step 3: Publish Assets

php artisan vendor:publish --tag=snawbar-localization-assets

Step 4: Run Migrations

php artisan vendor:publish --tag=snawbar-localization-migrations
php artisan migrate

⚙️ Configuration

Configure the package in config/snawbar-localization.php:

<?php

return [
    /*
    |--------------------------------------------------------------------------
    | Middleware Configuration
    |--------------------------------------------------------------------------
    |
    | Define the middleware that should be applied to the routes.
    | You can add authentication, authorization, or any custom middleware.
    |
    */
    'middleware' => ['web'],

    /*
    |--------------------------------------------------------------------------
    | Route Configuration
    |--------------------------------------------------------------------------
    |
    | Define the base route prefix for the localization package.
    | For example, if set to 'localization', the routes will be:
    | - /localization/view (file selector)
    | - /localization/compare (translation editor)
    |
    */
    'route' => 'localization',

    /*
    |--------------------------------------------------------------------------
    | Language File Path
    |--------------------------------------------------------------------------
    |
    | Define the path where language files are stored.
    | By default, this points to the application's `lang` directory.
    |
    */
    'path' => lang_path(),

    /*
    |--------------------------------------------------------------------------
    | Base Locale
    |--------------------------------------------------------------------------
    |
    | The base locale defines the default language for your application.
    | All other languages will be loaded based on this locale.
    |
    */
    'base-locale' => 'en',

    /*
    |--------------------------------------------------------------------------
    | Excluded Files
    |--------------------------------------------------------------------------
    |
    | Specify any language files that should be excluded from being loaded
    | or compared within the package.
    |
    */
    'exclude' => [
        // Add files to exclude, e.g., 'validation.php'
    ],
];

🎯 Usage

Accessing the Interface

Visit the localization manager in your browser:

https://your-app.com/localization/view

File Management

File Selector: The main dashboard shows all translation files with their completion status
Visual Status Indicators:
- ✅ Green check: All translations complete
- ⚠️ Yellow warning: Missing translations detected
File Selection: Click on any file card to open the translation editor

Translation Editor

Side-by-Side Comparison: View all languages for a file in organized columns
Edit Translations: Click on any translation value to edit it inline
Missing Key Highlighting: Missing translations are clearly marked
Bulk Save: Save all changes at once with validation

Override Management

Access overrides at: https://your-app.com/localization/overrides

Creating Overrides

Navigate to the Overrides section
Click "Add Override"
Search for Keys: Use the searchable dropdown to find translation keys
- Type to search across all translation files
- Format: file.key (e.g., auth.failed, validation.required)
- Preview original values in the dropdown
Select Language: Choose the target language
Enter Value: Provide the override translation
Save: Create the override

Managing Existing Overrides

View All: See all overrides in a organized table
Edit Values: Modify only the translation value (key and language are locked)
Delete: Remove overrides when no longer needed
Search: Find specific overrides quickly

🔧 Advanced Features

Database Structure

The package creates an override_translations table:

CREATE TABLE override_translations (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    key VARCHAR(255) NOT NULL,
    locale VARCHAR(2) NOT NULL,
    value TEXT NULL,
    UNIQUE KEY unique_key_locale (key, locale),
    KEY idx_key (key),
    KEY idx_locale (locale)
);

API Endpoints

The package provides RESTful endpoints:

Translation Files

GET /localization/view - File selector dashboard
GET /localization/compare?file={filename} - Translation editor
POST /localization/update - Save translation changes

Override Management

GET /localization/overrides - Override management interface
GET /localization/overrides/search?query={term} - Search translation keys
POST /localization/overrides/store - Create new override
POST /localization/overrides/update - Update existing override
DELETE /localization/overrides/delete - Delete override

Custom Middleware

Add authentication or authorization:

// config/snawbar-localization.php
'middleware' => ['web', 'auth', 'can:manage-translations'],

Route Customization

Change the base route prefix:

// config/snawbar-localization.php
'route' => 'admin/translations', // Changes URL to /admin/translations/view

File Exclusion

Protect sensitive files from editing:

// config/snawbar-localization.php
'exclude' => [
    'validation.php',
    'passwords.php',
    'pagination.php',
],

🎨 Customization

Styling

The package uses Bootstrap 5 with custom CSS. You can customize the appearance by:

Publishing Assets: php artisan vendor:publish --tag=snawbar-localization-assets
Modifying CSS: Edit public/vendor/snawbar-localization/css/app.css
Custom Themes: Add your own CSS classes

JavaScript Customization

Customize behavior by modifying:

public/vendor/snawbar-localization/js/app.js

Views

Publish and customize views:

php artisan vendor:publish --tag=snawbar-localization-views

Then modify:

resources/views/vendor/snawbar-localization/

🔒 Security Considerations

Middleware Protection: Always use appropriate middleware for production
File Permissions: Ensure proper file system permissions
Input Validation: All inputs are validated and sanitized
CSRF Protection: All forms include CSRF tokens
File Exclusion: Exclude sensitive translation files

🐛 Troubleshooting

Common Issues

Assets not loading:

php artisan vendor:publish --tag=snawbar-localization-assets --force

Permission denied:

chmod -R 755 resources/lang/

Missing styles:

php artisan config:clear
php artisan view:clear

Debug Mode

Enable debug mode for development:

// .env
APP_DEBUG=true

📝 Changelog

Version 4.0.0 (Current)

✅ Complete Bootstrap 5 redesign with modern UI components
✅ Advanced override system with searchable keys via Select2
✅ Individual override record management with CRUD operations
✅ Improved database structure with optimized indexing
✅ Enhanced API structure with RESTful endpoints
✅ Real-time search through translation files
✅ Visual file status indicators with completion tracking
✅ Responsive design for all device sizes
✅ Enhanced validation and error handling
✅ Configurable route prefixes and middleware

Previous Versions

v3.x: Enhanced translation management features
v2.x: Override system implementation
v1.x: Initial release with basic translation file management

🤝 Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
Submit a pull request

📄 License

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

👥 Credits

Author: Mikail Faruq Ali
Package: Snawbar Localization
Framework: Laravel
UI: Bootstrap 5, Select2, SweetAlert2

Need help? Open an issue on GitHub or contact the maintainers. | ensuring session and CSRF protection support. | */

'middleware' => ['web'],

/*
|--------------------------------------------------------------------------
| Route Configuration
|--------------------------------------------------------------------------
|
| Define the base route prefix for the localization package. This prefix
| will be used for all routes related to localization management.
| For example, if set to 'localization', the routes will be:
| - /localization/view (to view translations)
| - /localization/update (to update translations)
|
| You can customize this prefix to fit your application's routing structure.
|
*/

'route' => 'localization',

/*
|--------------------------------------------------------------------------
| Language File Path
|--------------------------------------------------------------------------
|
| Define the path where language files are stored. By default, this points
| to the application's `lang` directory. This is where the package will
| load language files from.
|
| You can customize this if your language files are stored in a different
| location.
|
*/

'path' => lang_path(),

/*
|--------------------------------------------------------------------------
| Base Locale
|--------------------------------------------------------------------------
|
| The base locale defines the default language for your application.
| All other languages will be loaded based on this locale.
|
| You can customize this to match the primary language of your application.
| In most cases, 'en' for English is the default.
|
*/

'base-locale' => 'en',

/*
|--------------------------------------------------------------------------
| Excluded Files
|--------------------------------------------------------------------------
|
| Specify any language files that should be excluded from being loaded
| or compared within the package. Useful if certain files should not
| be modified through the UI.
|
*/

'exclude' => [
    'auth.php',
    'validation.php',
    'pagination.php',
    'passwords.php',
],

];


## Usage
Access the translation interface at:
http://your-domain.com/{route_prefix}/view

## Key Functionality:

- Edit Translations
- Navigate to desired language file
- Modify values in textareas
- Click "Save Translations"
- Automatic synchronization across files
- Compare Files
- View side-by-side translations
- Identify missing translations
- Highlight discrepancies

## Security
- Recommended Security Measures:
- Add authentication middleware:

```php
'middleware' => ['web', 'auth']

Restrict access to authorized users
Keep excluded files list updated
Excluding Files
Protect critical files by adding to the exclude array:

'exclude' => [
    'auth.php',
    'validation.php',
    'custom-protected.php'
]

Contributing

Fork the repository
Create feature branch:

git checkout -b feature/your-feature

Commit changes with descriptive messages -Push to branch -Create pull request

License

MIT License - See LICENSE file.

Credits

Developed by: Snawbar
Maintainer: Mikail Faruq Ali
Contact: alanfaruq85@gmail.com
GitHub: github.com/mikailfaruqali/localization

mikailfaruqali / localization

Maintainers

Details

README

🚀 Features

Core Translation Management

Advanced Override System

Modern User Interface

Technical Features

📦 Installation

Step 1: Install via Composer

Step 2: Publish Configuration

Step 3: Publish Assets

Step 4: Run Migrations

⚙️ Configuration

🎯 Usage

Accessing the Interface

File Management

Translation Editor

Override Management

Creating Overrides

Managing Existing Overrides

🔧 Advanced Features

Database Structure

API Endpoints

Translation Files

Override Management

Custom Middleware

Route Customization

File Exclusion

🎨 Customization

Styling

JavaScript Customization

Views

🔒 Security Considerations

🐛 Troubleshooting

Common Issues

Debug Mode

📝 Changelog

Version 4.0.0 (Current)

Previous Versions

🤝 Contributing

📄 License

👥 Credits

Contributing

License

Credits