Filament Localization Laravel Package

Technical Evaluation

What it is (architecture fit). This is a dev-time codegen and i18n extraction tool, not a runtime library. It scans Filament resource/page/relation-manager classes, strips hardcoded labels, and rewrites them to __('filament/<panel>/<resource>.<key>') calls backed by generated lang/<locale>/... files. Critically, the artifacts it produces are plain Laravel translation files resolved by the stock FileLoader — nothing at runtime depends on the package. That makes the integration reversible: you can remove the Composer dependency and keep the translations. This is the single most important de-risking property and should anchor the business case.

The fit is narrow but real: teams building Filament v5 panels on Laravel 12/13 with hardcoded English labels and a genuine multi-locale requirement. Teams already using __() keys, or single-locale teams, get near-zero value.

Integration feasibility. Install is composer require plus a config publish; operation is two Artisan commands (filament:localize, filament:translate-with-deepl). There is no service provider surface to reason about, no middleware, no migration. Language switching — the part users actually see — is out of scope and delegated to a separate third-party plugin (craft-forge/filament-language-switcher), which means two vendors to vet, not one.

Technical risk. Ranked:

1. In-place source mutation. The tool edits your application PHP files (resources, pages, relation managers). This is the highest-risk category of tooling short of schema migration. Mitigations exist (dry-run, backups, git commits) but they are opt-in conveniences, not guarantees; the review gate is on you.
2. Bleeding-edge version matrix. PHP 8.3–8.5, Laravel 12|13, Filament 5, Livewire 4, Tailwind 4 — with Filament v4 explicitly deprecated to a v1.x branch. This narrows the addressable base to teams already on the newest stack and means the package's compatibility surface moves faster than most orgs upgrade.
3. Ecosystem immaturity / bus factor. 11 stars, 0 dependents, single maintainer, and an already-shipped breaking major (v1 → v2 dropping Filament 4). There is no commercial backing and no support SLA. The repo's own tooling (an agent-oriented context graph under agents//skills/) suggests the author optimizes for AI-assisted contribution — good for throughput, but not a substitute for external validation or human review depth.
4. External translation dependency. DeepL introduces per-character cost, quota/rate limits, a 60s timeout, and data egress of UI strings (field names, labels, notification copy) to a third party. Free-tier vs. Pro data-retention terms differ and matter for regulated environments.
5. Static-analysis fragility. Filament's API is closure- and variable-heavy (->label(fn () => ...), computed labels, loops over field arrays). Any textual/AST pass will hit cases it cannot safely rewrite; partial rewrites are the failure mode to design around, not total failure.
6. Marketing overreach. "First and only" claims are verifiably false (Filament ships its own translations; several community helpers exist). Immature vendor comms correlate with immature release discipline — weight the changelog, not the README.

Key questions to put to the maintainer before committing:

• Is the rewrite idempotent? What happens on a second run over already-localized files?
• Is there a prune/sync command to remove orphaned keys after class renames or resource deletion?
• Does it only rewrite literal string arguments, or does it attempt closures/variables? What does it do when it can't decide?
• How are key collisions handled when two resources share a class basename in different namespaces?
• Is the lang/ output path configurable, and does it respect Laravel 12's directory conventions?
• Does the auto-commit stage only generated files, or anything dirty in the working tree?
• Test coverage and CI matrix — which of Laravel 12/13 × PHP 8.3–8.5 are actually exercised?
• Stewardship: funding, roadmap, willingness to accept PRs for a supported LTS-style branch?

Integration Approach

Stack fit gate. Adopt only if the application is on Laravel 12+, Filament 5, Livewire 4, PHP 8.3+. On Filament 4, the answer is the v1.x line — treat that as a separate evaluation, since that branch is effectively frozen. On Filament 3 or Laravel ≤11, this is a non-starter; do not plan around it.

Migration path. The value is inversely proportional to how much i18n you already have:

