translatable-pro

#AI Translation

Translatable Pro can translate phrases using the Laravel AI SDK. Translations are available from the Phrases resource in Filament — per row or in bulk.

#Requirements

AI translation requires:

• PHP ^8.3
• Laravel ^12.0 || ^13.0 (required by laravel/ai)
• The Laravel AI SDK (laravel/ai) — installed automatically with Translatable Pro
• A configured AI provider API key
• A running queue worker for bulk translations

#Setup

Translatable Pro declares laravel/ai as a dependency, so it is installed when you require the package. You still need to publish the AI config and add your provider credentials.

Publish the Laravel AI configuration:

1php artisan vendor:publish --provider="Laravel\Ai\AiServiceProvider"

Add the API key for your chosen provider to .env. The default model is Google Gemini, so you typically need:

1GEMINI_API_KEY=your-api-key

Other supported providers (OpenAI, Anthropic, etc.) use their own keys — see the Laravel AI SDK documentation for details.

#Configuration

AI translation options are set in config/zeus-translatable-pro.php:

1'ai_provider' => 'gemini',
2 
3'ai_model' => 'gemini-3.5-flash',
4 
5'ai_agent_notes' => null,

You can override these per environment. The provider and model are passed to the TranslatePhrases agent and must match a provider configured in your Laravel AI SDK setup.

The fallback language (fallback_lang) is used to resolve the source phrase when translating a row that has no value yet.

#Custom agent notes

Use ai_agent_notes to append project-specific instructions to the translation agent prompt. This is useful for brand names that should stay untranslated, preferred terminology, tone, or domain-specific guidance.

1'ai_agent_notes' => <<<'NOTES'
2- Never translate the brand name "LaraZeus".
3- Use formal Arabic for admin panel labels.
4- "Dashboard" should always be translated as "لوحة التحكم".
5NOTES,

Leave it as null or an empty string to use only the built-in agent rules.

#Using AI Translation in Filament

The Phrases resource is registered by default (register_phrase_resource is true). From there you can:

#Translate a single phrase

Use the Translate with AI row action on any phrase record. The plugin finds a source phrase (preferring the fallback language), sends it to the AI agent, and saves the result into the current row.

#Bulk translate

Select multiple phrase records and choose Translate with AI. Each selected row is translated into its own language and dispatched to the queue via the TranslatePhrasesBulk job.

Make sure a queue worker is running:

1php artisan queue:work

#Programmatic Usage

You can trigger translations from your own code using PhraseAiTranslator:

1use LaraZeus\TranslatablePro\Models\Phrase;
2use LaraZeus\TranslatablePro\Services\PhraseAiTranslator;
3 
4// Translate one row into its own language
5PhraseAiTranslator::translateRow($phrase);

Bulk actions in Filament use TranslatePhrasesBulk, which calls translateRow() for each selected record asynchronously.

#How It Works

1. A source phrase is resolved — the record itself, the fallback language sibling, or any non-empty sibling sharing the same model and key.
2. Existing translations from other languages are included as context for terminology consistency.
3. The TranslatePhrases agent sends a structured prompt to the configured model, including any custom notes from ai_agent_notes.
4. The AI returns translations keyed by language and phrase ID; results are saved to the phrases table.

Placeholders (:name, {count}, %s, etc.), HTML, and markdown in the source text are preserved by the agent instructions.

#Troubleshooting

Trait Laravel\Ai\Promptable not found

Run composer update in your application so laravel/ai is installed. If you use a path repository for local development, update dependencies in both the package and the consuming app.

AI translation failed

Check that your provider API key is set, the model name in ai_model is valid for that provider, and your app can reach the provider API.

Bulk translations never complete

Ensure a queue worker is processing jobs and that TranslatePhrasesBulk is not failing silently — inspect failed_jobs or your queue logs.