Laravel Localization Helpers Laravel Package

Getting Started

• Install with a pinned version. The package's last release is from Feb 2015 (Laravel 4/5 era), so don't assume composer require potsky/laravel-localization-helpers resolves cleanly against a modern Laravel. Pin the version, install on a branch, and confirm your PHP constraint accepts it.
• Register the service provider manually. This predates Laravel 5.5 auto-discovery, so add it to config/app.php:

'providers' => [
    Potsky\LocalizationHelpers\LocalizationHelpersServiceProvider::class,
],

• Where to look first, in order:
  1. The GitHub README — it's the only authoritative documentation for this package.
  2. php artisan list (or php artisan list localization) to see the actual command names and flags shipped in the version you installed.
  3. Any config published via php artisan vendor:publish — scan paths and file extensions usually live there.
• First use case: run the "find missing" command on a throwaway branch against your existing Blade views, then inspect the lang/ diff with git diff. That single run tells you more about the parser's behavior on your codebase than any docs will: which @lang/trans() calls it catches, how it nests keys, and what it writes into files.

Implementation Patterns

• Baseline sync during development. After adding new @lang() / trans() calls, run the missing-key scan, review the diff, and commit it alongside the feature. This keeps lang files from drifting as features land.
• CI guard for untranslated strings. Run the missing-key command in CI and fail the build if it produces a diff (git diff --exit-code after running, or a dry-run flag if your version supports one). This makes "you forgot the translation" a PR-time failure rather than a production bug.
• Obsolete cleanup as its own PR. Run obsolete detection on a dedicated branch, review key-by-key, and delete in a commit that does nothing else. Mixing cleanup with feature work makes regressions impossible to bisect.
• Scope the scan tightly. Point it at resources/views, app/Http, and your own packages. Exclude vendor/, compiled Blade caches, and generated files, or you'll get noise plus slow runs.
• Use one locale as the source of truth. Let the tool populate your primary locale (e.g. en), then propagate keys to other locales with your own script. Auto-generating into every locale produces forests of placeholder translations that hide real gaps.
• Handle dynamic keys deliberately. For trans('validation.' . $rule), enum-driven keys, or translations consumed by JavaScript, keep a manual allow-list or a wrapper call the parser can see. Otherwise they get flagged as obsolete and deleted.

Gotchas and Tips

• Compatibility is the main risk. A 2015 codebase likely has tight PHP constraints, no auto-discovery, and assumptions about container/console APIs that have since moved. Test on a branch, and be prepared to fork and patch rather than rely on upstream.
• GPL-3.0 is copyleft. Bundling this into a closed-source application or SaaS has real licensing implications. Get sign-off from whoever owns that decision, or skip the package in proprietary products.
• The commands rewrite files in place. Always start from a clean working tree, never run them in production, and always review the diff. A bad scan path or parser bug can shred your lang files.
• Regex-based extraction has hard limits. Expect false negatives (concatenated/variable keys, __() with dynamic arguments, JS-side translations) and false positives (keys only referenced from config or tests).
• "Obsolete" doesn't mean unused. Pluralization suffixes (_one, _many), validation attribute names, and package-published vendor lang files are easy to misclassify. Review every deletion.
• Debugging empty results: check the configured scan directories and extensions first, run with verbose output if the command has a -v path, and check storage/logs/laravel.log for parse errors. If it finds nothing at all, it's almost always misconfiguration, not a broken parser.
• Extension points: the commands are ordinary Artisan command classes, so you can subclass them, override the parser, or register your own variant in app/Console/Kernel.php — useful for adding a dry-run mode, custom key formats, or JSON output for CI.
• Consider the modern alternative. For new projects, laravel-lang/lang plus a small custom extractor command (e.g. built on nikic/php-parser) is usually less risky than reviving a decade-old package — you get the same "find missing keys" workflow without the compatibility and licensing baggage.