Download the PHP package upon/mlang without Composer

High-Performance Multi-Language Package for Laravel

This package is a high-performance solution designed to provide efficient multi-language support for Laravel applications. It offers robust features and optimizations to ensure fast and reliable language management, making your application accessible to a global audience without sacrificing performance.

Version Compatibility

This package follows Laravel's major versioning for compatibility.

Note: If you are using Laravel 11 or 12, please use version ^2.0 of this package.
For Laravel 10, continue using version ^1.0.

The architecture has changed between versions - v1 uses model inheritance while v2 uses traits and interfaces.

Features

• Accelerated translation retrieval: Translation strings are efficiently retrieved from the same database table, minimizing database join queries and improving response times.
• Seamless integration with Laravel: The package integrates seamlessly with Laravel, leveraging its existing localization infrastructure while providing performance enhancements.
• Translation helpers: Helper functions and methods to translate your application's content into different languages.
• Language detection: Automatic language detection based on user's browser settings or manual language selection.
• Language fallbacks: Fallback support for missing translations to ensure users always see content in a supported language.
• Smart database structure: Custom columns for efficient language identification and relation management.
• Robust error handling: Intelligent error prevention when columns don't exist or when database operations aren't ready.
• Safe factory integration: Designed to work safely with factories even before migrations run.
• Smooth console integration: Terminal-friendly command output directly in your console.
• Flexible architecture:
  • Version 1: Model inheritance approach for simplicity
  • Version 2: Trait-based approach for more flexibility and compatibility with existing inheritance hierarchies
• Facade Support: Fluent facade interface for accessing MLang functionality directly

Database Structure

This package adds two essential columns to the models you specify:

• row_id: This column serves as the primary relation key across all languages, linking translations together.
• iso: This column holds the language code (e.g., en, fr, nl), identifying which language each record represents.

Requirements

• PHP >= 8.1 for version 1.x
• PHP >= 8.3 for version 2.x
• Laravel >= 10.0

This package requires the following dependency:

Installation

1. Install the package using Composer:

2. Publish the package configuration and language files:

3. Configure the package by modifying the config/mlang.php file according to your requirements. You can specify:

   • Supported locales
   • Default locale
   • Translatable models
   • Auto-generation settings
   • Auto-migration hooks
   • Observer behavior

4. Configure your models in the mlang config file:

5. Use MLang in your models:

For Version 1.x: Extend your models with MlangModel instead of the default Eloquent Model:

For Version 2.x: Use the trait and implement the interface instead of extending the model:

6. Run the migration command to add the required columns to your models:

Using the Facade

MLang comes with a powerful facade that provides a fluent interface for interacting with the package. After installation, you can use the facade as follows:

Configuration Options

The package offers various configuration options to fine-tune its behavior:

Working with Factories

The package is designed to work safely with factories even before migrations have run. It intelligently detects when MLang columns don't exist and avoids trying to use them in such cases.

To ensure smooth operation with factories:

1. Set 'auto_generate' => false in your config file when using factories before migrations.
2. The trait will automatically detect missing columns and adjust behavior accordingly.
3. After running migrations, you can enable auto-generation features.

Version 2.x additional benefits: The trait-based approach in version 2 makes it even easier to work with factories before migrations, as it has enhanced column existence detection and more graceful fallbacks.

Managing Translations

Using Artisan Commands

Generate translations for all models:

Generate translations for a specific model:

Generate for a specific language:

Remove a language from a table:

Using the Facade

You can also manage translations programmatically using the facade:

Language Detection

To automatically detect the user's browser language:

1. Add the locale middleware to your app/Http/Kernel.php file:

To manually set the language:

Query Usage

Both package versions provide the same query methods for working with multilingual content:

Finding Records

To find a record by ID, translated to the current application language:

Querying with Conditions

To query with conditions while respecting language context:

The trWhere method works like the normal where but automatically maps id to row_id and adds a language condition, allowing you to chain other query methods:

Route Model Binding

The package enhances Laravel's route model binding to automatically fetch the correct language version:

Understanding Interface and Trait Relationship

When implementing MLang v2.x in your models, it's important to understand the relationship between the interface and trait:

1. The Interface (MlangContractInterface) defines the contract that your models must fulfill to be MLang-compatible.

2. The Trait (MlangTrait) provides the actual implementation of the methods required by the interface.

You must use both together:

This provides several benefits:

• Contract Enforcement: Ensures all required methods are available
• Implementation Reuse: Reuses code through the trait
• Flexibility: Allows customization by overriding trait methods
• Type Safety: Provides better IDE support and static analysis

Contributing

Contributions are welcome! If you encounter any issues, have suggestions, or want to contribute to the package, please create an issue or submit a pull request on the package's GitHub repository.

License

This package is open-source software licensed under the MIT license. Feel free to use, modify, and distribute it as per the terms of the license.

Credits

This package was developed by Reymon Zakhary. Special thanks to the Laravel community for their support and inspiration.

Contact

If you have any questions or need further assistance, you can reach out to the package maintainer at [email protected].