- How do I install filament-localization in a Laravel app using Filament 5?
- Install it with Composer using composer require --dev mominalzaraa/filament-localization, pinning an exact version so a minor release cannot change how your resources are rewritten. Then publish the config with php artisan vendor:publish --tag="filament-localization-config". The package exposes two Artisan commands, filament:localize and filament:translate-with-deepl, both of which accept flags such as --panel, --locale, --dry-run, --force, and --no-git. A pilot run against a low-risk internal panel typically takes under a day for an experienced Laravel developer.
- Which PHP, Laravel, Filament, and Livewire versions does filament-localization support?
- The current line requires PHP 8.3 through 8.5, Laravel 12 or 13, Filament 5, and Livewire 4. Older PHP versions and earlier Filament majors are explicitly deprecated. If your application is still on Filament 4, you would need the deprecated v1.x branch of the package, which is effectively a different and less capable tool. Treat any Filament major or minor upgrade as a localization-affecting change and re-verify generated output after bumping.
- How does filament-localization generate translation files for Filament resources?
- It is a build-time codemod rather than a runtime library: it scans your Filament resources, pages, and relation managers, replaces hardcoded labels with __() keys, and writes structured files into your lang directory. Because it edits application PHP source, the critical question is whether label extraction is AST-based via something like nikic/php-parser or regex-based text substitution. Regex substitution can silently corrupt files containing chained modifiers, closures, heredocs, or nested builders. Always run with --dry-run and review the diff before applying it.
- How do I run filament:localize on just one panel with a dry run first?
- Run php artisan filament:localize --panel=your-panel --dry-run to preview the proposed changes without touching files. Choose the lowest-value panel available, such as an internal admin or back-office tool, and never start with a customer-facing panel. Review the diff manually, then apply it and gate the result with php -l, Pint, and PHPStan or Larastan before committing anything. This lint-and-static-analysis step is non-negotiable for a tool that rewrites your source files.
- Should filament-localization be a dev dependency or a production dependency?
- It belongs in require-dev, because nothing about resource scanning or translation file generation needs to run in production. Exclude the service provider from production autoload if you can, but verify first, since the package publishes config and may auto-register a provider at runtime. Restricting it to local and CI environments keeps the blast radius of a bad run limited to a revertible diff. Confirm with the maintainer whether the provider registers anything that would affect a production boot.
- Is filament:localize idempotent, and what happens if I run it twice?
- Idempotency is not something you should assume here; it is one of the key questions to put to the maintainer before adopting the package. A well-built codemod should detect existing __() calls and leave already-localized files untouched, but a naive implementation may double-wrap keys or regenerate conflicting entries. Run it a second time on a branch after your first pass and inspect the diff, which should be empty. If it is not, treat every run as a one-shot migration rather than a repeatable command.
- How are the generated translation keys structured, and how are duplicate resource names handled across panels?
- The package produces structured, organized keys rather than flat lists, typically grouped by resource and component so the lang files stay readable and maintainable. The riskier edge case is key collisions: if the same resource class name exists in two separate panels, panel-based key structure must disambiguate them. Ask the maintainer how collisions are resolved before you localize a multi-panel application. Also treat the generated lang files as a starting point, not final copy, and have a human review the source-of-truth strings.
- Does filament-localization translate strings automatically with DeepL, and is that safe?
- The filament:translate-with-deepl command sends your UI strings to DeepL, which introduces both a paid third-party dependency and outbound data egress. That is usually fine for generic labels like Name or Created At, but it may be a compliance problem for strings containing internal terminology or customer data. Generate the English keys first with filament:localize, review them, and only then decide whether to run the DeepL step. Keep the machine-translated output under human review before it ships.
- What does the --force flag do, and will automatic git commits break my review workflow?
- --force is destructive by design and can overwrite translations a human has already curated, so avoid it on any locale that has been hand-edited. The package can also create git commits automatically, which will collide with branch protection rules, signed-commit policies, and PR-based review. Start with git.enabled set to false and --no-git so all changes land as a normal diff you can inspect. Also confirm your rollback story beyond reverting an auto-commit, especially when --no-git was used.
- Is filament-localization safe to adopt given its low download count and single maintainer?
- The technical risk here is high and concentrated: source-rewriting correctness, hard version coupling to Filament 5 and Livewire 4, and a supply-chain and bus-factor concern from a small single-maintainer package with little downstream production evidence. You would likely be the first reference implementation, so budget time for a pilot on an internal panel with a pinned exact version. Mitigate with CODEOWNERS or Renovate rules so Filament bumps trigger re-verification, and keep fixture or golden-file tests around your resources. If that overhead is unacceptable, hand-managed translation keys remain the low-risk alternative.