Translation Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require argentum/translation-bundle:dev-master
   

   Register the bundle in AppKernel.php:

   new Argentum\TranslationBundle\ArgentumTranslationBundle(),
   

2. Configure Locales: In parameters.yml:

   parameters:
       locales: ['en', 'fr', 'es']
   

3. Enable Dependencies: In config.yml:

   imports:
       - { resource: ../../vendor/knplabs/doctrine-behaviors/config/orm-services.yml }
   bundles:
       - A2lix\TranslationFormBundle\A2lixTranslationFormBundle
   argentum_translation:
       locales: %locales%
   a2lix_translation_form:
       locales: %locales%
   

4. Create Database Schema:

   php app/console doctrine:schema:update --force
   

5. First Use Case: Access the Sonata Admin panel at /admin/argentum/translation/translationdomain/list to create translation domains and entries.

Implementation Patterns

Workflow for Translation Management

1. Define Domains: Use the Sonata Admin GUI to create translation domains (e.g., messages, validation). Each domain maps to a logical group of translations (e.g., form labels, error messages).

2. Add Translations: For each domain, add translation keys (e.g., homepage.title) and their values per locale via the GUI. The a2lix/translation-form-bundle provides a user-friendly form for this.

3. Override Defaults: Database translations override file-based translations (e.g., Resources/translations/messages.en.yml). Use this to customize translations without modifying bundle files.

4. Integrate with Twig: Use the standard Symfony translation syntax in templates:

   {{ 'homepage.title'|trans }}
   

5. Export/Import:

   • Export translations to files for version control:

     php app/console translation:export --dir=translations --format=yml
     

   • Import translations from files back into the database:

     php app/console translation:import --dir=translations
     

Integration with Entities

Use the Translatable behavior (from knplabs/doctrine-behaviors) to make entity fields translatable:

use Knp\DoctrineBehaviors\Model\Translatable\Translatable;

class Page
{
    use Translatable;

    // ...
}

Configure the behavior in config.yml:

knp_doctrine_behaviors:
    translatable:
        mappings:
            AppBundle\Entity\Page:
                fields: [title, content]

Cache Management

• Clear cache after importing translations to ensure updates take effect:

  php app/console cache:clear
  

• Translations are cached in files and loaded from the database only once per cache clear.

Gotchas and Tips

Pitfalls

1. Locale Configuration:

   • Ensure %locales% is defined in parameters.yml before configuring argentum_translation or a2lix_translation_form. Missing locales will break the admin panel.
   • Default locale must be the first in the array (used for fallback).

2. Schema Updates:

   • Running doctrine:schema:update --force drops existing tables. Use migrations for production:

     php app/console doctrine:migrations:diff
     php app/console doctrine:migrations:migrate
     

3. Sonata Admin Menu:

   • If the "Translation" group doesn’t appear in the Sonata menu, manually add it to sonata_admin.dashboard.groups in config.yml:

     sonata_admin:
         dashboard:
             groups:
                 Translation: ~
     

4. Translation Loading Order:

   • File-based translations (e.g., Resources/translations/) load before database translations. Database entries will override files, but files are still required for fallback.

5. PHP 7+ Compatibility:

   • The bundle supports Symfony 3.3+ and PHP 7+, but some tests may fail on PHP 7/HHVM. Ignore these if your environment works.

Debugging Tips

1. Missing Translations:

   • Verify the translation domain exists in the database (translation_domain table).
   • Check if the locale is included in %locales%.
   • Clear cache after adding new translations.

2. Admin Panel Issues:

   • Ensure sonata-project/doctrine-orm-admin-bundle is installed (required for Sonata Admin to work).
   • Check for JavaScript errors in the browser console (Sonata Admin relies on jQuery).

3. Export/Import Failures:

   • Use --format=yml for debugging to see the parsed translation files.
   • Ensure the target directory (--dir) is writable.

Extension Points

1. Custom Translation Domains: Extend the TranslationDomain entity to add custom fields (e.g., priority, author):

   namespace Argentum\TranslationBundle\Entity;
   
   class TranslationDomain extends \Sonata\DoctrineORMAdminBundle\Model\BaseTranslationDomain
   {
       // Add custom fields here
   }
   

   Update the database schema and admin configuration accordingly.

2. Override Export/Import: Extend the TranslationExporter and TranslationImporter services to add custom logic (e.g., validation, logging):

   services:
       app.custom_translation_exporter:
           class: AppBundle\Service\CustomTranslationExporter
           parent: argentum_translation.exporter
           tags:
               - { name: argentum_translation.exporter }
   

3. Add Translation Sources: Extend the loader to support additional sources (e.g., API calls, external databases) by implementing Argentum\TranslationBundle\Loader\LoaderInterface.

4. Customize Sonata Admin: Override the admin class for TranslationDomain to add filters, actions, or custom fields:

   namespace AppBundle\Admin;
   
   use Argentum\TranslationBundle\Admin\TranslationDomainAdmin;
   
   class CustomTranslationDomainAdmin extends TranslationDomainAdmin
   {
       protected function configureListFields(ListMapper $listMapper)
       {
           $listMapper->add('name');
           $listMapper->add('createdAt', 'datetime', ['template' => 'ArgentumTranslationBundle:Admin:field_datetime.html.twig']);
       }
   }
   

   Register the override in config.yml:

   sonata_admin:
       options:
           models:
               Argentum\TranslationBundle\Entity\TranslationDomain:
                   admin_service: app.custom_translation_domain_admin