Download the PHP package upon/mlang without Composer

MLang - The Performant Way to Handle Multilingual Laravel Models

Stop using JSON columns. Start using proper database structure for translations.

Quick Start • Why MLang? • Features • Documentation • Contributing

Why Another Translation Package?

Most Laravel translation packages store translations in JSON columns. This works, but has serious limitations:

• Can't query translations efficiently - Want to search products by name in French? Good luck with JSON.
• No database indexing - JSON columns can't be indexed properly, making searches slow.
• Complex migrations - Adding a new translatable field means updating JSON structure.

MLang takes a different approach: Each translation is a proper database row with row_id (linking translations together) and iso (language code). This means:

Quick Start

Why MLang?

When to Use MLang

Choose MLang if you need:

• Search/filter by translated fields (e-commerce, CMS, catalogs)
• Database-level performance for translations
• Translation coverage analytics
• Bulk translation operations

Stick with JSON-based packages if:

• You only display translations (no querying)
• You have very few translatable models
• You prefer simpler table structure

Documentation

• Version Compatibility
• Installation
• Features
• Database Structure
• Artisan Commands
• Using the Facade
• Query Usage
• Helper Classes
• Configuration Options
• Security Best Practices
• Contributing
• License

Features

Core Features

Developer Experience

Security & Performance

Installation

Requirements

Step 1: Install

Step 2: Configure Models

Step 3: Add Trait to Models

Alternative: You can also extend Upon\Mlang\Models\MlangModel if you prefer inheritance over traits.

Step 4: Run Migration

This adds two columns to your tables:

• row_id - Links translations together (same row_id = same content in different languages)
• iso - Language code (en, fr, de, etc.)

Artisan Commands

The package provides several Artisan commands for managing translations:

Command Examples

Using the Facade

MLang comes with a powerful facade that provides a fluent interface for interacting with the package.

Core Facade Methods

Migration & Generation Methods

🆕 Multi-Language Operations

🆕 Translation Statistics & Analysis

Basic Usage Examples

🆕 Multi-Language Insert (NEW!)

Create a record in multiple languages simultaneously:

🆕 Translation Statistics (NEW!)

Get insights into your translations:

🆕 Bulk Translation Operations (NEW!)

Manage all translations for a record using its regular ID - no need to know about row_id!

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.

Trait-based approach benefits: The trait-based approach makes it easy to work with factories before migrations, with enhanced column existence detection and 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.

Model Query Scopes

Finding Records

Querying with Conditions

Route Model Binding

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

How it works:

• The row_id from the URL is used to find the record
• The current application locale (app()->getLocale()) determines the language
• Returns 404 if no translation exists in the current language

Understanding Interface and Trait Relationship

When implementing MLang 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

🆕 Helper Classes

The package includes organized helper classes for better code organization and reusability.

SecurityHelper Methods

Example Usage:

LanguageHelper Methods

Example Usage:

TranslationHelper Methods

Example Usage:

QueryHelper Methods

Example Usage:

Security Best Practices

This package includes several security features:

1. Input Validation: All user inputs (model names, table names, locales) are validated before use
2. SQL Injection Prevention: Uses Laravel's Query Builder exclusively, no raw SQL with user input
3. Sanitization: Automatic sanitization of string values to remove null bytes and control characters
4. Rate Limiting: Built-in rate limiting for bulk operations to prevent abuse
5. Type Safety: Strong typing throughout the codebase with PHP 8.3+ features

Security Guidelines

Contributing

Contributions are welcome! Here's how you can help:

1. Star the repo - It helps others discover MLang
2. Report bugs - Open an issue with reproduction steps
3. Suggest features - We'd love to hear your ideas
4. Submit PRs - Bug fixes and improvements welcome

Support the Project

If MLang helps you build multilingual Laravel apps, please consider:

• Giving it a star on GitHub
• Sharing it with other Laravel developers
• Writing about your experience using it

License

MIT License - see LICENSE for details.

Built with care by Charisma Design

Report Bug • Request Feature • Contact