Translation Editor Bundle Laravel Package

Getting Started

1. Install as a dev-only dependency

composer require --dev jbtronics/translation-editor-bundle

The --dev flag matters: on production deploys (composer install --no-dev) the bundle class won't exist, so it can't be accidentally activated.

2. Register it for dev only

// config/bundles.php
return [
    // ...
    Jbtronics\TranslationEditorBundle\TranslationEditorBundle::class => ['dev' => true],
];

(Verify the exact class name in vendor/jbtronics/translation-editor-bundle/ if your installed version differs — the package is small and namespaces have changed across releases.)

3. Confirm the profiler is on, then dump the bundle's config reference so you know what knobs your version actually exposes:

php bin/console debug:config translation_editor   # current values
php bin/console config:dump-reference translation_editor

4. First use case — fix a typo without leaving the browser. Load any page in dev, click the Symfony toolbar, open the Translation panel, and look for the edit affordance (pencil/link) next to a message. Change the text, save, refresh the page. That's the whole value proposition: see the string → fix the string → verify it renders, with no grep through translations/messages.en.yaml.

Start with the highest-friction scenario in your app: a page with dozens of labels where a stakeholder says "this word is wrong." That's where this bundle pays for itself.

Implementation Patterns

The tight edit loop (the primary workflow). Navigate the real UI, not the file. Open the profiler on the exact page that renders the copy, edit in the Translation panel, refresh and confirm the rendered output. Because you're editing from the request that uses the message, you're guaranteed to be touching the locale/domain actually in play.

Pair it with debug:translation for discovery. The profiler panel only knows about messages resolved in the current request — it is not a catalogue browser. Use the console to find gaps, then use the browser to fill them:

php bin/console debug:translation en --only-missing
php bin/console debug:translation fr

Use the profiler's "missing translations" list to jump to a page that triggers the fallback, then edit there.

Verify which file you wrote to. After a handful of edits, run git status — the bundle writes to the resource Symfony resolved, and that may be a file you didn't expect. This one habit prevents the most common "where did my translation go?" incident.

Custom translation directories. If your project loads translations from non-default paths via framework.translator.paths, make sure those paths are registered so the resolved resources are the ones you intend to edit. Files inside vendor/ are fair game for the editor but will be destroyed on composer update — copy overrides into translations/ instead of editing bundle-shipped files.

Writable filesystem for Docker/VM setups. The PHP process must be able to write to translations/. Typical fix:

# docker-compose.yml
services:
  php:
    user: "${UID}:${GID}"
    volumes:
      - .:/app

Copy-review sessions. When a product owner reviews UI copy, drive the browser: page by page, edit in the panel, save, refresh to show the result live. Then commit the diff deliberately. This turns i18n review from a spreadsheet round-trip into a single paired session.

Guard the write path. Only expose this on a dev instance that is not internet-facing. If non-developers need it, give them a dedicated dev deployment behind authentication — never the production profiler.

Gotchas and Tips

• Profiler panel ≠ full catalogue. You can only edit messages that were loaded during the request you're inspecting. To fix a string on a rarely visited page, visit that page first.
• Fallback locale trap. If fr shows an English fallback, the message you're looking at lives in the en file. Editing "the French translation" in that state silently edits English. Check the locale/domain label before typing.
• YAML/XLIFF round-tripping is lossy. Symfony's dumpers drop comments and may reorder keys or change quoting. Expect noisy diffs after bulk edits — commit before a session so git diff is reviewable and revertible.
• Placeholders are not validated. %name%, {count, plural, ...}, and ICU syntax pass straight through. Always reload the page (and any pluralized variants) after saving; a broken placeholder only fails at render time.
• Cache behaviour. In dev the translator tracks resource freshness, so edits normally appear on refresh. If something stubbornly doesn't change, run bin/console cache:clear and check your OPcache/opcache.validate_timestamps settings, especially in Docker.
• Permission denied on save is almost always the CLI-vs-web-user split: cache:clear run as your host user creates root/www-data-owned artifacts and translation files. Check var/log/dev.log for the actual write exception and normalize ownership.
• Last write wins. There's no locking or history. Two developers editing the same file concurrently will clobber each other. Coordinate, or keep sessions short and commit often.
• No translation memory, no review workflow. This is a file editor with a nice UI — not a TMS. Keep your existing process (Crowdin/Weblate/PR review) for real translation work; use this for the fast in-context fixes.
• Small project, no dependents. 8 stars, 0 dependents, single maintainer. Pin the version in composer.json, skim the source once (it's a few files) so you know exactly which routes and filesystem writes you're enabling, and don't plan architecture around it.
• Template overrides are the main extension point. If you need to tweak the panel UI, check whether the installed version ships Twig templates and override them under templates/bundles/TranslationEditorBundle/.
• Proxy/absolute-URL issues. If the save request 404s or posts to the wrong host behind a reverse proxy, set framework.router.default_uri or configure trusted_proxies so the profiler-generated URLs are correct.