Kunstmaan German Backend Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation Add the bundle via Composer:

   composer require dreadlabs/kunstmaan-german-backend-bundle
   

   Register it in config/bundles.php (Laravel 5.4+) or AppKernel.php (older versions):

   // config/bundles.php
   DreadLabs\KunstmaanGermanBackendBundle\DreadLabsKunstmaanGermanBackendBundle::class => ['all' => true],
   

   Or in AppKernel.php (if using Symfony/Kunstmaan):

   new DreadLabs\KunstmaanGermanBackendBundle\DreadLabsKunstmaanGermanBackendBundle(),
   

2. Clear Cache After installation, clear Kunstmaan’s cache:

   php bin/console kunstmaan:cache:clear
   

3. First Use Case Switch the Kunstmaan backend to German via the language selector (if available) or force it via URL:

   /de/admin
   

   Verify German translations appear in the UI (e.g., menus, buttons, validation messages).

Implementation Patterns

Workflows

1. Localization Overrides

   • The bundle provides German translations for Kunstmaan’s default backend strings (e.g., "Save," "Cancel," "Page").
   • Extend translations: Override specific translations by adding them to your project’s translation files (e.g., Resources/translations/messages.de.xlf or .yml). Example (messages.de.yml):

     kunstmaan_admin:
         node:
             create: "Erstelle neuen Knoten"
     

2. Integration with Kunstmaan’s Translation System

   • Kunstmaan uses Symfony’s translation component. Leverage trans() helper in templates:

     {{ 'kunstmaan_admin.node.create'|trans }}
     

   • For dynamic contexts, use the transChoice filter.

3. Theme-Specific Adjustments

   • If using a custom Kunstmaan theme, ensure the bundle’s translations are loaded by checking:
     • Resources/config/translations.xml (if using XLIFF).
     • Resources/config/translations.yml (if using YAML).
   • Merge translations with kunstmaan:translation:dump:

     php bin/console kunstmaan:translation:dump
     

4. Validation Messages

   • German validation errors (e.g., "This field is required") are automatically handled. Customize by extending the validation.messages.de.xlf file.

Best Practices

• Testing: Test translations in a staging environment before deploying to production.
• Fallbacks: Ensure English translations remain fallback options in config/parameters.yml:

  locale: de
  default_locale: en
  

• Partial Overrides: Use ~ in YAML to override specific keys without duplicating the entire file.

Gotchas and Tips

Pitfalls

1. Cache Dependencies

   • Issue: Translations may not update immediately due to caching.
   • Fix: Clear cache after adding new translations:

     php bin/console cache:clear
     php bin/console kunstmaan:cache:clear
     

2. Missing Translations

   • Issue: Some Kunstmaan modules (e.g., custom plugins) may lack German translations.
   • Fix: Check if the module supports translations via Resources/translations/. Contribute missing translations to the community or extend them locally.

3. Locale Configuration

   • Issue: Kunstmaan may default to English even after installing the bundle.
   • Fix: Explicitly set the locale in config/parameters.yml:

     kunstmaan_admin_locale: de
     

   • Or override the default locale in AppKernel.php:

     $kernel->setLocale('de');
     

4. Symfony/Kunstmaan Version Mismatch

   • Issue: The bundle may not support newer Kunstmaan versions (archived status).
   • Fix: Check compatibility with your Kunstmaan version (e.g., kunstmaan/admin-bundle:^3.0). Fork and update if needed.

Debugging Tips

• Check Loaded Translations: Use Symfony’s debug toolbar to verify German translations are loaded under the "Translations" tab.
• Log Missing Keys: Enable debug mode (APP_DEBUG=true) to log missing translation keys in var/log/dev.log.
• Translation Dumping: Regenerate translation files with:

  php bin/console kunstmaan:translation:dump --force
  

Extension Points

1. Custom Translation Domains Extend the bundle by adding new translation domains in config.yml:

   kunstmaan_german_backend:
       domains:
           - 'your_custom_domain'
   

2. Dynamic Language Switching Implement a language switcher in your backend using Kunstmaan’s NodeService and Locale utilities:

   $locale = $this->get('kunstmaan_admin.locale');
   $locale->setLocale('de');
   

3. Fallback Logic Override the fallback locale in services.yml:

   kunstmaan_admin.locale:
       class: Kunstmaan\AdminBundle\Helper\Locale
       arguments:
           - '%locale%'
           - '%default_locale%'  # Set to 'en' or another fallback