Localization Helpers Laravel Package

Getting Started

Install as a dev dependency so translation tooling never reaches production:

composer require --dev torann/localization-helpers

Laravel package discovery registers the service provider automatically. Publish the config if you need to adjust scan paths, base locale, or file conventions:

php artisan vendor:publish --tag=localization-helpers

Before adopting any workflow, verify the installed version's actual command surface — with a package this small, the commands are the product:

php artisan list localization
php artisan help localization:<command>

First use case: pick a source-of-truth locale (usually en), scan your views and application code for translation keys, generate or update the base-locale files, review the diff, and commit before translating. That loop — scan → generate → translate → commit — is the core day-to-day value.

Where to look first:

1. config/localization-helpers.php after publishing — scan paths, locale, file-type settings.
2. Command signatures via php artisan help — they define the workflow more accurately than the README.
3. src/Console/ in the package source — with low adoption, the code is the documentation.

Implementation Patterns

CI gate for key drift. Add a job that detects new translation keys missing from the base locale. Prefer a check-only/dry-run mode if available; otherwise run the command and fail on any diff:

- run: php artisan localization:missing --dry-run

If no dry-run flag exists:

php artisan localization:missing
git diff --exit-code lang/

This prevents a developer from adding __('checkout.new_field') in Blade and nobody noticing the key is absent until a user sees the raw key in production.

Feature-branch translation sync. On branches that introduce strings: scan, commit base-locale keys, send files to translators, merge translations back. Keep generated key changes in their own commit so review diffs stay readable and machine-generated churn does not hide logic changes.

Multi-locale fan-out. Treat the base locale as canonical, then sync the key set into every other locale with placeholder or English values. This gives translators fully-keyed files and makes "missing key" vs. "untranslated" distinguishable in review. Never let a partial locale file ship — an empty value is better than an absent key because it fails visibly rather than falling back silently.

Read-only before write. If the package offers export/diff (or you can run generation against a scratch directory), do that first and diff against committed lang/. Establish fidelity on one real locale — including a non-Latin script and a pluralized string — before you trust any file-mutating command. Round-trip losslessness is the only acceptance test that matters.

php artisan localization:export > /tmp/keys.json
diff <(jq -S . /tmp/keys.json) <(jq -S . lang/en.json)

Sorting and cleanup as a pre-commit hook. Normalizing key order and whitespace makes every future translation diff reviewable. Wire it into a Husky/pre-commit step so it runs automatically and never gets forgotten:

php artisan localization:sort && git add lang/

Runtime helpers (if the installed version ships them). The package description advertises locale detection, switching, and locale-prefixed routes. If your installed manifest confirms this, use them for:

• A SetLocale middleware that resolves from session or Accept-Language, validates against a configured allowlist, and calls App::setLocale().
• Route generation: route('home', ['locale' => app()->getLocale()]) becomes uniform rather than hand-built per view. Wrap it once in a Blade helper or a LocalizedRoute facade so the dependency is swappable.
• Locale switcher UI that reads available locales from config rather than hardcoding.

Adopt helpers only if they replace code you would otherwise write — otherwise the dependency is a cost without a benefit.

Integration points to standardize. Controllers and Blade views consume the same helper surface. If you mix __() calls with package helpers, you lose the "one way to do it" advantage. Pick one style: package helpers for locale state, native __() for string lookup.

Gotchas and Tips

Resolve the identity question first. The description says runtime helpers (middleware, routes); prior assessments say Artisan commands. These are completely different packages architecturally. Read the installed composer.json and run php artisan list — do not trust the README. If middleware is present, it goes into the request lifecycle and needs a middleware-ordering review (relative to StartSession, Authenticate, and cache middleware); if not, it stays in require-dev.

Any command that rewrites lang/ is destructive. There is likely no test coverage on translation files, so a partial write silently drops translations. Never let a mutating command touch a protected branch. Always: run read-only first, review the diff, commit generated changes separately, keep git as the rollback mechanism.

Silent skipping is a defect. Dynamic keys (__("messages.{$key}")), JSON translations, pluralization pipes (apple|apples), :placeholder handling, and vendor-namespaced keys are commonly out of scope for tools of this shape. Test each against your codebase. If a key shape is silently ignored, that is a bug against your coverage, not a convenience — decide whether to accept the gap explicitly.

Lang path relocation. Laravel 9+ moved resources/lang to lang/. Confirm the package honors your actual lang path, especially if you have both (post-upgrade, unmerged) or use a custom translation_loader. A command pointed at the wrong root will report everything as missing.

Pin the exact version. At 8 stars, 0 dependents, and a single maintainer, do not float on ^. Something like "torann/localization-helpers": "2.1.1" — and if the tool becomes load-bearing, budget a fork as a contingency (small surface means days, not weeks).

Test against the oldest Laravel in your fleet. The release note only says "Laravel 12 support." Confirm compatibility with the actual lowest version you operate, and add the check to your CI matrix.

Excel is the main corruption vector. If translators use spreadsheets, document encoding rules (UTF-8, no BOM), no column reordering, no auto-formatting of key columns, and no formula injection into keys. Validate the returned file with a scan before merging — an Excel-mangled header will look like "all keys renamed."

Debugging commands. Use -vvv for verbose output, check php artisan list to confirm the package registered (a missing command usually means auto-discovery failed or the extra.laravel.providers entry is absent), and verify the config is published if behavior seems to ignore settings. With no community docs, src/Console/*.php and src/Providers/*.php are the real references.

Extension points, if you need them. Small packages with low adoption are usually trivially subclassable — bind a custom implementation over the package's service in a service provider, or override the command registration in AppServiceProvider::boot(). Prefer this to forking; keeps you updatable if the maintainer surprises everyone and ships.

Own the runbook. One page covering who may run mutating commands, who reviews the diff, how to revert, and the pre-agreed abandon criterion (e.g., "if the package breaks on a Laravel upgrade twice in a year, we fork"). At this adoption level, governance matters more than the tooling.