Entity Translator Laravel Package

Getting Started

Treat this as a legacy, low-level translation helper, not a full i18n framework. The first decision is whether you are already inside an Elcodi/Symfony 2.x codebase. If not, do not start here.

1. Check compatibility before installing. The package is archived, last released in 2016, and read-only. Expect PHP 5.6/7.0-era code and Symfony 2.x/3.0-era integration. Pin a tagged release that resolves against your legacy dependency set; do not use dev-master for anything production-facing.
2. Look at the component internals first. Start in src/Elcodi/Component/EntityTranslator/ and inspect:
   • the main translator service/interface,
   • the translation entity and repository,
   • Doctrine mapping resources,
   • service definitions / DI extension. Verify the actual service id and method signatures before writing application code.
3. Register the mapping and services. If you are not using the full Elcodi distribution, you will likely need to import the component’s Doctrine mapping and service configuration manually. If you are using elcodi/elcodi, use the version already wired there instead of mixing standalone component versions.
4. Use the first use case as a smoke test. A typical first case is translating a product name/description per locale:

// Verify exact signatures against the installed version.
$entityTranslator->save($product, $locale, [
    'name' => 'Produit',
    'description' => 'Description en français',
]);

$entityTranslator->translate($product, $locale);

If that works, wire it into one admin edit screen and one storefront read path before expanding to other entities.

Implementation Patterns

• Generic field translation records. The component is oriented around storing translations for entity fields by locale. In practice, keep translation data separate from the base entity and save it alongside the entity in the same transaction.
• Admin form pattern. Render locale tabs or sections and submit a structured payload such as translations[locale][field]. In the controller, normalize and save only the fields you allow:

  $translations = $request->request->get('translations', []);
  $entityTranslator->save($product, $locale, array_intersect_key($translations, array_flip([
      'name',
      'description',
      'slug',
  ])));
  

• Read path pattern. Prefer translating into a DTO/view model for display rather than mutating a Doctrine-managed entity and later flushing it. If the component mutates the entity in memory, detach it or use a clone before rendering.
• Fallback explicitly. Do not assume a missing translation returns the default-language value. Implement fallback in your application layer: requested locale → default locale → raw entity value.
• Preload for listings. For product/category listings, do not call the translator per row without checking what queries it triggers. Load translation rows for the current locale in bulk, or decorate the translator/repository with a cached lookup.
• Locale source of truth. Decide early whether locale is a string (en_US, fr_FR) or a Language entity. Keep the admin form, request locale, and stored translation locale identical; mismatches are a common source of “missing” translations.
• Service decoration. If you need caching, fallback rules, or audit logging, decorate the translator service or wrap it in an application-level service rather than editing vendor code.
• Extension point for custom entities. If the built-in translation entity does not fit, extend/replace the translation entity and repository through the component’s configuration, but only after checking how the translator resolves the repository.

Gotchas and Tips

• EOL and read-only. This package will not receive fixes. The repository README explicitly says pull requests are not accepted there; use the main elcodi/elcodi repository for issues/PRs. For a real legacy deployment, consider forking or using Composer patches.
• Not a replacement for Symfony Translator. This is entity-field translation, not message translation. Do not wire it into translator expectations or Symfony’s translation catalogue.
• Doctrine mapping is easy to miss. Standalone use often fails because the translation entity mapping was never imported or the table was not created. Check doctrine:mapping:info and run schema migrations before debugging application code.
• Mutating managed entities is risky. If translate() writes translated values onto the entity, any later flush() can overwrite the original locale values. Use a detached clone, DTO, or read-only translation step.
• Reflection/property access quirks. The translator may rely on getters/setters or reflection. Protected/private fields, missing accessors, or value objects can behave differently than expected. Test with the exact entity fields you plan to translate.
• Missing translations fail silently. Build explicit fallback and logging. A missing row should be visible in admin previews and tests, not just appear as a blank field in production.
• Locale normalization. Normalize and validate locale codes before saving. A stray fr vs fr_FR will create duplicate or invisible translation rows.
• Cache invalidation. If you add caching around translation lookups, clear it on entity save/delete and on locale changes.
• N+1 queries. Translation components commonly introduce extra queries per entity. Profile listing pages and eager-load/preload translations where possible.
• Testing tip. Test with an in-memory SQLite database and the real Doctrine mapping, not mocks alone. Most failures are mapping, locale, or persistence issues rather than translator logic.
• Replacement candidate. For new work, use a maintained approach such as Gedmo Translatable, a custom translation table with explicit DTOs, or Symfony’s own translation tooling for UI strings. Keep this package only where it is already part of an existing Elcodi installation.