Laravel Langman Laravel Package

Technical Evaluation

What it is: themsaid/laravel-langman is a developer-facing Artisan toolkit for Laravel translation files. It scans application source (views/controllers) for __(), @lang, and trans() calls and reconciles them against resources/lang/* — surfacing missing keys, orphaned keys, and allowing append/find/show operations. It ships no runtime code path, no middleware, no service provider work at request time.

Architecture fit: Narrow but real. It addresses a genuine workflow gap in Laravel i18n: keys are plain PHP arrays with no schema, so drift between code and lang files is silent and only caught at runtime (missing key returns the raw key string). For a product with heavy Blade usage and multiple locales, the problem fits. The package fits only Laravel 5.x-era applications — the illuminate/support constraint and 2017 codebase will not resolve against modern Laravel without modification.

Integration feasibility: Medium-low.

• Dev-dependency only, so blast radius is contained to developer machines and CI.
• Composer resolution is the first blocker: last release 2017-08-06, PHP 7.0-era syntax, no PHP 8 compatibility, no Laravel 6+ support.
• The useful surface is small — roughly a handful of commands and a file-scanning service. A fork or in-house reimplementation is a few days of work, not a quarter.
• Dependents: 0 plus a stale release cadence is the decisive signal: this is an unmaintained reference implementation, not a dependency to adopt as-is.

Technical risk:

• Abandonment (High): no upstream fixes, no security response, no framework alignment. Effectively a code sample you inherit.
• Security (Low): no network calls, no runtime exposure, no auth surface. Primary exposure is untrusted input to file-writing commands on developer workstations.
• Correctness (Medium): key extraction is heuristic. Dynamically constructed keys (__('status.' . $code)), pluralization, and JSON translation files are the classic miss/false-positive cases.
• Data loss (Medium): any command that writes lang files can overwrite or reorder entries; diffs must be reviewable in PRs.

Key questions for the team:

1. What Laravel and PHP versions are in scope today, and what is the 12-month upgrade path?
2. Is the pain missing keys, orphaned keys, or translation vendor handoff? Each points to a different tool.
3. Are we prepared to own a fork (named maintainer, upgrade budget), or is a ~500-line internal Artisan command cheaper than patching?
4. Do we use JSON translation files or PHP array files only? JSON support materially changes the build-vs-fork calculus.
5. Can we gate this behind CI (fail build on missing keys) rather than relying on developer discipline?

Integration Approach

Stack fit: Only appropriate for a legacy Laravel 5.x service that is not on the immediate upgrade path. For any Laravel 8+ codebase, treat the repository as a design reference, not a package.

Migration path (recommended):

1. Do not install as a production dependency. Add as require-dev only if the version constraint resolves; otherwise vendor the source into a tools/ or internal package namespace.
2. Fork and re-baseline under an internal namespace: bump PHP constraint, adopt illuminate/contracts for the target Laravel major, replace any deprecated helpers, add a test suite around the scanner. Expect 2–4 engineer-days.
3. Alternatively reimplement the two commands that carry the value — sync (detect missing keys, append with empty values) and missing (report-only, CI mode) — using nikic/php-parser for Blade/PHP extraction. This is the cleaner long-term option if the fork drifts.

Compatibility: Expect breakage on PHP 8 (reserved words, typing, string offset behavior) and on Laravel's move to lang/ at the project root and JSON translation files. The scanner's regex assumptions about resources/lang layout will need updating. Blade compilation changes (component syntax, @lang directives) also affect extraction accuracy.

Sequencing:

1. Inventory — count lang keys, locales, and files; measure current drift by running a read-only scan. If drift is under ~1%, stop here; the ROI does not justify ownership.
2. Pilot — run report-only mode on one bounded module for two sprints; capture false positives/negatives against manual review.
3. Decide — fork vs. rebuild vs. buy (translation management platform). Weight by expected framework upgrades.
4. Automate — wire the report into CI as a non-blocking warning, then blocking after noise is under control.
5. Integrate with vendor handoff — export/import step so translators work from a stable key contract.

Alternatives to evaluate in the same pass: barryvdh/laravel-translation-manager (web UI, actively maintained), kkomelin/laravel-translatable-string-exporter (extraction-first, modern Laravel), or a commercial TMS if multiple locales and external translators are involved.

Operational Impact

Maintenance: The dominant cost. Zero upstream cadence means every Laravel/PHP upgrade becomes an internal ticket. Assign a named owner; without one, the tool silently rots and developers stop trusting its output — the worst outcome, because a stale scanner produces false confidence. Budget ~1–2 engineer-days per framework major.

Support: Community-only, and the community has moved on. No maintainer response path, no issue triage, no advisories. Internal documentation and a short runbook are mandatory if adopted.

Scaling: Negligible runtime concern — it runs at build/commit time and lang files are small. The real scaling limit is organizational: as locales multiply, key naming conventions and review ownership matter far more than the tool. Watch for git churn on large lang files and merge conflicts when multiple teams edit translations in parallel; splitting lang files per domain mitigates this.

Failure modes to instrument:

• False negatives — dynamic keys never detected; missing translations ship to users as raw keys. Mitigate with a runtime fallback handler that logs unresolved keys, so production catches what static scanning misses.
• False positives — dead keys retained forever; harmless but erodes trust in the report.
• Destructive writes — a write-mode command clobbering existing translations. Enforce report-only in CI; require human review on any file-mutating run.
• Blade drift — extraction misses new syntax after a Laravel upgrade, silently reducing coverage.
• Fork divergence — internal patches never upstreamed, creating a snowflake.

Ramp-up: Very low. Artisan commands, self-documenting, a developer is productive in under a day. The cost is not learning the tool; it is the ongoing ownership tax and the credibility risk if output is unreliable.

TPM recommendation: Do not adopt as a dependency. Use it to frame the problem, run a one-week read-only pilot to quantify translation drift, and fund either a hardened internal fork or a reimplementation of the two commands that matter — scoped to ~1 engineer-week, with CI enforcement as the actual deliverable. The value here is the pattern, not the package.