Statamic Translation Manager Laravel Package

Getting Started

The package is a Statamic addon, so it follows the standard addon lifecycle. Install it like any other:

composer require ryanmitchell/statamic-translation-manager

Then publish any config and clear caches so the CP picks up the new nav/utility entry:

php artisan vendor:publish --tag=statamic-translation-manager-config
php artisan config:clear
php artisan cache:clear

Where to look first:

1. config/statamic/translation-manager.php (after publishing) — this is where you'll find the knobs for which language paths are exposed and which locales are editable. Read this before touching anything else.
2. The Control Panel — the manager is surfaced as a CP screen (typically a Utilities entry or a nav item under Tools). That UI is the product; the PHP side is mostly plumbing.
3. The addon's src/ directory if you need to extend it — look for the service provider to see registered routes, nav items, and any view/Vue components.

First use case: you have lang/en/messages.php (or resources/lang/en/messages.php depending on Laravel version) with application strings, and you want a non-developer to fix copy or add a second locale without opening an editor. Point the config at that directory, log into the CP, open the Translation Manager, and edit the strings. That's the whole loop: developer seeds keys → editor fills values → template renders them.

A minimal end-to-end smoke test:

// lang/en/messages.php
return [
    'welcome' => 'Welcome to :site',
];

{{ trans key="messages.welcome" :site="config:app.name" }}

Edit messages.welcome in the CP, save, reload the page. If the string doesn't change, you have a cache issue (see Gotchas).

Implementation Patterns

Developer-seeds, editor-fills. The healthiest workflow with a translation manager is to never let the editor invent keys. Add new keys in code, commit them with an English placeholder, and let the CP fill in the real copy and other locales. This keeps grep-ability and prevents orphaned keys from accumulating.

Per-domain language files. Split translations by domain (messages.php, validation.php, emails.php, marketing.php) rather than one giant file. The manager lists files as groups; smaller files mean faster loads and fewer merge conflicts when two people edit different domains at once.

Multisite tie-in. If you're running Statamic multisite, map each site's locale to a Laravel locale code (en, de, fr_CA) and keep that mapping consistent between config/statamic/sites.php and whatever locale list the manager exposes. Mismatches here are the number-one cause of "I translated it but the other site still shows English."

Blade / Antlers parity. Because Laravel handles the lookup, the same keys work in both:

{{ __('messages.welcome', ['site' => config('app.name')]) }}

{{ trans key="messages.welcome" :site="config:app.name" }}

Keep placeholders (:site, :count) identical across locales — the manager won't catch a renamed placeholder for you.

Content vs. chrome. Use Statamic's own fieldset/i18n for content translations (bard, titles, SEO fields) and this package for chrome (buttons, nav labels, validation messages, email templates). Trying to push page content through language files is a common anti-pattern — it fights the CMS instead of using it.

Review gate. Treat the language directory like any other source file: PR review, CI check that files still return a valid array (php -l), and a deploy step that clears caches. This package writes PHP arrays, so a malformed save can take down the site if it lands in production unchecked.

Gotchas and Tips

Caching is the default explanation for everything. After a save, Laravel may still serve the cached config, compiled views, or the OPcache of the PHP file. When a translation "doesn't take," run:

php artisan cache:clear
php artisan config:clear
php artisan view:clear

On production with OPcache, you may need to reload PHP-FPM before the new array file is picked up.

File format sensitivity. Laravel supports both PHP array files (lang/en/messages.php) and JSON files (lang/en.json). The manager targets PHP array files in most configurations; JSON-based translations and vendor/ namespaced files (vendor::package.key) generally won't round-trip cleanly through a CP editor. Keep managed strings in your own lang/ tree and leave vendor translations alone.

Nested keys and dot notation. A file like ['auth' => ['failed' => '...']] is addressed as auth.failed. If the manager flattens or re-keys on save, deeply nested structures can get restructured. Snapshot a file (git diff lang/) after your first save to confirm the shape survives the round-trip before letting an editor loose.

Permissions. The web server user (e.g. www-data) needs write access to the lang/ directory and its files. This is easy to miss in Docker/Forge setups where deploys leave files owned by the deploy user. chown -R www-data:www-data lang/ or an explicit chmod on the directory is usually the fix; check storage/logs/laravel.log for write errors if saves silently fail.

Multisite locale mismatch. Confirm the locale codes in config/statamic/sites.php are the ones the manager reads. en_US vs en vs en-us will all silently resolve to different directories.

Conflicts with .php files under version control. Two editors saving different strings in the same file will produce merge conflicts on the array literal. Mitigate by splitting files, or by having the manager's changes go through a staging branch rather than straight to main.

Extension points. This is a small, single-maintainer addon (9 stars, no dependents). Before relying on internals, read the service provider to see what's actually exposed. If you need custom behavior — filtering which files appear, adding a "publish to all locales" button, or wiring in a translation API — expect to either fork or subclass rather than configure, because the public surface is likely thin.

Version drift. The package declares a 2026 release date but has essentially no downstream users. Pin the exact version in composer.json, and re-test the edit-and-save loop after every Statamic minor upgrade — CP component APIs and utility registration have moved around across Statamic 3/4/5.