Contao I18Nl10N Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require blioxxx/contao-i18nl10n
   

   Ensure your Contao 4 project is up-to-date.

2. First Use Case:

   • Enable the module: Activate the bundle in config/bundles.php:

     return [
         // ...
         Blioxxx\ContaoI18nl10nBundle\ContaoI18nl10nBundle::class => ['all' => true],
     ];
     

   • Configure locales: Edit config/packages/contao_i18nl10n.yaml to define supported locales (e.g., en, fr):

     locales:
         - en
         - fr
     

   • Create localized pages: Use the Contao backend to duplicate pages and assign them to locales via the module’s dropdown.

3. Where to Look First:

   • Backend UI: Navigate to System > Localization to manage locales and page assignments.
   • Twig Integration: Check templates/ for locale-specific templates (e.g., page_*.html5.twig).
   • Routing: Review config/routes.yaml for locale-aware routes (e.g., /{_locale}/page).

Implementation Patterns

Core Workflows

1. Page Localization:

   • Duplicate pages: Use the Contao backend to clone pages and assign them to locales via the i18nl10n field.
   • Automatic redirects: Configure redirects in contao_i18nl10n.yaml to handle fallback locales:

     redirects:
         fr: en  # Fallback to English if French page missing
     

2. Content Localization:

   • Fields: Extend Contao’s tl_content table with i18nl10n fields for multilingual content (e.g., title, text).
   • Example:

     // In a custom field type
     $this->strTable = 'tl_content';
     $this->addField('i18nl10n_title', 'text', 'Title', true);
     

3. Twig Integration:

   • Locale-aware templates: Use {% set locale = app.request.attributes.get('_locale') %} in Twig to render locale-specific content.
   • Example:

     {% if locale == 'fr' %}
         {{ content.i18nl10n_title|default(content.title) }}
     {% endif %}
     

4. API/CLI:

   • Export/Import: Use the contao:i18nl10n:export and import commands to sync locales:

     php bin/console contao:i18nl10n:export fr locales/fr.csv
     

Integration Tips

• Symfony Routing: Extend ContaoI18nl10nBundle's router to handle custom routes:

  # config/routes.yaml
  contao_i18nl10n:
      resource: "@ContaoI18nl10nBundle/Resources/config/routing.yaml"
      prefix:   "/{_locale}"
  

• Event Listeners: Subscribe to ContaoI18nl10nBundle::EVENT_LOCALIZE to customize localization logic:

  use Symfony\Component\EventDispatcher\GenericEvent;
  
  $dispatcher->addListener(
      ContaoI18nl10nBundle::EVENT_LOCALIZE,
      function (GenericEvent $event) {
          $event->setArgument('fallback', 'en');
      }
  );
  

Gotchas and Tips

Pitfalls

1. Locale Fallbacks:

   • Issue: Missing fallback locales cause 404s. Always define redirects in config.
   • Fix: Test with php bin/console debug:router to verify routes.

2. Caching:

   • Issue: Contao’s cache may not reflect locale changes immediately.
   • Fix: Clear cache after updates:

     php bin/console cache:clear
     

3. Database Conflicts:

   • Issue: Duplicate tl_page entries if not managed via the module’s UI.
   • Fix: Use the backend’s i18nl10n field to avoid manual DB edits.

4. Twig Debugging:

   • Issue: locale variable not updating in Twig.
   • Fix: Ensure ContaoI18nl10nBundle is loaded before TwigBundle in bundles.php.

Debugging Tips

• Log Locale Requests: Add a listener to log _locale values:

  $dispatcher->addListener(
      KernelEvents::REQUEST,
      function (RequestEvent $event) {
          error_log('Locale: ' . $event->getRequest()->attributes->get('_locale'));
      }
  );
  

• Check Backend Permissions: Ensure the Contao user has permissions to edit tl_page.i18nl10n.

Extension Points

1. Custom Fields: Extend the module to support custom fields:

   // src/EventListener/CustomFieldListener.php
   use Blioxxx\ContaoI18nl10nBundle\Event\LocalizeEvent;
   
   public function onLocalize(LocalizeEvent $event) {
       $event->addField('custom_field', 'tl_custom_field');
   }
   

2. Override Templates: Copy vendor/blioxxx/contao-i18nl10n/src/Resources/contao/templates/ to templates/ to customize backend UI.

3. Locale-Specific Assets: Use {% set asset_path = path('assets', {'_locale': locale}) %} in Twig to load locale-aware CSS/JS.