Laravel Translation Handler Laravel Package

Product Decisions This Supports

• Localization architecture: single source of truth vs. format sprawl. Teams routinely end up with translations split across PHP arrays, JSON, and a database, typically because an admin UI was bolted on later. This package makes PHP/JSON/CSV/DB interchangeable with one import/export/sync call, so the decision "where do translations live?" becomes reversible. That is a roadmap de-risker: you can ship on file-based translations now and migrate to DB-backed translations later without a rewrite.
• Build vs. buy on internal translation tooling. The alternative is a homegrown Artisan command set plus a __() key scanner — realistically 1–3 weeks of engineering, then perpetual maintenance as formats and frameworks drift. At MIT license and zero integration cost beyond composer require + config publish, this is a clear "buy" (adopt) unless you already own a TMS integration.
• Whether to invest in an admin translation UI. DB format + set/listTranslations/deleteGroup + the swappable dbHandlerClass gives you a programmatic backend for an internal editor without designing a storage layer. Useful for deciding if a "translations admin page" is a small internal tool (build on this) or a product surface (buy a TMS).
• Release-readiness gating. check-translations-tool / translation-handler:check reports keys referenced in code but undefined, per side and locale, with orphans: true for defined-but-unused keys. That converts "is localization done?" from a QA opinion into a pass/fail gate you can put in CI before a launch or a new-market release. Directly supports go/no-go decisions for localization launches.
• New-market / new-locale scoping. listGroups, whereGroupIn, and per-locale CSV export let you estimate scope ("how many keys exist in auth, validation, messages?") and hand translators exactly one locale's strings as CSV — a concrete input to costing a market expansion.
• AI-assisted localization as a roadmap option, not a bet. The Laravel Boost v2 MCP integration auto-registers tools that let an agent read config, write a whole translation group across all locales in one call, sync DB → files, and run the missing-key audit. The PM-relevant point: the "golden rule" (edit in db, sync to files once at the end) means agent-driven edits don't cause N full-file rewrites. This is a credible, low-commitment pilot for AI in the dev workflow — you can trial it on one feature's strings and measure time-to-localized without a platform purchase.
• Deciding where translation drift gets caught. Frontend and backend are scanned separately (check.backend = app, resources/views, routes, database + .php; check.frontend = resources/js + .ts/.tsx/.js/.jsx). If your product has both, that per-side breakdown tells you which side is the actual source of missing-copy bugs — a fact you can act on.
• Extensibility as a hedge. Every handler class and the checker are swappable via config or setOption(). That means "adopt now" doesn't commit you to this package's file layout — custom FileHandlerInterface / DatabaseHandlerInterface implementations and a TranslationChecker subclass with custom patternsFor() regexes cover non-standard key conventions.

When to Consider This Package

Adopt-trial when:

• You are on Laravel with translations in PHP arrays and/or JSON and want bidirectional movement between them, or a low-friction path to a DB table.
• You want a missing-key audit in CI — this is the strongest standalone reason, independent of the format conversion.
• You need one-locale CSV for an external translator and want to avoid hand-exporting.
• You already run laravel/boost v2 and want to pilot agent-driven translation edits with a sane write pattern (DB-first, sync at the end).
• Your translation volume is moderate (hundreds to low thousands of keys) and you have no TMS.

Look elsewhere when:

• Maturity is a hard requirement. 0 stars, 0 dependents, and no ecosystem signal. The release metadata lists 2026-10-21, which is not a date you can verify against a shipped artifact — treat version history as unconfirmed and pin an exact version in composer.json with a lock file. Do a code read before merging; there is no community backstop.
• You need a translation management system. No translator UI, no review/approval workflow, no translation memory, no vendor integrations, no pluralization-rule management, no per-string context/screenshots. If your process involves humans who aren't engineers, this is a component, not a solution — pair it with Crowdin/Phrase/Lokalise or spatie/laravel-translation-loader.
• You need runtime-editable translations in production with caching semantics, per-tenant overrides, or fallback chains. DB format exists but this is not positioned as a production runtime translation layer.
• You need pluralization/ICU message handling. Nothing here manages plural forms — it moves strings.
• Heavy concurrency or large key counts. File handlers rewrite the whole file per write; even in DB mode you are trusting a small package with your write path. For very large corpora, evaluate throughput and locking before committing.
• You can't accept an unreviewed dependency on your critical path. Localization is core to a multilingual product; a single-maintainer package with no dependents is a bus-factor and abandonment risk.

Mitigations if you proceed: MIT + swappable handlers means exit cost is low — worst case you keep the data, drop the package. Pin the version, wrap calls behind your own service class, and add the check command to CI so a future removal is caught by failing builds.

How to Pitch It (Stakeholders)

For executives (one paragraph): Localization is currently a manual, error-prone process: strings live in more than one place, nobody can say with certainty whether every string on a page is translated, and preparing files for translators is handwork. This package is an MIT-licensed Laravel library that makes translation storage formats interchangeable, gives us an automated audit of missing translations we can run before every release, and exports a single language as a spreadsheet for translators. It also plugs into our AI coding tooling so agents can localize a whole feature in one pass. The cost is a Composer dependency and a config file; the risk is maturity — it has no adoption yet, so we would use it behind our own wrapper, pin the version, and treat it as reversible. Concrete asks: approve a one-sprint trial scoped to one feature and one pre-release gate, with a go/no-go on measured missing-key count before and after.

For engineering (one paragraph): It's a facade plus four storage handlers — php_file, json_file, csv_file, db — with import/export/sync/get/set/find/listTranslations/deleteKey/deleteGroup/sortKeys and equivalent Artisan commands. TranslationCollection gives chainable filters (whereLocale, whereGroup, whereValueContains) and merge semantics (addTranslations skips existing key+locale, replaceTranslations overwrites). The real win is check, which regex-scans configured paths and extensions per side (backend PHP, frontend TS/JS) for __()/trans() usage and reports referenced-but-undefined keys plus optional orphans; scan paths, extensions, and the extraction regexes themselves are configurable or overridable via a TranslationChecker subclass. Everything — all four handlers and the checker — is swappable via config or setOption(), so we can back it with our own table or key convention. Important operational detail: file formats rewrite the entire file per write, so batch multi-key edits into db and sync to files once. Boost v2 auto-registers MCP tools with no config. Caveats to weigh: zero stars, zero dependents, single maintainer, unconfirmed release history — pin the version and wrap the facade so removal is a one-file change.