Laravel Gemini Translator Laravel Package

Product Decisions This Supports

Localization roadmap and market sequencing

• Quantifies the cost of opening a new locale: instead of estimating translator spend and 2–4 weeks of back-and-forth, the team can run --dry-run against the existing codebase to get an actual count of untranslated keys per locale. That number becomes the input to a build-vs-buy-vs-outsource decision rather than a guess.
• Enables a "thin locale" launch strategy: ship a machine-translated locale to validate demand in a market, then invest in human translation only where retention and revenue justify it.

Build vs. buy on the i18n toolchain

• Creates a credible low-cost baseline to compare against a TMS (Lokalise, Crowdin, Phrase) or an agency quote. The comparison is not "free vs. $X" but "free plus internal review time vs. $X plus vendor onboarding" — and this package makes the "free plus review time" side concrete.
• Informs whether we need translation memory, glossaries, and reviewer workflows as product requirements. If we adopt this package, those become gaps we consciously accept; if we buy a TMS, they are the justification.

Feature and scope decisions

• --skip-existing makes incremental localization a per-sprint activity rather than a release-blocking project. That directly enables "localize as you build" as a team policy, which is a process decision, not just a tooling one.
• The three modes (full sync, missing-only, refresh-only) map to three distinct product workflows: initial market launch, ongoing feature work, and correcting bad machine output after a glossary change. Being able to name those workflows is what lets you write a localization runbook.
• Module support (nwidart/laravel-modules) is a scoping signal: if the codebase is a modular monolith, this package consolidates module strings into one place, which reduces the number of surfaces a future TMS migration has to cover.

Engineering investment and sequencing

• Because output is plain lang/ PHP and JSON files, there is no lock-in at the data layer. The decision is reversible, which means it can be made early and cheaply and revisited after the first market data lands.
• The absence of a CI/CD or review-queue story is itself a roadmap item: if localization becomes business-critical, that gap is the first thing to fund (a review step, a diff gate, or a TMS integration), not a reason to delay the first locale.

Cost and risk modeling

• Gemini free-tier limits (roughly 15 requests/minute, 1,000/day) make cost predictable and near-zero for small projects, but they cap throughput. For a large backlog, you either pay for a higher tier or accept multi-run batch processing — a decision worth modeling before committing to a launch date.

When to Consider This Package

Strong fit

• Laravel 11/12/13 on PHP 8.3+, with strings already written through __(), @lang(), trans_choice(), or Vue $t() — the scanner depends on that convention, so a codebase with hardcoded copy will produce poor coverage.
• Internal tools, admin panels, back-office apps, and early-stage products where a slightly imperfect translation is a minor annoyance rather than a legal, brand, or safety problem.
• Teams with no localization budget and no in-house translator, where the alternative is not shipping the locale at all.
• Mid-sized string volumes and a handful of target languages, where a single command run and a spot-check are a realistic QA process.
• Modular monoliths already using nwidart/laravel-modules.
• Teams that want to prototype a locale before committing to a translation vendor.

Look elsewhere when

• The content is customer-facing marketing, legal, contractual, medical, or financial. Machine translation without a human review gate is a liability, and this package has no review queue, approval state, or per-string sign-off.
• You need translation memory or a maintained glossary. The --context flag passes project context to the model, but it is not a persistent, versioned glossary — repeated runs will not converge on your preferred terminology.
• You already run a TMS, or your non-Laravel surfaces (iOS, Android, marketing site, email templates) also need strings. A single-source-of-truth workflow will not come from a Laravel Artisan command.
• The codebase is on PHP < 8.3, or the deployment target is Windows-only without the pcntl extension — you lose the fork driver's throughput and fall back to sequential runs.
• You require vendor support, an SLA, or a security review of a third-party dependency. Signals here are thin: 69 stars, zero dependents, a single maintainer, and two major versions with breaking changes in recent history (v4 removed the --source option; v5 raised the PHP floor to 8.3). Adopt as a dev-time convenience, never as something production runtime depends on.
• The team cannot absorb version churn. Plan for a pinned version and a scheduled review, not automatic upgrades.

Adoption checklist before committing

• Confirm the translation-key scanner's coverage matches your actual templates — run --dry-run first and read translation_extraction_log.json for missed keys.
• Verify the Gemini API key handling fits your secrets policy, and decide whether runs are permitted from developer machines or must be CI-only.
• Establish a human spot-check step for the first locale; placeholder-mismatch detection is automated, but tone, formality, and product-specific terminology are not.
• Agree on ownership of lang/ in code review — machine-generated diffs need a reviewer, or quality silently drifts.

How to Pitch It (Stakeholders)

For executives — one paragraph This is a free, MIT-licensed Laravel command that scans our codebase for translatable text, machine-translates it with Google's Gemini AI, and writes standard Laravel language files. It converts "open a new market" from a multi-week, budgeted translation project into a single command we can run in an afternoon and preview without writing anything (--dry-run). It is a developer tool, not a runtime dependency — nothing ships to customers because of it, and removing it costs us nothing but the command itself. The tradeoff we are accepting: translations are unreviewed machine output, so this is the right tool for validating demand and shipping internal or low-stakes surfaces, not for legal, marketing, or regulated copy. Recommended position: adopt it as our zero-cost baseline for locale prototyping, measure real usage per market, and only fund human translation or a paid translation platform where the data supports it.

For engineering — the practical case

• It is a dev-time Artisan command generating plain lang/*.php and *.json. No runtime coupling, no service provider in the request path, no schema changes. Reversible in one composer remove.
• It already handles the tedious correctness details we would otherwise get wrong: placeholder preservation and mismatch detection (prevents runtime str_replace-style failures), Laravel pluralization format retention, locale canonicalization (en-US → en_US), RTL/CJK/Cyrillic script handling, and framework translation bootstrapping.
• Safety is designed in, not bolted on: atomic temp-file-then-rename writes, path validation against the base directory, directory-traversal checks, and a --dry-run that writes nothing. Generated output lands in git and goes through normal code review.
• It is built for real CI ergonomics: --skip-existing for incremental runs, --refresh to re-translate after a terminology decision, configurable --chunk-size and --concurrency, retry/backoff for rate limits, and structured failure output (failed_translation_keys.json) so a partial run is diagnosable rather than silent.
• Known costs to plan for, not discover: PHP 8.3+ floor (required for Laravel 13 support), pcntl needed for the fork driver (Windows falls back to sync), tokenizer extension for parsing, and a documented gotcha where config/gemini.php must cast request_timeout to int or the command fails at startup. Free-tier Gemini quotas (~15 RPM / 1,000 daily) will throttle a large first run.
• Real risk: this is a single-maintainer package with low adoption and a history of breaking changes across major versions. Pin the version, review upgrades deliberately, and treat the lang/ output as the durable asset — the tool is disposable.