Getting Started

Minimal Steps to Begin

Installation

composer require asm/translation-loader-bundle "~1.0"

new Asm\TranslationLoaderBundle\AsmTranslationLoaderBundle(),

Configure Routing (Optional GUI) Add to config/routes.yaml (Symfony 4+) or app/config/routing.yml (Symfony 2/3):

asm_translation_loader.gui:
    resource: "@AsmTranslationLoaderBundle/Resources/config/routing.yml"
    prefix: /translation

Set Up Database Table Run the schema update command:
```
php bin/console doctrine:schema:update --force
```
Import Translations Generate dummy translation files (if needed) and import existing translations:
```
php bin/console asm:translations:dummy
php bin/console asm:translations:import
```
Clear Cache Ensure translations are loaded from the database:
```
php bin/console cache:clear
```

First Use Case: Managing Translations via Database

Replace traditional .yml, .xliff, or .po files with a centralized database table. Use the GUI (if enabled) or CLI to:

Edit translations directly in the database.
Track changes via the history feature (if enabled in config/packages/asm_translation_loader.yaml):
```
asm_translation_loader:
    history: true
```

Implementation Patterns

Workflow: Transitioning from File-Based to Database Translations

Configure Locales and Domains Define supported locales and message domains in config/packages/asm_translation_loader.yaml:

asm_translation_loader:
    resources:
        fr: [messages, validation]
        de: [messages]
        en: ~
    driver: orm

Import Existing Translations Use the import command to migrate translations from files to the database:
```
php bin/console asm:translations:import -c  # Clears the database first
```
Delete Legacy Files Remove translation files from Resources/translations/ to avoid conflicts.

Edit via GUI or CLI

Use the admin GUI (/translation) for manual edits.

Update translations programmatically via Doctrine entities:

$translation = $entityManager->getRepository(Translation::class)->findOneBy([
    'domain' => 'messages',
    'locale' => 'en',
    'id' => 'welcome.message'
]);
$translation->setMessage('Hello, world!');
$entityManager->flush();

Export Back to Files (Optional) Regenerate files for backup or legacy systems:
```
php bin/console asm:translations:dump
```

Integration Tips

Custom Entity Manager Use a non-default Doctrine manager by configuring:

asm_translation_loader:
    database:
        entity_manager: my_custom_manager

Translation History Enable to track changes with user attribution:
```
asm_translation_loader:
    history: true
```
Access history via Doctrine queries on the TranslationHistory entity.
Fallback Logic Leverage Symfony’s built-in fallback chains (e.g., en_US → en). Configure in config/packages/framework.yaml:
```
framework:
    translator:
        fallbacks:
            - en
```

Testing Mock the TranslationLoader service in tests:

$this->container->set('asm_translation_loader.loader', $this->createMock(LoaderInterface::class));

Gotchas and Tips

Pitfalls

Performance on Large Imports The import command checks for existing translations row-by-row, which can be slow for large datasets. Consider:
- Using -c to clear the database first for faster imports.
- Batch processing or optimizing the Translation table indexes.
Circular Dependencies The history feature requires security_context. If you encounter issues, ensure:
- The security bundle is loaded.
- The security.context service is available (Symfony 2.5+ compatibility fix in v1.0.4).
Dummy File Generation The asm:translations:dummy command creates placeholder files (e.g., messages.en_US.db). These are not actual translation files but markers to avoid Symfony’s file-based loader conflicts. Delete them after setup.
Cache Invalidation After database changes, always run:
```
php bin/console cache:clear
```
Or manually refresh the MessageCatalogue via the asm:translations:dump command.
Symfony 3/4 Compatibility
- The bundle supports Symfony 2.3–3.0 but may require adjustments for newer versions (e.g., YAML config paths).
- For Symfony 4+, use config/packages/ instead of app/config/.

Debugging Tips

Check Database Schema Verify the translation table exists and has the correct structure:

CREATE TABLE translation (
    id INT AUTO_INCREMENT PRIMARY KEY,
    domain VARCHAR(255) NOT NULL,
    locale VARCHAR(255) NOT NULL,
    id VARCHAR(255) NOT NULL,
    message TEXT,
    UNIQUE KEY unique (domain, locale, id)
);

Enable Debug Mode Add to config/packages/dev/asm_translation_loader.yaml:
```
asm_translation_loader:
    debug: true
```
This logs loader events to var/log/dev.log.
Validate Translations Use the asm:translations:validate command (if available) or manually check for:
- Missing domain/locale/id combinations.
- Duplicate entries (violating the UNIQUE constraint).
Loader Resolution Issues If translations fail to load:
- Ensure driver: orm is set in the config.
- Verify the TranslationLoader service is registered (check services.yaml or compiled services).

Extension Points

Custom Loaders Extend the bundle by creating a custom loader (e.g., for JSON or API-based translations). Implement Asm\TranslationLoaderBundle\Loader\LoaderInterface and register it via a compiler pass.

Event Listeners Subscribe to asm.translation.updated events to trigger post-save actions:

// config/services.yaml
services:
    App\EventListener\TranslationListener:
        tags:
            - { name: kernel.event_listener, event: asm.translation.updated, method: onTranslationUpdate }

GUI Customization Override the admin templates in templates/AsmTranslationLoaderBundle/ to modify the UI (e.g., add bulk edit features).
Translation Validation Add custom validation rules to the Translation entity (e.g., regex for message content) by extending the bundle’s Translation entity class.

Pro Tips

Backup Strategy Regularly export translations to files for backup:

php bin/console asm:translations:dump --output=backups/translations_%date%.yml

Multi-Environment Sync Use the database to sync translations across environments (dev/staging/prod) via migrations or scripts.

Performance Optimization For high-traffic sites, cache translations at the application level (e.g., Redis) alongside Symfony’s cache:

$translator = $this->get('translator');
$cache = $this->get('cache.app');
$cacheKey = 'translations_' . md5($locale);
$translations = $cache->get($cacheKey, function() use ($translator, $locale) {
    return $translator->getCatalogue($locale)->all();
});

Translation Loader Bundle Laravel Package