Download the PHP package tmi/translation-bundle without Composer

TMI Translation Bundle - Doctrine Entity Translations for Symfony

A modern, high-performance translation bundle for Symfony that stores entity translations in the same table as the source entity - no expensive joins, no complex relations.

🚀 Why This Bundle?

This bundle solves: Symfony Doctrine translation, entity localization, multilingual entities, Doctrine translatable, Symfony translation bundle, database translations, entity translations

❌ Traditional Translation Problems:

• Multiple tables with complex joins
• Performance overhead on translated entities
• Complex queries for simple translations
• Schema changes required for each new translation

✅ Our Solution:

• Single table for all translations
• No performance penalty - same query speed as non-translated entities
• Simple implementation - just add interface and trait
• Zero schema changes when adding new languages

🎯 Key Features

• 🏷️ Same-table storage - Translations stored with source entity (no joins needed)
• ⚡ Blazing fast - No performance overhead on translated entities
• 🔄 Auto-population - Automatic relation translation handling
• 🎯 Inherited entity support - Works with complex entity hierarchies
• 🛡️ Type-safe - Full PHP 8.4 type declarations throughout
• 🧪 100% tested - Comprehensive test suite with full coverage
• 🤖 AI-ready - Includes AI skills for Claude Code and other assistants

🏗️ About This Version

This is a complete refactoring based on PHP 8.4, Symfony 7.3, and Doctrine ORM 3.5 of the fork from umanit/translation-bundle, implemented with modern development practices and featuring 100% code coverage with comprehensive test suites.

⚠️ Limitations

• ManyToMany associations are currently not supported. This includes usage with the SharedAmongstTranslations attribute.
• Entities with single-column unique: true constraints will trigger a validation error at cache:warmup -- use composite constraints (field + locale) instead. See UPGRADING.md for the pattern.
• Requires PHP 8.4+, Symfony 7.3+ and Doctrine ORM 3.5+ (see legacy versions for older support)

📦 Installation

Register the bundle to your config/bundles.php.

⚙️ Configuration

Configure your available locales in framework.yaml and, optionally, additional bundle settings:

Doctrine DBAL Custom Type - TuuidType

To use the TuuidType in your Symfony project, you must register it in your Doctrine configuration:

This ensures that Doctrine recognizes the tuuid type and avoids errors like:

🚀 Quick Start

Make your entity translatable

Implement Tmi\TranslationBundle\Doctrine\TranslatableInterface and use the trait Tmi\TranslationBundle\Doctrine\ModelTranslatableTraiton an entity you want to make translatable.

Translate your entity

Use the service tmi_translation.translator.entity_translator to translate a source entity to a target language.

Every attribute of the source entity will be cloned into a new entity, unless specified otherwise with the EmptyOnTranslate attribute. Generated IDs (properties with #[ORM\Id] + #[ORM\GeneratedValue]) are automatically reset to null on cloned translations.

🔧 Advanced Usage

Usually, you don't wan't to get all fields of your entity to be cloned. Some should be shared throughout all translations, others should be emptied in a new translation. Two special attributes are provided in order to solve this.

SharedAmongstTranslations

Using this attribute will make the value of your field identical throughout all translations: if you update this field in any translation, all the others will be synchronized. If the attribute is a relation to a translatable entity, it will associate the correct translation to each language.

Note: ManyToMany associations are not supported with SharedAmongstTranslations yet.

⚠️ Ordering caveat. Shared values propagate to translations created after the value is set. If you set a shared field in one locale and translate the entity to other locales later, those earlier siblings keep their stale value. To back-fill existing data, run:

The command propagates #[SharedAmongstTranslations] column values from the default-locale row to every sibling. Shared associations are out of scope (and unsupported).

EmptyOnTranslate

This attribute will empty the field when creating a new translation. ATTENTION: The field has to be nullable or instance of Doctrine\Common\Collections\Collection!

Translate event

You can alter the entities to translate or translated, before and after translation using the Tmi\TranslationBundle\Event\TranslateEvent

• TranslateEvent::PRE_TRANSLATE called before starting to translate the properties. The new translation is just instanciated with the right oid and locale
• TranslateEvent::POST_TRANSLATE called after saving the translation

Filtering your contents

To fetch your contents out of your database in the current locale, you'd usually do something like $repository->findByLocale($request->getLocale()).

Alternatively, you can use the provided filter that will automatically filter any Translatable entity by the current locale, every time you query the ORM. This way, you can simply do $repository->findAll() instead of the previous example.

Add this to your config.yml file:

(Optional) Disable the filter for a specific firewall

Usually you'll need to administrate your contents. For doing so, you can disable the filter by configuring the disabled_firewalls option in your configuration:

Quick Fix for unique fields

If you need a translatable slug (or UUID), adjust your database schema to make the slug unique per locale, instead of globally:

Querying Locale Variants

Always use these helpers for cross-locale lookups. Hand-rolled WHERE tuuid = ... queries get the tmi_translation_locale_filter wrong and silently return only the current-locale row.

The quickest way is to extend the ready-made TranslatableEntityRepository base class:

If your repository must extend something else, use TranslatableRepositoryTrait directly (v2.1):

Both methods temporarily disable the tmi_translation_locale_filter (if enabled) to query across all locales.

The tuuid column is automatically indexed: the bundle injects a composite (tuuid, locale) index into every translatable entity at mapping time, so locale-variant lookups never hit an unindexed scan. Set unique_locale_variants: true to promote it to a UNIQUE constraint — do this only once existing data is free of duplicate locale rows (see tmi:translation:doctor).

Translation Linkage & Diagnostics

Every locale variant of an entity shares one Tuuid. Translations created through EntityTranslator::translate() inherit it automatically. If application code instead does new Entity() + setLocale('de_DE') and persists it without a shared Tuuid, the result is a standalone entity linked to no other locale — a silent data bug.

The bundle guards against this:

• On persist — an entity persisted in a non-default locale without a shared Tuuid is flagged. strict_orphan_check controls the reaction: true throws, false logs a warning, null (default) is auto — throws when kernel.debug is on, warns otherwise.

• tmi:translation:doctor — scans every translatable table and reports standalone translations, incomplete translations (fewer locale rows than configured locales) and duplicate (tuuid, locale) pairs. Exits non-zero on findings, so it works as a post-migration / CI integrity gate:

• tmi:translation:sync-shared — see below.

📊 Performance Comparison

🤖 AI-Assisted Development

This bundle includes AI skills that help you implement translations correctly. These skills work with Claude Code and other AI coding assistants.

Available Skills

Using with Claude Code

If you're using Claude Code, the skills are automatically available when working in this project. Simply describe what you need:

Claude Code will automatically invoke the appropriate skill and guide you through the process.

Using with Other AI Assistants

The skills are defined in .agents/skills/ and follow a standard markdown format. Point your AI assistant to:

• Entity Translation Setup
• Translation Debugger
• Custom Handler Creator

For comprehensive documentation optimized for AI assistants, see:

• llms.txt - Quick reference with all important links
• llms.md - Detailed guide with handler chain decision tree and troubleshooting

📖 Upgrading

See UPGRADING.md for migration guides between major versions.

🤝 Contributing

We welcome contributions!

📄 License

This bundle is licensed under the MIT License.

🙏 Acknowledgments

Based on the original work by umanit/translation-bundle, now completely modernized for current PHP and Symfony ecosystems.

⭐ If this bundle helps you, please give it a star on GitHub!