Laratext Laravel Package

Product Decisions This Supports

• Localization roadmap / market expansion sequencing. Adding a locale stops being an engineering project and becomes a translator-API line item plus a review pass. Run php artisan laratext:scan --dry to size the work in minutes — it reports new keys, drifted source texts, and orphan keys without writing anything or calling the translator, so you can cost a market before committing to it.
• Build vs. buy for translation workflow. Three realistic options: Laravel's native __() with JSON keys (fragile, unreadable), a SaaS TMS like Crowdin/Lokalise/Phrase (per-seat and per-word contracts, translator UI, but strings leave the repo), or this package (in-repo strings, CLI/CI-driven, usage-based API spend). The key+default-text pattern is the differentiator: keys stay stable while source text stays human-readable, which removes the classic "do we key on strings or on opaque IDs" compromise.
• Translation vendor strategy. Translators are swappable classes driven by default_translator / --translator=claude. You can benchmark OpenAI, Claude, and Google on the same corpus with --resync and pick per quality and cost, rather than negotiating a contract blind.
• Cost and quality governance. The tooling makes spend legible: --dry costs nothing, whereas dropping --write still spends tokens and discards results. That distinction belongs in a written runbook. Similarly, context (product description, formality, do-not-translate terms) and key names are sent to the model — so translation quality becomes a product-voice decision the PM actually owns, not a black box.
• Human review resourcing. The translator decides how many plural forms a locale gets; the README explicitly tells you to review languages with more forms than your source and then laratext:lock the key. That is a staffing decision (who reviews ru, pl, ar) that should be budgeted with the locale, not discovered after launch.
• Engineering standards / naming discipline. Keys travel to the translator as context, so nav.home meaningfully improves output while common.name doesn't. That justifies codifying a key-naming convention in the style guide — a cheap process decision with measurable quality upside.
• Localization debt as a tracked metric. --prune plus drift warnings turn orphan keys and stale translations into a health number you can put on a dashboard rather than an invisible liability.

When to Consider This Package

Consider adoption when:

• You're on Laravel 10–13 / PHP 8.2+ and localization is either already on the roadmap or an acknowledged pain point.
• The team is small enough that no one owns localization full-time, and the target set is modest (roughly 2–8 locales) where AI translation plus spot review is acceptable.
• You want translations to live in the repo, reviewed in the same PR flow as the code that uses them.
• Your UI strings are predominantly static literals in PHP/Blade — the scanner reads source statically, so text('key', 'Default') is the happy path.
• You prefer usage-based API spend to per-seat/per-word vendor contracts, and you want provider optionality.

Look elsewhere — or defer — when:

• You need certified or legally reviewed translation (medical, legal, financial disclosures), formal translation memory, glossary enforcement, or screenshot-context review for translators. That's TMS territory and this package won't substitute.
• Non-developers must edit copy and trigger translations. This is a developer tool behind an artisan command, not a CMS workflow.
• Your strings are heavily interpolated (text("activity.{$type}")). The scanner can't see them, so those keys are never created or translated and users see raw keys with no warning — a real correctness trap, not a nitpick.
• You operate dozens of locales or very large volumes where a TMS's negotiated per-word rates beat LLM-plus-review total cost.
• Policy forbids sending product copy to third-party AI providers. The translator layer is pluggable and Google Translate takes no prompt, but this needs a legal/security check before pilot, not after.
• Vendor-risk tolerance is low. The signals here are honest but thin: 77 stars, zero dependents, a single maintainer, MIT, and a short track record. Mitigate by keeping the integration surface small (config file + three translators) or by forking — but go in with eyes open.

One pre-flight decision if you adopt: set source_locale explicitly before the first --write. If APP_LOCALE differs from the language your source strings are written in, every key looks drifted and a single run retranslates the entire project — a silent, expensive mistake.

How to Pitch It (Stakeholders)

For executives: Today, shipping a new language is a stop-the-line engineering task plus a vendor negotiation. This package collapses it into a config file and one command: we write copy in our source language inline in the code, a scan finds new and changed strings, and an AI translation provider renders them into the locales we choose. Launching a market becomes an API bill and a review pass instead of a sprint. It's MIT-licensed, lives in our own repository so it goes through normal code review, and the translation provider is a swappable class — we can switch vendors or fall back to manual without rework. The honest caveat is maturity: it's a small, young project with one maintainer, so I'd propose a scoped pilot on a single locale with a quality gate before we commit further.

For engineering: One composer require, publish config/texts.php, and replace __() call sites with text('key', 'Default text') / @text('key', 'Default text'). It preserves Laravel semantics you already rely on — :placeholder replacement and the | plural selector, including explicit ranges like [1,19] — and uses Laravel's own plural chooser, so per-language rules apply. Lifecycle is CLI-driven: --dry previews at zero cost and zero writes, --write applies, and --only-missing, --resync, --prune, --lang, --translator, and --diff cover the rest. Two constraints to design around: the scanner is static, so keys must be literals (refactor interpolated keys into a match); and the AI decides plural form counts, so review and laratext:lock the keys that matter. It's tested across every PHP 8.2–8.5 × Laravel 10–13 combination on each push and weekly against new releases.

Proposed decision ask: approve a bounded pilot — one locale, one translator, --dry to size the corpus, a named native-speaker reviewer for plural-heavy languages, and a go/no-go on sampled translation quality before any broader rollout.