Dont Translate Bundle Laravel Package

Getting Started

Minimal Setup

1. Install via Composer:

   composer require antfroger/dont-translate-bundle
   

2. Enable the Bundle in AppKernel.php:

   $bundles[] = new Af\Bundle\DontTranslateBundle\AfDontTranslateBundle();
   

3. Configure (optional) in config/packages/af_dont_translate.yaml:

   af_dont_translate:
       mode: "get"  # or "cookie"
       param_name: "untrans"
       roles: ["ROLE_ADMIN", "ROLE_TRANSLATOR"]
   

First Use Case

• Debugging Translations: Append ?untrans to any URL to see raw translation keys instead of translated strings. Example:

  http://your-app.dev/admin/dashboard?untrans
  

  This is invaluable for:
  • Verifying translation keys match expectations.
  • Debugging missing translations without modifying code.
  • Collaborating with translators to confirm keys.

Implementation Patterns

Workflows

1. Development Workflow:

   • Use mode: "get" for quick debugging during development.
   • Toggle translations on/off via URL parameters (e.g., ?untrans=1).
   • Ideal for local testing or CI environments where security is less critical.

2. Production Workflow:

   • Use mode: "cookie" for production-like environments.
   • Restrict access via roles (e.g., only admins/translators).
   • Example cookie setup:

     // Set via JavaScript or browser dev tools
     document.cookie = "untrans=true; path=/";
     

   • Clear the cookie to revert to translated content.

3. Integration with Twig:

   • The bundle automatically intercepts translator calls in Twig templates. No template changes required.
   • Example: {{ 'welcome.message'|trans }} will show welcome.message when untrans is active.

4. API/CLI Usage:

   • For APIs or CLI commands, use the Translator service directly:

     $translator = $this->get('translator');
     $translator->trans('key'); // Returns raw key if untrans is active
     

Advanced Patterns

• Dynamic Toggle: Create a toggle button in your admin panel to set the cookie:

  <button onclick="document.cookie='untrans={{ isUntransActive ? 'false' : 'true' }}; path=/'; location.reload();">
      {{ isUntransActive ? 'Disable' : 'Enable' }} Raw Keys
  </button>
  

• Environment-Specific Config: Override config per environment (e.g., config/packages/dev/af_dont_translate.yaml):

  af_dont_translate:
      mode: "get"  # Only GET mode in dev
  

• Custom Parameter Names: Use a unique parameter name (e.g., debug_keys) to avoid conflicts:

  af_dont_translate:
      param_name: "debug_keys"
  

Gotchas and Tips

Pitfalls

1. Role-Based Access:

   • If roles are configured, unauthenticated users cannot trigger the feature, even with the GET parameter or cookie.
   • Test with ROLE_USER or no roles if you want public access:

     af_dont_translate:
         roles: []  # No roles = public access
     

2. Cookie Scope:

   • Cookies are set globally. Ensure param_name is unique to avoid unintended side effects (e.g., conflicting with other bundles).

3. Caching:

   • The bundle bypasses translation caches. If you rely on cache warming (e.g., cache:pool:clear), ensure translations are re-warmed after toggling untrans.

4. Symfony 4+ Compatibility:

   • This bundle is Symfony 2.x only. For Symfony 4/5/6, consider:
     • Forking the bundle and updating dependencies.
     • Using a similar approach with Symfony’s TranslatorInterface event listeners.

5. Nested Translations:

   • The bundle shows raw keys for nested arrays (e.g., ['key' => 'value']). If your translations use complex structures, test thoroughly.

Debugging Tips

1. Check Active State:

   • Add a debug Twig function to verify if untrans is active:

     {{ dump(app.request.query.get('untrans') || app.request.cookies.get('untrans')) }}
     

   • Or in PHP:

     $this->get('af_dont_translate.listener')->isActive();
     

2. Override Translator Globally:

   • If the bundle isn’t working, manually override the translator in a service:

     # config/services.yaml
     services:
         App\Service\CustomTranslator:
             decorates: 'translator'
             arguments: ['@App\Service\CustomTranslator.inner']
     

     Then implement logic to check untrans in translate() method.

3. Clear Cookies:

   • If cookies persist unexpectedly, clear them via:

     curl -X POST --cookie "untrans=" http://your-app.dev
     

     Or use browser dev tools to delete the cookie manually.

Extension Points

1. Custom Logic:

   • Extend the AfDontTranslateBundle\EventListener\TranslatorListener to add custom conditions:

     // src/EventListener/CustomTranslatorListener.php
     use Af\Bundle\DontTranslateBundle\EventListener\TranslatorListener;
     
     class CustomTranslatorListener extends TranslatorListener {
         public function isActive() {
             if (parent::isActive()) {
                 return true;
             }
             // Add custom logic (e.g., IP whitelist)
             return $this->request->getClientIp() === '127.0.0.1';
         }
     }
     

   • Override the service in config/services.yaml:

     services:
         Af\Bundle\DontTranslateBundle\EventListener\TranslatorListener:
             class: App\EventListener\CustomTranslatorListener
     

2. UI Indicators:

   • Add a visual indicator (e.g., badge) in your layout to show when untrans is active:

     {% if app.request.query.get('untrans') or app.request.cookies.get('untrans') %}
         <div class="untrans-badge">🔍 RAW KEYS MODE</div>
     {% endif %}
     

3. Environment Variables:

   • For Docker/Kubernetes, pass the mode via environment variables by extending the bundle’s configuration loader:

     // config/packages/af_dont_translate.yaml
     af_dont_translate:
         mode: "%env(UNTRANS_MODE)%"  # Defaults to "get" if not set