PHPackages                             lukasccb/laravel-ai-translations - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Localization & i18n](/categories/localization)
4. /
5. lukasccb/laravel-ai-translations

ActiveLibrary[Localization & i18n](/categories/localization)

lukasccb/laravel-ai-translations
================================

Scan, manage, and AI-translate \_\_() strings stored in the database for Laravel applications.

v0.0.1(1mo ago)02↑2900%MITPHPPHP ^8.2

Since Mar 27Pushed 1mo agoCompare

[ Source](https://github.com/LukasCCB/laravel-ai-translations)[ Packagist](https://packagist.org/packages/lukasccb/laravel-ai-translations)[ Docs](https://github.com/LukasCCB/laravel-ai-translations)[ RSS](/packages/lukasccb-laravel-ai-translations/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (1)Dependencies (11)Versions (2)Used By (0)

Laravel AI Translations
=======================

[](#laravel-ai-translations)

[![Latest Version on Packagist](https://camo.githubusercontent.com/a65b1c289d8a3ebc0f7dd78496dfa6530fcb07a6c8062ebadecc4f52105cc415/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6c756b61736363622f6c61726176656c2d61692d7472616e736c6174696f6e732e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/lukasccb/laravel-ai-translations)[![License](https://camo.githubusercontent.com/08490737261f13a1b02505ac55d2e06e67fbecf26d74ad5dafcf4c196a67a1e4/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f6c756b61736363622f6c61726176656c2d61692d7472616e736c6174696f6e732e7376673f7374796c653d666c61742d737175617265)](LICENSE.md)

A Laravel package that automatically scans your codebase for `__()` translation strings, stores them in the database, and translates them to any language using AI — powered by [Prism](https://github.com/prism-php/prism).

What It Does
------------

[](#what-it-does)

Instead of manually maintaining JSON/PHP translation files for every language, this package:

1. **Scans** your entire codebase (Blade, PHP, JS, Vue) for `__()`, `trans()`, `@lang()`, and `Lang::get()` calls
2. **Stores** every unique string in a `translations` database table
3. **Translates** all strings to any target language using AI (OpenAI, Anthropic, etc. via Prism)
4. **Serves** translations at runtime by hooking into Laravel's translation system — zero code changes needed

Your existing `__('Hello World')` calls just work. No file management, no copy-pasting, no manual editing.

Benefits
--------

[](#benefits)

- **Zero migration effort** — works with any existing Laravel app that uses `__()` strings
- **Database-driven** — all translations live in one table, easy to query, export, or edit
- **AI-powered** — translate hundreds of strings to any language in minutes, not days
- **Case-sensitive** — distinguishes between "paid" and "Paid" as separate entries
- **Database column scanning** — also picks up translatable strings stored in your database tables
- **Cached** — translations are cached per locale with configurable TTL
- **Auto-invalidation** — cache clears automatically when translations are created, updated, or deleted
- **Pluggable AI** — swap the default Prism translator for any provider via a simple interface
- **24 languages** included out of the box (en, pt, es, fr, de, it, nl, ru, zh, and more)

Requirements
------------

[](#requirements)

- PHP 8.2+
- Laravel 11, 12, or 13
- MySQL (recommended, for case-sensitive collation) or SQLite/PostgreSQL
- [Prism](https://github.com/prism-php/prism) (optional — only needed for AI translation commands)

Installation
------------

[](#installation)

### 1. Install the package

[](#1-install-the-package)

```
composer require lukasccb/laravel-ai-translations
```

The service provider is auto-discovered. No manual registration needed.

### 2. Publish the config and migration

[](#2-publish-the-config-and-migration)

```
php artisan vendor:publish --tag=ai-translations-config
php artisan vendor:publish --tag=ai-translations-migrations
```

### 3. Run the migration

[](#3-run-the-migration)

```
php artisan migrate
```

### 4. (Optional) Install Prism for AI translations

[](#4-optional-install-prism-for-ai-translations)

```
composer require prism-php/prism
```

Configuration
-------------

[](#configuration)

After publishing, edit `config/translation.php`:

```
return [

    // The source language of your project
    'source_language' => 'en_US',

    // Default batch size for AI translation runs
    'batch_size' => env('TRANSLATION_BATCH_SIZE', 500),

    // Directories and file types to scan
    'scan' => [
        'paths' => [
            resource_path('views'),
            app_path(),
            base_path('lang'),
            resource_path('js'),
        ],
        'extensions' => ['php', 'blade.php', 'js', 'vue'],
        'exclude' => [
            base_path('vendor'),
            base_path('node_modules'),
            // ...
        ],
    ],

    // Database columns that contain translatable strings (read-only)
    'database_scan' => [
        'roles' => ['name', 'description'],
        'settings' => [
            'column'        => 'value',
            'filter_by'     => 'key',
            'filter_values' => ['site_description', 'meta_title'],
        ],
    ],

    // AI translator class (implements TranslatorInterface)
    'translator' => \LukasCCB\AiTranslations\Translators\PrismTranslator::class,

    // AI provider settings (used by PrismTranslator)
    'ai' => [
        'provider'   => env('TRANSLATION_AI_PROVIDER', 'openai'),
        'model'      => env('TRANSLATION_AI_MODEL', 'gpt-4o-mini'),
        'max_tokens' => env('TRANSLATION_AI_MAX_TOKENS', 500),
    ],

    // Cache TTL in seconds (0 = disabled)
    'cache_ttl' => env('TRANSLATION_CACHE_TTL', 3600),

    // Custom locale resolver for the SetLocale middleware (null = use session)
    'locale_resolver' => null,
];
```

Add these to your `.env`:

```
TRANSLATION_AI_PROVIDER=openai
TRANSLATION_AI_MODEL=gpt-4o-mini
TRANSLATION_BATCH_SIZE=500
TRANSLATION_CACHE_TTL=3600
```

Usage
-----

[](#usage)

### Step 1: Scan your codebase

[](#step-1-scan-your-codebase)

```
php artisan translations:scan
```

This will:

- Find every `__()`, `trans()`, `@lang()`, and `Lang::get()` call in your project
- Extract translatable strings from configured database columns
- Insert new strings into the `translations` table (source language)
- Automatically clean up orphaned strings that no longer exist in the codebase

Options:

```
# Custom batch size for DB insertion
php artisan translations:scan --batch=200

# Force mode: re-insert and delete obsolete records
php artisan translations:scan --force
```

### Step 2: Translate to a target language

[](#step-2-translate-to-a-target-language)

```
php artisan translations:start --lang=pt_BR --alias="Portugues (Brasil)"
```

This sends each source string to the configured AI provider and stores the translation.

Options:

```
# Limit how many strings to translate in one run
php artisan translations:start --lang=pt_BR --alias="Portugues (Brasil)" --batch=100

# Re-translate everything, even already translated strings
php artisan translations:start --lang=pt_BR --alias="Portugues (Brasil)" --force
```

### Step 3: Auto-translate all languages

[](#step-3-auto-translate-all-languages)

If you have multiple target languages already registered:

```
php artisan translations:auto-translate
```

This finds all languages with at least one record and translates any missing strings.

### Cleanup orphaned strings

[](#cleanup-orphaned-strings)

```
php artisan translations:cleanup
```

Removes translation records (across all languages) for strings that no longer exist in your codebase. This is also called automatically before every scan.

Middleware
----------

[](#middleware)

Register the `SetLocale` middleware to automatically set the application locale per request:

```
// bootstrap/app.php (Laravel 11+)
->withMiddleware(function (Middleware $middleware) {
    $middleware->web(append: [
        \LukasCCB\AiTranslations\Middleware\SetLocale::class,
    ]);
})
```

By default, it reads from `session('locale')` and falls back to the configured `source_language`. You can customize this with a locale resolver:

```
// config/translation.php
'locale_resolver' => function (\Illuminate\Http\Request $request): ?string {
    return $request->user()?->preferred_locale;
},
```

Dispatching Translations via Queue
----------------------------------

[](#dispatching-translations-via-queue)

For long-running translation batches, use the built-in job:

```
use LukasCCB\AiTranslations\Jobs\TranslateLanguageJob;

TranslateLanguageJob::dispatch(
    lang: 'es_ES',
    alias: 'Espanol (Espana)',
    batch: 200,
    force: false,
);
```

Custom AI Translator
--------------------

[](#custom-ai-translator)

The package uses `TranslatorInterface` to decouple from any specific AI provider. To use your own:

### 1. Implement the interface

[](#1-implement-the-interface)

```