Laravel Ai Translator Laravel Package

Getting Started

laravel-ai-translator is a Laravel package that automates translation of your lang/ files using LLM providers. In 1.7.22 the default provider switched to OpenRouter, which means you can point at one API key and swap between dozens of underlying models without touching config structure.

Minimal steps:

1. composer require kargnas/laravel-ai-translator
2. Publish config: php artisan vendor:publish --tag="ai-translator-config"
3. Set OPENROUTER_API_KEY in .env (the new default)
4. Have a source locale fully populated, e.g. lang/en/messages.php
5. Run the translation command (typically php artisan ai:translate or similar — check php artisan list for the exact signature) targeting your other locales.

First use case: take an existing lang/en/*.php tree and generate lang/es/*.php without hand-editing. Start with a single small file (e.g. auth.php) to validate your API key, model choice, and prompt behavior before running over the whole directory.

Where to look first:

• config/ai-translator.php — provider, model, source/target locales, chunk sizes, prompt templates.
• The package's artisan commands (php artisan list | grep -i translat).
• Model pricing output, since 1.7.22 loads live model pricing — useful for picking a cost-appropriate model before committing to a large backfill.

Implementation Patterns

Provider/model selection. Because OpenRouter is now the default, the common pattern is one OPENROUTER_API_KEY plus a TRANSLATOR_MODEL env var. Pin a cheap model for bulk passes (e.g. translation of large validation.php files) and a stronger model for customer-facing strings. Keep model names in config, not hardcoded in code.

Source of truth workflow. Treat lang/en/ as canonical and never hand-edit generated files in other locales. Re-run the command after English changes; the package is designed around reconciling existing translated files rather than regenerating everything. Run it in CI as a check step (dry-run if supported) so missing translations fail the build rather than silently shipping.

Integration with existing pipelines. Commit generated locale files. Do not run the translator at deploy time — it's network-bound and non-deterministic. Instead, generate locally or in a scheduled job, review the diff, and commit. This keeps deploys fast and translations auditable.

Chunking large files. validation.php is huge; expect the package to chunk long arrays. Tune the chunk size in config if you hit timeouts or truncated output. For very large trees, translate locale-by-locale (or file-by-file) rather than all targets in one invocation, so a single failure doesn't discard the whole run.

Cost control with live pricing. Since 1.7.22 fetches live pricing, inspect the current per-model rates before choosing a default. For a mid-sized app (a few thousand strings × several locales), OpenRouter's cheap models make this near-free; a top-tier model can get expensive quickly across many locales.

Local overrides via env. Keep OPENROUTER_API_KEY, model, and target locales in .env per environment (local dev can point at a cheap model; a "translation" CI job can use a stronger one).

Gotchas and Tips

• Default provider changed in 1.7.22. If you were on an older version relying on OpenAI/Anthropic as the implicit default, 1.7.22 now defaults to OpenRouter. Set your provider explicitly in config to avoid surprise 401s or unexpected model changes after upgrading.
• OPENROUTER_API_KEY may not exist in your .env yet. Existing installs upgrading to 1.7.22 may fail with "no API key" until you add it or explicitly set an alternate provider.
• Symfony 8 support (symfony/process ^8.0) is now allowed — relevant if you're on Laravel 12 / Symfony 8 toolchains. If you previously had to pin symfony/process to ^7, you can drop that constraint.
• Live model pricing requires network calls. If the package fetches pricing on every run (or at boot), you may see slower startup in air-gapped/CI environments. Cache or disable if it becomes a bottleneck; check config for a pricing-cache TTL.
• Non-deterministic output. LLM translations vary run to run. Use a low temperature setting in config for consistency, and always review generated strings for the locale — especially brand names, placeholders (:attribute, {name}), and pluralization rules.
• Placeholder integrity is the #1 bug source. Verify :name, {0}, %s, and Laravel pluralization (|) survive translation. Add a small test that loads each locale file and asserts placeholder parity with English.
• PHPStan memory fix (1.7.22): the callback/parsing path had a memory issue in earlier 1.7.x — upgrading resolves OOMs during large-file parsing. If you're on 1.7.21 and seeing memory spikes during translation of big files, upgrade.
• JSON vs PHP lang files. Confirm your app's lang/ layout (JSON or PHP arrays); generated output format must match what your __() calls expect.
• Gitignore check. Don't accidentally commit .env with your OpenRouter key — the package reads it directly, so a leaked .env is a billed risk.
• Extension points. If translation quality is off for a domain-specific area, override the prompt template in config rather than patching vendor files. The package exposes prompt config for exactly this reason.