Laravel Deepl Laravel Package

Technical Evaluation

Architecture fit

• Idiomatic Laravel package shape: service provider + DeepL facade + publishable config + two Artisan commands, wrapping the official deeplcom/deepl-php SDK rather than reimplementing the HTTP client. That is the right call — protocol churn is absorbed upstream.
• Two distinct usage modes with different risk profiles: (a) developer/CI-time tooling operating on lang/{locale}.json, and (b) runtime DeepL::translate() calls. Mode (a) is low risk and clearly the designed-for path; mode (b) puts a paid, network-bound third party in the request path.
• Fits Laravel's JSON-based localization convention only. No indication of support for PHP array lang files (lang/en/messages.php), Eloquent model translation, or DB-stored content — so scope is narrower than "translate the app."

Integration feasibility

• composer require simonet85/laravel-deepl, optional vendor:publish --tag=deepl-config, then a DeepL auth key in env. Free vs Pro inferred from the :fx key suffix — convenient, but means a key typo silently changes endpoint/billing tier behavior.
• Hard constraints: PHP 8.2+ and Laravel 11/12/13. Legacy L9/L10 or PHP 8.1 applications are excluded outright; validate the Laravel 13 claim against your actual target release calendar before committing.

Technical risk

• Cache-key correctness is the dominant risk. The advertised value ("a text already translated is not billed twice") is only safe if the key includes target locale, source locale, formality, context, and tag-handling version. An incomplete key serves wrong-language or wrong-tone output from cache — strictly worse than paying twice.
• Placeholder protection is necessary but likely insufficient as described. :count and & < > are handled; undocumented is Laravel pluralization (trans_choice pipe syntax {0} …|[1,*] …), ICU-style tokens, %s-style sprintf strings, and Blade {{ }}. Also unverified: whether DeepL may legally reorder protected tokens in ways that break grammar.
• Locale mapping (Laravel pt_BR/zh_CN ↔ DeepL PT-BR/ZH) needs explicit configuration; silent derivation will mis-target or fail at runtime.
• File mutation hazards: deepl:translate writes into source-controlled JSON. Needs atomic writes, stable key ordering (otherwise every run produces diff noise), and defined semantics for concurrent runs (two devs or CI + dev).
• --force is a governance footgun — it can overwrite human-reviewed copy with machine output. --scan= is heuristic and can pull unintended strings, inflating both cost and scope.
• Cost exposure: character-metered billing, multiplied by --scan/--force and by number of locales. Batches of 50 matches DeepL's per-request cap, so large catalogs mean many sequential requests.
• Supply chain: good upstream choice (official SDK), but this package is v1.0.0 from a single maintainer.
• Compliance: every translated string leaves your environment. Lang files routinely contain email templates, legal copy, and occasionally secrets/PII. EU-endpoint support for Pro and a DPA should be confirmed before use on production content.

Key questions

1. Exact cache key composition, and how invalidation works when formality/context/glossary config changes?
2. Are DeepL glossaries supported or planned? Without them, terminology consistency across releases is manual.
3. Is --scan= AST-based (Blade/PHP __() call detection) or regex? What is the false-positive profile?
4. How are trans_choice pluralization pipes and ICU syntax protected?
5. Retry/backoff on 429 and quota-exceeded (456)? What happens on partial batch failure — are files left unwritten?
6. Does usage() hit the API or the cache, and is it per-key or account-wide?
7. PHP array lang file support on the roadmap?
8. License, test coverage, and CI matrix (PHP 8.2/8.3/8.4 × Laravel 11/12/13)?

Integration Approach

Stack fit

• Target: Laravel 11+ apps on PHP 8.2+, already using lang/*.json, with a DeepL Pro account (Pro is effectively required for glossaries, EU endpoint, and predictable billing).
• Poor fit: apps localizing database content, model attributes, or user-generated text — no trait, no queued job, no batch abstraction is advertised. Use the official SDK directly instead.

Migration path

• Greenfield: require → publish config → set key → php artisan deepl:translate fr --dry-run → review diff → real run → commit.
• Backfill: safe by default, since the command only fills missing keys in existing files. Human-authored strings are preserved unless --force is used — keep --force out of the default workflow.
• Blocked: PHP <8.2 or Laravel ≤10. The fallback is a ~100-line internal service around deeplcom/deepl-php; the package is thin enough that this is a realistic contingency.

Compatibility

• Pin both the package and the SDK; validate the PHP/Laravel matrix in your own CI rather than trusting the README.
• Output is plain JSON, so coexistence with laravel-lang, IDE i18n plugins, and existing review tooling is fine — but assign clear ownership of lang/*.json to avoid write conflicts.

Sequencing

1. PoC on one low-stakes locale, --dry-run only.
2. Configure properly: persistent shared cache store (not array), formality, context, explicit locale map.
3. Add a CI gate that runs the command in dry-run and reports drift, before allowing any writes in automation.
4. Wire cost guardrails: scheduled deepl:usage check with a monthly threshold alert.
5. Only after 1–4 are stable, consider --scan and any --force usage, and restrict both to a single owning pipeline.

Operational Impact

Maintenance

• Small code surface, but a young dependency. Track releases; keep the option to fork — replacing the facade with direct SDK calls is roughly a day of work given how thin the wrapper is. Pin exact versions and review lockfile diffs.

Support

• Author/community support only, no vendor SLA, v1.0.0. Assume internal ownership of the translation pipeline, the lang files, and the DeepL billing relationship.

Scaling

• The scaling axis is character volume and locale count, not request throughput. Cache hit rate is the primary cost lever: the first full-locale run is the expensive one; subsequent runs should be near-free for unchanged strings.
• Large key sets require many 50-text batches. Without documented retry/backoff, big catalogs risk timeouts and mid-run aborts.
• Do not call translate() in request paths: it adds latency and makes your uptime a function of DeepL's. If runtime translation is genuinely needed, queue it and cache aggressively.

Failure modes

• Invalid/missing auth key → hard failure at first use; ensure the error surfaces clearly rather than as an empty lang file.
• Quota exhausted (456) or rate limited (429) mid-run → partial translation; command must fail loudly, not silently write a half-filled file.
• Stale cache with mismatched formality/context → wrong tone shipped with no visible symptom.
• --force clobbering reviewed copy; --scan capturing unintended strings; concurrent runs racing on the same JSON file.
• DeepL outage during CI → decide now whether that blocks builds (it shouldn't; make the check non-blocking).

Ramp-up

• Low for developers: a facade and two Artisan commands, learnable in hours. The real effort is policy, not code — who owns source strings, whether --force is ever permitted, cache store choice, a maintained locale mapping table, and a mandatory review gate for machine output (especially marketing/legal copy where formality and terminology matter).
• Publish a short runbook: dry-run → review diff → commit, plus a quota check before any large-locale run, plus a documented "what to do when the run fails halfway" step.