Laravel Langman Laravel Package

Getting Started

Install and publish

composer require themsaid/laravel-langman
php artisan vendor:publish --provider="Themsaid\Langman\LangmanServiceProvider"

On Laravel < 5.5 you must also register Themsaid\Langman\LangmanServiceProvider::class in config/app.php. On 5.5+ auto-discovery handles it.

Look here first

1. config/langman.php — the only config surface (path settings for the CSV sync flow). Read it before anything else; it tells you where Langman expects to read/write.
2. resources/lang/ — Langman scans every locale directory and every PHP file returning an array, plus root-level JSON files (managed as a special _json pseudo-file).
3. The shell itself: run php artisan langman and it drops you into an interactive REPL. Type list to see the files it found and confirm your layout is being picked up correctly before doing anything destructive.

First use case

Don't start with add. Start with:

php artisan langman
> missing

This shows every key present in your fallback/default locale but absent from other locales — usually the highest-value thing you can do with the package on day one, and it's read-only. Once you trust the output, move on to add/edit to fix what it reports.

Implementation Patterns

Treat the default locale as the source of truth. Langman's missing report is one-directional: it walks keys from the fallback locale outward. Keep en (or whatever your fallback is) complete and let Langman drive the other locales from it. If you let translations drift in both directions, missing will quietly lie to you.

Add keys through the shell, not by hand. When a feature needs a new string, add it with add so the key lands in every locale file at once, with a placeholder value in the untranslated ones. That keeps the "key exists everywhere, value is empty" invariant that makes missing trustworthy and lets __('...') fall back cleanly instead of throwing.

Use find as your grep replacement. Before you add pages.home.title, run find home / find title — existing keys are frequently 80% of what you need, and near-duplicate keys are the main way translation files rot.

Batch your edit sessions. The shell is interactive and one-key-at-a-time; it's a poor fit for "translate 200 strings." Use it for corrections and consistency passes (renaming a product name, changing tone), and use the CSV flow for bulk work.

CSV round-trip for translators. The package ships a langman:sync artisan command that exports your keys into a CSV (one column per locale, key in the first column) and imports it back. The workflow:

1. php artisan langman:sync to export.
2. Hand the CSV to a translator / send it to a translation vendor.
3. Import the returned file.
4. git diff resources/lang and review before committing.

This is the realistic way non-developers contribute. Check config/langman.php for the exact path key in your installed version and commit the CSV if you want a durable audit trail.

Team protocol: one runner, clean tree. Langman writes files directly. Two developers running it on overlapping branches produces painful merge conflicts in PHP arrays. Convention: whoever owns the feature adds the keys, commits them, and everyone else rebases.

Scriptable checks belong in your own command. The REPL isn't CI-friendly (no non-interactive flags worth relying on). If you want a build-time guard, wrap the package's Themsaid\Langman\Manager class in a small custom artisan command that diffs key sets across locales and exits non-zero. That's the intended extension point — Manager is a plain service class, not a shell-coupled one.

Gotchas and Tips

Maintenance risk is the headline. Last release was August 2017 — a Laravel 5.x-era package. On Laravel 8/9/10+ with PHP 8 you should expect trouble: Symfony Console API changes, deprecation noise, and provider/config loading that may simply not bind. Prototype on a throwaway branch, not on main. If it breaks, the realistic options are a community fork, a hand-rolled Manager-style command, or laravel-lang / spatie/laravel-translation-loader for the runtime side. Langman is a dev-time convenience, not load-bearing infrastructure — treat it as replaceable.

It rewrites your files. Langman re-serialises the PHP arrays it touches. Comments vanish, key ordering normalises, and any hand-formatting or alignment is lost. Always run it on a clean working tree and review git diff file by file. Never run it as part of a commit you haven't inspected.

Sorting is a side effect and a feature. The shell can sort keys within a file. Good for consistency; bad if you rely on key order for readability grouping. Decide as a team whether sorted files are the norm, and if so, sort once and commit as a dedicated "chore: sort lang files" commit so the noise isn't mixed into feature diffs.

Dotted keys become nested arrays. add pages.home.title creates ['pages' => ['home' => ['title' => ...]]]. If pages.home already exists as a flat string, you get a conflict or a surprising overwrite. Run find first.

JSON files are second-class. Root-level JSON translations (used by __('Some literal sentence')) are grouped under a _json pseudo-file. Mixing JSON keys and PHP-file keys for the same concept is legal at runtime but confusing in Langman's listing — pick one convention per domain and stick to it.

Vendor and package translations are invisible. Langman only scans your resources/lang. Overriding vendor/package/... keys still requires manual file creation; the shell won't tell you what's missing there.

Missing is one-way. As noted above: a key in fr that's absent from en will never be reported. If you need bidirectional integrity, write it yourself against Manager.

CSV import is picky. Locale column headers must exactly match your locale directory names (en, en_GB, pt_BR — casing and separators included). Empty cells are treated as untranslated, so an over-zealous "delete empty rows" pass in Excel can silently drop keys. Watch for BOM-prefixed files from Excel exports; they break the header row. If your values contain commas or quotes, verify the escaping survived the round-trip before importing.

Duplicate keys across files are fine at runtime, invisible in the shell. auth.failed in auth.php and failed in messages.php are different keys, but a search for failed shows both with no indication of which one your view actually resolves. Be disciplined about one file per domain.