Laravel Translation Sync Laravel Package

Getting Started

First, install via Composer and check what the package auto-registers:

composer require mohammadtrabelsi/laravel-translations-sync

Since the package changed hands from rizqengine to mohammadtrabelsi in 1.0.0, confirm the actual vendor/package name resolves on Packagist before committing. If you were previously on the RizqEngine release line, treat the rename as a potential breaking change — update composer.json, any service providers referenced in config/app.php (for older non-auto-discovered setups), and any published config that pins class namespaces.

Where to look first:

1. vendor/mohammadtrabelsi/laravel-translations-sync/README.md — the command signature and config options are the whole surface area of a sync package.
2. The published config (php artisan vendor:publish --tag=...) — this tells you which locale paths are scanned, which source locale is authoritative, and whether new keys are auto-created or only reported.
3. php artisan list | grep -i translat — sync packages typically expose one or two Artisan commands.

First use case: run the package's reporting/dry-run mode (usually a --dry-run or --check flag) against a project that has drifted. You're looking for missing keys in secondary locales and orphaned keys that no longer exist in the source. Only after you understand the diff output should you run it in write mode.

Implementation Patterns

Diff-then-apply in CI. The highest-value integration is a CI step that runs the sync in check mode and fails the build on drift. This keeps translation files honest without humans running the command ad hoc. Pair it with a separate scheduled job (or a manual workflow) that actually writes the changes and opens a PR.

Source-of-truth discipline. Pick one locale (almost always en) as canonical and make sure the package config reflects that. Everything else is generated/diffed against it. Mixing "sometimes edit fr directly, sometimes sync" is how you get orphaned keys that never get cleaned up.

Post-merge regeneration. If keys are added in feature branches, run the sync after merge into your main branch — not in the feature branch itself. This avoids three branches each generating conflicting placeholder entries for the same key.

Placeholder preservation. For any new key the package auto-creates, check what placeholder value it writes (empty string, the key itself, or the source-locale text). Whichever it is, decide the policy and lean on the package config if it's configurable. A key that silently falls back to English is a bug that ships; a key that's visibly the raw key name gets caught in review.

Pair with a lint step. Sync packages detect missing keys; they don't usually detect unused keys reliably, nor do they validate placeholder parity (:name present in all locales). A small custom test iterating __() over each key catches placeholder mismatches the sync won't.

Local developer loop. Wire the command into a Composer script (composer translations) so it's discoverable. Developers won't remember the vendor-namespaced Artisan command, but they'll remember composer translations.

Gotchas and Tips

The 1.0.0 change is a maintainer transfer, not a feature release. Nothing in the notes suggests new functionality or a deprecation — but an ownership move is a real supply-chain consideration. Review the new maintainer's repository, confirm the Packagist entry points at Mohammadtrabelsi/laravel-translations-sync, and check whether the old RizqEngine package is abandoned or merely superseded. If you have a lockfile pinned to the old vendor name, it will keep resolving there silently.

Namespace and config-key churn. Ownership transfers frequently coincide with renamed namespaces, renamed config files, and renamed command signatures. Even at 1.0.0, diff the published config against whatever you had before and re-run vendor:publish rather than assuming parity.

Commit the output, review the diff. Never let the sync run as a deploy step. Translation files are code — a bad sync that overwrites a hand-edited string is silent data loss. Run it locally or in a bot PR, and read the diff.

Empty-string vs. missing-key behavior differs. Laravel's __() falls back to the key when a translation is missing, but returns an empty string if the key exists with an empty value. Sync tools that create keys with empty values change runtime behavior in a way that's easy to miss in staging.

Watch multi-line and nested keys. JSON translation files and PHP array files behave differently; nested dot-notation keys (auth.failed) don't map cleanly into flat JSON. Confirm which format the package writes and whether your project mixes both.

Ordering noise. Some sync tools rewrite files with sorted keys, producing enormous diffs on first run. Do that first run as its own commit so subsequent real changes stay reviewable.

Extension point to check: whether the package exposes a contract or event for custom key extraction. If your project generates translation keys dynamically (e.g. from a CMS or enum), the default scanner will miss them, and you'll need to hook in or maintain a supplementary list — otherwise those keys look "unused" and may get pruned.

Debugging tip: when a key reports as missing but clearly exists, the culprit is almost always locale path config (the package scanning lang/ while your app uses resources/lang/, or vice versa) or a cached config (php artisan config:clear). Check both before filing an issue.