README

A modular AI translation gateway for Laravel. Supports LLM providers via laravel/ai (OpenAI, Anthropic, Gemini, …) and LibreTranslate. Integrates with laravel-chained-translator to discover missing keys and persist results.

Installation

composer require statikbe/laravel-ai-translation

Publish the config file:

php artisan vendor:publish --tag=ai-translation-config

Optionally publish the default system prompt Blade view so you can customise it:

php artisan vendor:publish --tag=ai-translation-views

Drivers

laravel_ai (LLM — recommended)

Requires laravel/ai:

composer require laravel/ai

Configure your provider in config/ai-translation.php (or via .env):

AI_TRANSLATION_DRIVER=laravel_ai
AI_TRANSLATION_PROVIDER=openai   # openai | anthropic | gemini | ollama | …
AI_TRANSLATION_MODEL=gpt-4o

Set the provider API key expected by laravel/ai (see .env.example):

OPENAI_API_KEY=your-key

libretranslate (open-source machine translation)

AI_TRANSLATION_DRIVER=libretranslate
LIBRETRANSLATE_URL=https://libretranslate.com
LIBRETRANSLATE_API_KEY=your-key

null (testing / no-op)

Returns the input string unchanged. Useful in tests or when no provider is configured.

Getting started

1. Install the package and publish the config.

composer require statikbe/laravel-ai-translation
php artisan vendor:publish --tag=ai-translation-config

1. Choose a driver and provider in your .env.

AI_TRANSLATION_DRIVER=laravel_ai
AI_TRANSLATION_PROVIDER=openai

1. Set the matching API key for your provider.

OPENAI_API_KEY=your-key

Alternative provider keys (from .env.example):

ANTHROPIC_API_KEY=your-key
GEMINI_API_KEY=your-key
GROQ_API_KEY=your-key
MISTRAL_API_KEY=your-key
DEEPSEEK_API_KEY=your-key
XAI_API_KEY=your-key
AZURE_OPENAI_API_KEY=your-key
OLLAMA_API_KEY=optional
PERPLEXITY_API_KEY=your-key
OPENROUTER_API_KEY=your-key
VOYAGEAI_API_KEY=your-key

1. Run a translation.

php artisan ai-translation:translate nl

If you use queues, remember to restart workers after changing env/config.

Artisan command

Requires statikbe/laravel-chained-translator:

composer require statikbe/laravel-chained-translator

Translate all missing keys for a locale:

php artisan ai-translation:translate nl

Limit to specific groups:

php artisan ai-translation:translate nl --group=auth --group=validation

Override the driver:

php artisan ai-translation:translate nl --driver=libretranslate

Run synchronously (instead of dispatching queue jobs):

php artisan ai-translation:translate nl --sync

Preview what would be translated without saving anything:

php artisan ai-translation:translate nl --dry-run

Override the source locale:

php artisan ai-translation:translate nl --source=en

Programmatic usage

use Statikbe\AiTranslation\AiTranslationService;

// Single string
app(AiTranslationService::class)->translate('Hello world', 'en', 'nl');

// Batch
app(AiTranslationService::class)->translateBatch(
    ['greeting' => 'Hello', 'farewell' => 'Goodbye'],
    'en', 'nl'
);

// Translate all missing keys for a locale (requires chained-translator)
app(AiTranslationService::class)->translateMissingForLocale('nl');

// Queue missing keys for background processing
app(AiTranslationService::class)->queueMissingForLocale('nl');

Via the facade:

use Statikbe\AiTranslation\Facades\AiTranslation;

AiTranslation::translate('Hello', 'en', 'nl');
AiTranslation::driver('libretranslate')->translateBatch(['key' => 'text'], 'en', 'nl');

Queue configuration

AI_TRANSLATION_QUEUE=true
AI_TRANSLATION_QUEUE_CONNECTION=redis
AI_TRANSLATION_QUEUE_NAME=translations

Run the worker:

php artisan queue:work --queue=translations

Custom system prompts

Via config

Override globally in config/ai-translation.php:

'prompts' => [
    'system' => 'Your custom global prompt here.',
    'group_overrides' => [
        // Append to global prompt:
        'validation' => 'Keep validation messages concise and user-friendly.',
        // Fully replace the global prompt:
        'emails' => [
            'prompt'  => 'You are translating marketing email content. Use a warm, professional tone.',
            'replace' => true,
        ],
    ],
],

Via published Blade view

After publishing with php artisan vendor:publish --tag=ai-translation-views, edit resources/views/vendor/ai-translation/prompts/system.blade.php. The config value takes precedence if set.

Testing

composer test