README

A Filament plugin that enables Translation Overrides management in Laravel applications with an elegant admin interface. Supports both multi-tenant and single-tenant applications.

Features

Built-in Filament admin panel for managing translations
Support for both multi-tenant and single-tenant applications
Per-tenant translation management in multi-tenant setups
Global translation overrides for single-tenant applications
Seamless integration with Filament resources and panels
Support for multiple languages with easy switching
Support for vendor/package translations (lang/vendor/*)
Performance-optimized with automatic caching
Override translations without modifying Laravel's original translation files

Requirements

PHP 8.3+
Filament 3.2+

Installation

You can install the package via composer:

composer require jaysontemporas/translation-overrides

Publish the configuration file:

php artisan translation-overrides:install

This will publish the config file to config/translation-overrides.php and the migration file to create the Translation Overrides table.

Important: Before running migrations, you should review and update the configuration file to set your preferred table name, tenancy mode, and other settings.

Run the migrations after configuring:

php artisan migrate

Configuration

After publishing the configuration file, you can configure the package in config/translation-overrides.php:

return [
    // Cache duration in seconds
    'cache_duration' => 21600, // 6 hours
    
    // Filament navigation settings
    'navigation' => [
        'group' => 'Settings',
    ],

    // Access control
    'can_access' => [
        'role' => 'Super Admin',
    ],

    // Tenancy configuration
    'tenancy_enabled' => false, // Set to true for multi-tenant apps

    // Your tenant model (only needed if tenancy_enabled is true)
    'tenant_model' => null, // \App\Models\Team::class
    
    // Table name for storing Translation Overrides
    'table_name' => 'translation_overrides',
    'tenant_id_column' => null, // Ex. tenant_id, only used if tenancy_enabled is true
    
    // Supported languages
    'supported_languages' => [
        'en' => 'English',
        'es' => 'Spanish',
        'fr' => 'French',
        // Add more languages as needed
    ],
];

Usage

For Single-Tenant Applications (Non-Tenancy)

If you're using this package in a single-tenant application, set tenancy_enabled to false in your configuration:

// config/translation-overrides.php
return [
    'tenancy_enabled' => false,
    // ... other configuration
];

In this mode:

No tenant relationship is created in the database
All translation overrides are global to your application
No tenant filtering in the admin interface
The HasTenantTranslation contract is not required in your Model

For Multi-Tenant Applications

If you're using this package in a multi-tenant application, ensure tenancy_enabled is true:

// config/translation-overrides.php
return [
    'tenancy_enabled' => true,
    'tenant_model' => \App\Models\Team::class,

    'table_name' => 'translation_overrides',
    'tenant_id_column' => 'tenant_id',
    // ... other configuration
];

User Model Requirements (Multi-Tenant Only)

Your User model should implement the HasTenantTranslation contract:

use JaysonTemporas\TranslationOverrides\Contracts\HasTenantTranslation;

class User extends Authenticatable implements HasTenantTranslation
{
    // ...
    
    public function getTranslationTenantId(): int|null
    {
        if (Filament::getTenant()) {
            return Filament::getTenant()->id;
        }

        return null;
        
        // OR in simple tenancy structure, users table has tenant_id
        // return $this->tenant_id;
    }
}

Filament Integration

Registering the Plugin

Add the TranslationOverrides plugin to your Filament panel:

use JaysonTemporas\TranslationOverrides\TranslationOverridesPlugin;

public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->plugins([
            TranslationOverridesPlugin::make(),
        ])
        // ...
}

This will automatically register the TranslationOverride resource in your Filament admin panel under the configured navigation group (default: "Settings").

Customizing the Resource

You can override the default TranslationOverrideResource by creating your own resource class and configuring the plugin to use it. This is useful when you need to customize access controls, modify the interface, or add additional functionality.

Basic Usage

use JaysonTemporas\TranslationOverrides\TranslationOverridesPlugin;

public function panel(Panel $panel): Panel
{
    return $panel
        ->plugins([
            TranslationOverridesPlugin::make()
                ->usingResource(CustomTranslationOverrideResource::class),
        ]);
}

Example: Custom Access Control

Create a custom resource class that extends the default one:

use JaysonTemporas\TranslationOverrides\Filament\Resources\TranslationOverrideResource;

class CustomTranslationOverrideResource extends TranslationOverrideResource
{
    public static function canAccess(): bool
    {
        // Only allow super admins to access translation overrides
        return auth()->user()?->hasRole('super-admin');
    }
}

Admin Interface

Once installed, you'll have access to a dedicated translations management interface in your Filament admin panel where you can:

For Single-Tenant Applications:

Create, edit, and delete global translations
Filter translations by language
Search by translation key or value

For Multi-Tenant Applications:

Create, edit, and delete tenant-specific translations
Filter translations by language
Search by translation key or value
Assign translations to specific tenants

User Model Requirements (For Multi-Tenant)

Your User model should implement the HasTenantTranslation contract:

use JaysonTemporas\TranslationOverrides\Contracts\HasTenantTranslation;

class User extends Authenticatable implements HasTenantTranslation
{
    // ...
    
    public function getTranslationTenantId(): int
    {
        return Filament::getTenant()->id;
        
        // OR in simple tenancy structure, users table has tenant_id
        // return $this->tenant_id;
    }
}

Using Translations in Your Application

After configuring the Filament interface, you can use translations in your views:

// In blade templates
{{ __('message.greeting') }}

// In PHP code
__('message.greeting');

How It Works

This plugin provides a way to override translations without actually modifying Laravel's original translation files. When a translation key is requested:

Single-Tenant Mode:

The system first checks if a global translation override exists in the database
If found, it returns the custom translation
If not found, it falls back to Laravel's standard translation files

Multi-Tenant Mode:

The system first checks if a tenant-specific translation exists in the database
If found, it returns the tenant's custom translation
If not found, it falls back to Laravel's standard translation files

This approach allows you to:

Customize translations without duplicating translation files
Update translations through the admin interface without touching code
Keep the original Laravel translations intact for reference or fallback

Vendor Translations

This package supports vendor translations published by Laravel packages. When a package provides its own translations, they are typically published to:

lang/vendor/package-name/en
lang/vendor/package-name/es

The package automatically discovers and includes these vendor translations in your Translation Overrides management interface. Vendor translations will appear with their package name as a prefix (e.g., package-name.file.key).

To publish vendor translations from a package, you can use Laravel's standard vendor publish command:

php artisan vendor:publish --tag=package-name-translations

Once published, these translations will be automatically available in the translation management interface and can be customized per tenant (in multi-tenant mode) or globally (in single-tenant mode).

License

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

jaysontemporas / translation-overrides

Maintainers

Details