• Greenfield / pre-localization panel with hardcoded labels — best case. Run it early, before the resource surface grows, so key naming stabilizes while the codebase is small.
• Brownfield with hardcoded labels and no translation files — viable, but scope to one panel first. Diff volume on a large panel will be enormous and unreviewable in one PR.
• Already using __() keys — skip. The DeepL command is the only residual value, and that is a commodity you can script yourself.

Compatibility considerations.

• Pin the dependency exactly (e.g. 2.1.*), not ^2. Release cadence and an existing breaking major argue against floating constraints in a production composer.json.
• Disable the built-in git integration in any shared/CI environment (--no-git) and own the commit yourself. An unattended auto-commit inside a pipeline will interleave with developer commits and make history archaeology painful.
• Treat the language-switcher plugin as a second, independent procurement decision with its own vetting; the localization package does not deliver a working switcher.
• Confirm interaction with Filament's own vendor translations (UI chrome) and RTL locales — those are Filament's responsibility, not this package's, and the boundary should be explicit in your acceptance criteria.

Sequencing (with exit criteria).

1. Spike (1–2 days, throwaway branch). Install, publish config, run filament:localize --dry-run against one panel. Exit: diff is inspectable and no file is corrupted; you know the exact rewrite shapes it produces.
2. Pilot (one sprint). One non-critical panel, dry-run → real run → human diff review → php -l on every generated lang file → smoke test the panel in both locales. Exit: panel renders correctly in target locale, no parse errors, key naming convention accepted.
3. Rollout. Remaining panels, one PR per panel, using --panel= scoping. Exit: all panels localized, orphan-key check run.
4. Machine translation (separate phase). DeepL only after human-reviewed key structure exists. Run with --dry-run first, then batch by panel; require native-speaker QA on the output. Exit: translation quality signed off per locale; skip-terms list extended with your domain acronyms.
5. Switcher + locale routing. Only after content is correct. Exit: locale persistence, URL or session strategy, fallback behavior verified.

Do not compress phases 2–4. The cost of a bad rewrite is a broken admin panel; the cost of bad machine translation is a customer-visible credibility problem.

Operational Impact

Maintenance and ownership. Bus factor is 1. Budget for an internal owner (a senior Laravel/Filament dev at ~10–15% time) who can read the package source, not just run the commands — because when a rewrite goes wrong, GitHub issues will not resolve it in your SLA window. Track the upstream changelog manually; assume no deprecation notice before a breaking change. Maintain a fork-ready posture: the codebase is small and MIT-licensed, so forking is a credible contingency, and that is the main reason this risk is containable.

Support model. Community-only: GitHub issues, no SLA, no paid tier. Escalation path is "fix it yourself or fork." That is acceptable for a dev-time tool with reversible output; it would not be acceptable if the package sat in the runtime path.

Scaling. The localize command is O(resources) and runs in seconds-to-minutes; not a concern. The real scaling curve is DeepL: cost is per character, batched at 50 strings, with a 60s timeout per request. A large panel with hundreds of fields across many locales multiplies quickly — model the character count before enabling the translate command org-wide, and expect rate limiting or partial completion on big batches. Mitigate by scoping to --panel= and re-running rather than doing a single global pass; partial runs are recoverable because smart detection only touches missing/identical keys.

Failure modes and controls.

Ramp-up. Developer-facing ramp is genuinely low — two commands and a config file, well documented in the README. Owner-facing ramp is moderate: understanding Filament internals, the rewrite semantics, git hygiene around generated diffs, and translation QA workflow. Call it 1–2 days to a credible spike and roughly one sprint to a reviewed pilot panel including translation sign-off.

Recommendation shape. Treat this as a bounded, reversible developer-productivity bet, not a platform commitment: pilot it on one panel, keep the auto-commit off, budget for human translation review, and retain the option to fork or drop the package while keeping the generated lang files. The exit cost is near zero, which is what makes the immaturity tolerable — but the version-matrix narrowness means the decision should be revisited if the team is not already on Filament 5.