README

Translate an existing Laravel website when a visitor chooses a language. Keep your Blade text, original product records, and custom interface.

Composer installs the headless engine; it does not add a visible widget or invent provider credentials. Run the guided installer once to select public pages and languages, supply your backend API key, and add your own language control. The SDK then loads automatically on those public pages.

<button type="button" data-at-locale="ckb">کوردی</button>
<button type="button" data-at-locale="ar">العربية</button>
<button type="button" data-at-locale="en">English</button>

await AutoTranslate.setLocale('ckb');

Laravel AutoTranslate AI is an independent MIT-licensed package. It is not developed, endorsed, or maintained by Laravel or its creators.

Compatibility

Stable release 1.1.0 is installed with Composer's default stability policy. The package supports Laravel 12 on PHP 8.2–8.5 and Laravel 13 on PHP 8.3–8.5. Its Composer identity is a4hmad1/laravel-autotranslate-ai.

These combinations are checked with isolated PHP runtimes, fresh dependency resolution, Pest/Testbench, and Larastan. See the compatibility guide, matrix results, and verification report. Laravel 10 and 11 are not claimed as supported: their dependency resolution was rejected by Composer's security-advisory protection. Composer security checks remain enabled.

Installation

Install the stable package with:

composer require a4hmad1/laravel-autotranslate-ai

For local package development, add a Composer path repository pointing to this checkout and explicitly require the development branch:

composer config repositories.autotranslate path /absolute/path/to/laravel-autotranslate
composer require a4hmad1/laravel-autotranslate-ai:@dev

Laravel discovers the service provider automatically. Composer does not publish files, edit routes/templates, create credentials, or activate translation on private pages.

Activate once

php artisan autotranslate:install
php artisan autotranslate:doctor

The guided installer publishes configuration and the complete tutorial, asks for the original language, enabled language codes, and the public paths that may be translated, and optionally accepts a hidden Google API key to save in .env. Existing manually managed configuration is retained unless you deliberately use --force after reviewing it.

For automation, set GOOGLE_TRANSLATE_API_KEY in your deployment environment first:

php artisan autotranslate:install --source=en --locales=ckb,ar --routes="/,catalog,products/*" --no-interaction

Quote the --routes argument if your shell expands wildcards. The source locale is included automatically. Run autotranslate:doctor after setup; a nonzero exit reports missing credentials, targets, public-page integration, application encryption key, or a working lock-capable cache. A doctor success means local setup is ready, not that a billable provider request has been made.

Add your own language control

Place this optional unstyled component in your existing Blade layout:

<x-autotranslate-switcher />

Or use your own data-at-locale buttons or AutoTranslate.setLocale('ckb') call. No npm or Vite build is required for the SDK. The site owns the selector design. There is no automatic visible button after Composer installation.

The guided setup writes preferences like these to .env:

AUTOTRANSLATE_SOURCE=en
AUTOTRANSLATE_LOCALES=en,ckb,ar
AUTOTRANSLATE_ROUTES=/,catalog,products/*
GOOGLE_TRANSLATE_API_KEY=your-restricted-server-api-key

Only the selected public GET pages receive signed source metadata and the versioned SDK. For multiple hosts, configure shared lock-capable caching; a single-host development setup may use AUTOTRANSLATE_CACHE_STORE=file. Database cache stores require their ordinary Laravel storage to be available.

The explicit integration from 1.0 remains supported: assign autotranslate middleware to reviewed public routes inside web. @autotranslate is now an optional placement marker; full HTML pages with the middleware load the SDK automatically even without that directive. For bundler-managed SDK initialization, set integration.inject_sdk to false.

Publish the included complete tutorial separately with:

php artisan autotranslate:docs

Read the activation guide when the package installed but nothing appears or window.AutoTranslate is undefined.

How translation works

The opt-in middleware inspects rendered HTML and issues short-lived, session-bound proofs for eligible public text. The SDK collects visible content, retains its original source, deduplicates units, and sends bounded batches. Laravel validates proofs and locale capabilities, checks translation memory and cache, reserves a character budget, and calls the provider. Translations are assigned as plain text. A newer language transition invalidates older responses.

A switch from Kurdish to Arabic always uses original English content. Returning to English restores original strings. On the next full page navigation, source HTML renders first and the encrypted first-party locale cookie triggers translation again. There is no page reload during a normal language switch.

const result = await AutoTranslate.setLocale('ar', {
    onSuccess(result) { console.log(result.translated); },
    onError(error) { console.error(error.code); }
});
AutoTranslate.getLocale();
AutoTranslate.getLocales();
AutoTranslate.getState();
await AutoTranslate.refresh(document.querySelector('main'));
await AutoTranslate.reset();

A transition rejects if required translation or persistence fails. Partial coverage emits translation:partial and rejects by default, restoring source content. allowPartial: true explicitly permits mixed-language content with a partial result. See JavaScript API.

Database content

A rendered {{ $product->name }} is ordinary DOM text and can be translated without changing the product record. No observers, translated columns, or ProductTranslation models are installed. Optional translation memory lives in its own table, stores source hashes instead of source text, and supports approved overrides.

Providers and languages

Google Cloud Translation Basic v2 is the default production adapter. The reviewed built-in capability subset is English en, Arabic ar, and Kurdish Sorani ckb. Enabling a locale is separate from provider capability; Kurmanji ku is not Sorani. The configurable mapping cannot manufacture a capability.

The optional OpenAI Responses adapter requires an explicitly configured structured-output model and a developer-reviewed locale allowlist. No language quality guarantees are inferred from general model availability. Google and OpenAI credentials stay on the server. See providers for verified official contract links and setup.

Security and costs

Translation sends content to an external processor. Opt in only public pages. Authenticated pages are excluded by default. Mark private regions data-at-private before rendering and exclude any account, health, payment, or personal content. Heuristics are a secondary defense, not a privacy classifier. The endpoint rejects unsigned arbitrary text, applies CSRF protection and rate limits, validates input and output, and enforces a daily character budget.

Cache and optional memory reduce repeated paid calls. A lock-capable shared cache is required for reliable distributed budgets. File cache works on a single host. This package does not impose a guaranteed currency spend cap; configure provider-side quotas and billing alerts. See privacy and performance.

Example application

The Fieldwork storefront includes a seeded catalog, detail and category pages, search, custom language controls, HTML fragment loading, and a Livewire example. A clearly marked local-only fixture provider makes the complete request workflow runnable without credentials. Its sample output is not an AI translation quality demonstration.

Documentation

Read the tutorial, installation, configuration reference, quick start, switcher guide, backend API, dynamic content, Livewire, Inertia, Vue and React, customization, troubleshooting, testing, and upgrade policy.

Support and contribution

Report issues through the GitHub issue tracker. Include package and framework versions, a minimal public-text reproduction, expected behavior, and redacted logs. Never attach credentials, session proofs, private HTML, or customer text. Security issues should be reported privately; see SECURITY.md. Contribution guidance lives in CONTRIBUTING.md.

a4hmad1 / laravel-autotranslate-ai

Package info

Security

Statistics