Download the PHP package dyahunter35/filament-translation-toolkit without Composer

Filament Translation Toolkit

A comprehensive, production-ready translation toolkit for Filament v5 — automatic UI translation, AI-powered translation generation, language file scaffolding, and a full dashboard to monitor translation health across your entire application.

Table of Contents

• Features
• Requirements
• Installation
• Configuration
• Quick Start
• Dashboard
• Artisan Commands
• Traits (Concerns)
• Translation File Structure
• AI Translation Service
• Templating System
• How It Works
• Publishing Assets
• Testing
• Changelog
• License

Features

Requirements

• PHP >= 8.2
• Laravel >= 13.x
• Filament >= 5.x
• spatie/laravel-package-tools >= 1.15

Installation

Step 1: Add the Package

Step 2: Add Views Path to Your Theme (Required for Dashboard Styling)

To ensure Tailwind CSS v4 compiles the classes used in the Translation Dashboard, add a @source directive in your main CSS file:

Then rebuild your assets:

Step 3: Publish the Config

This creates config/filament-translation-toolkit.php in your project.

Step 4: Configure Your Locales

Open config/filament-translation-toolkit.php:

Step 5: (Optional) Configure AI Translation

If you want AI-powered translation generation:

1. Create a free account at openrouter.ai
2. Generate an API key from Keys page
3. Add to your .env:

Step 6: Register the Dashboard (Optional)

To add the Translation Dashboard to your Filament panel:

Customizing Dashboard Navigation

You can customize the dashboard's navigation label, group, title, icon, and sort order from the config file or via environment variables:

Or via .env:

When set to null (default), the label, group, and title are automatically translated based on the active locale (English: "Translation Dashboard", Arabic: "لوحة التحكم بالترجمة").

Step 7: Use Traits in Your Filament Classes

Start using the translation traits in your existing classes (see Traits below).

Configuration

The full config file with all options:

Environment Variables

Quick Start

1. Add the Translatable Trait to Your Models

First, mark your Eloquent models as translatable by adding the Translatable trait:

Available properties:

Available methods:

2. Generate Translation Files for a Table

3. Add the Filament Traits to Your Resources

That's it — just add the trait. Translation is auto-activated:

4. Add the Trait to Your Relation Manager

That's it — your UI is now automatically translated!

5. Disable Translation for a Specific Class

If a page doesn't need translation, disable it per-class:

Or disable globally in .env:

Or in config:

6. Explicit Boot (Optional)

If the global auto-translation doesn't work for your setup, you can still call bootTranslation() explicitly:

Dashboard

The TranslationDashboard is a comprehensive monitoring page with 5 sections:

1. AI Service Status

• Green indicator: API key is configured and ready
• Red indicator with instructions: Shows step-by-step setup guide including:
  • How to create an OpenRouter account
  • How to generate an API key
  • Where to add it in .env
  • Direct link to get the API key

2. Missing Translation Files

• Scans all database tables with the Translatable trait
• Shows which tables are missing translation files per locale
• Per-language buttons — e.g., EN, AR — generates only for that specific locale
• All button — generates for all missing locales at once
• AI buttons per language — e.g., AI EN, AI AR — uses AI for that specific locale (only shown if API is configured)
• Use Resource Defaults toggle — when enabled, extracts navigation values (label, group, icon) from the Filament Resource class instead of generating generic values
• Loading indicators: Each button shows a spinner during processing and becomes disabled to prevent double-clicks. A global banner appears at the top of the dashboard while any action is running.

3. Translation Completeness

• Compares the base locale against all other locales
• Shows progress bars with percentages
• Displays key counts (e.g., 45/50)
• Tooltip on missing keys shows the actual missing key names

4. Model Relationships

• Auto-discovers all Eloquent models with the Translatable trait
• Shows all public relationship methods per model
• Green badge = translation file exists for that locale, red badge = missing
• Per-language buttons — e.g., EN, AR — generates only for that specific locale
• All button — generates for all missing locales at once
• Shows existing locales as green badges when translation already exists

5. All Translation Files (Collapsed)

• Lists every translation file
• Shows key count per locale
• Highlights files that are missing in certain locales

Artisan Commands

make:translation

Generate translation files for a database table. Supports both basic scaffolding and AI-powered generation.

Examples:

Requirements for AI mode:

• OPENROUTER_API_KEY must be set in .env
• The table must exist in the database

What AI mode does:

1. Reads all columns from the database table
2. Detects Eloquent relationships from the model
3. Sends everything to AI with a structured prompt
4. AI returns professional English and Arabic translations
5. Writes lang/en/{model}.php and lang/ar/{model}.php

Traits (Concerns)

Translatable — Model Trait

Mark your Eloquent models as translatable. The Translation Dashboard only shows models that use this trait.

Properties:

Methods:

HasTranslateConfigure — The Core Engine

The central trait that powers all auto-translation. Provides:

How it works (two modes):

What it translates:

Additional utilities:

HasResource

For Filament Resource classes. Provides:

Locale path is derived from the model name: App\Models\Company → company

You can override it:

HasSinglePage

For standalone Filament pages (not part of a Resource):

Locale path is derived from the class name: ExpenseSettings → expense_settings

HasResourcePage

For Resource sub-pages (View, Edit, Create):

HasRelationManager

For Relation Manager classes:

HasPage

For generic Page classes that belong to a Resource:

Translation File Structure

Resource Translation File

Relation Translation File

Key Naming Convention

AI Translation Service

The AiTranslationService sends database schema data to OpenRouter API and receives professionally translated UI labels.

How It Works

1. Reads table columns via Schema::getColumnListing()
2. Detects Eloquent relationships via reflection
3. Constructs a prompt with the template structure
4. Sends to OpenRouter API (configurable model)
5. Parses JSON response
6. Writes PHP translation files for each locale

Supported AI Models

Any model available on OpenRouter:

Customizing the Endpoint

If you want to use a different API provider:

Templating System

The package uses a Strategy pattern for translation templates. Two templates are included:

ResourceTemplate

Generates files with navigation, breadcrumbs, and fields keys.

RelationTemplate

Generates files with label, fields, filters, and actions keys.

Creating a Custom Template

Use it:

How It Works

Auto-Translation Flow (Global Mode — Recommended)

Auto-Translation Flow (Explicit Mode)

Locale Path Resolution

Publishing Assets

Published views will be at resources/views/vendor/filament-translation-toolkit/.

Testing

Package Structure

Changelog

Please see CHANGELOG for more information on recent changes.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

If you discover a security vulnerability within the package, please send an email to Dyahunter35 via [email protected]. All security vulnerabilities will be promptly addressed.

License

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