Skip to main content

Troubleshooting

Common issues and solutions for the Participaite Unified Plugin v2.

Installation Issues​

Script Not Loading​

Problem: The plugin script fails to load or doesn't initialize.

Solutions:

  1. Check script URL: Ensure you're using the correct CDN URL

    <script src="https://translator.participaite.de/ptp-translate-plugin"></script>

  2. Verify configuration timing: Configuration must be defined before the script tag

    <!-- ✅ Correct order -->
    <script>
      window.PTP_TRANSLATE_CONFIG = {
        /* config */
      };
    </script>
    <script src="https://translator.participaite.de/ptp-translate-plugin"></script>

    <!-- ❌ Wrong order -->
    <script src="https://translator.participaite.de/ptp-translate-plugin"></script>
    <script>
      window.PTP_TRANSLATE_CONFIG = {
        /* config */
      };
    </script>

  3. Check for JavaScript errors: Open browser console (F12) and look for error messages

Buttons Not Appearing​

Problem: Configured buttons don't show up on the page.

Diagnostic Steps:

  1. Check console for errors: Look for configuration or loading errors
  2. Verify feature is enabled: 
    translator: { enabled: true },
    EAS: { enabled: true },
    LS: { enabled: true }
  3. Check CSS conflicts: Ensure your site's CSS isn't hiding the buttons
  4. Verify selectors: For inside placement, ensure the container exists

Configuration Issues​

Invalid Configuration​

Problem: Configuration object has syntax errors or invalid values.

Common Mistakes:

// ❌ Wrong: Missing quotes around property names
window.PTP_TRANSLATE_CONFIG = {
  translator: {
    sourceLang: de, // Should be "de"
    targetLangs: [{ code: en }], // Should be "en"
  },
};

// ✅ Correct: Proper JSON syntax
window.PTP_TRANSLATE_CONFIG = {
  translator: {
    sourceLang: "de",
    targetLangs: [{ code: "en" }],
  },
};

Solution: Validate your configuration using browser console:

console.log(window.PTP_TRANSLATE_CONFIG);

LS Target Element Not Found​

Problem: Leichte Sprache button appears but content isn't simplified.

Solutions:

  1. Verify selector exists: Use browser DevTools to check if your targetElementSelector matches an element

    console.log(document.querySelector("{{your_selector}}")); // Should not be null

  2. Check selector specificity: Make sure the selector targets the correct content container

    // ❌ Too broad
    LS: {
      targetElementSelector: "body";
    }

    // ✅ Specific to content
    LS: {
      targetElementSelector: "main";
    }
    LS: {
      targetElementSelector: ".content-wrapper";
    }

Button Placement Issues​

Problem: Buttons appear in wrong positions or overlap with site elements.

Solutions:

  1. Floating placement conflicts:

    buttonPlacement: {
      type: "floating",
      position: "bottom-right",
      offset: { x: 20, y: 80 }, // Adjust to avoid overlaps
      zIndex: 10000 // Increase if covered by other elements
    }

  2. Inside placement not working:

    buttonPlacement: {
      type: "inside",
      buttonContainer: "#my-container", // Ensure this element exists
      buttonInsidePosition: "end"
    }

Translation Issues​

Translations Not Loading​

Problem: Language dropdown appears but switching languages doesn't work.

Diagnostic Steps:

  1. Check network requests: Open DevTools Network tab and look for failed API calls
  2. Verify language codes: Ensure target language codes are valid
  3. Check source language: Make sure sourceLang is correctly set

Common Language Code Issues:

// ❌ Wrong: Invalid language codes
targetLangs: [{ code: "english" }]; // Should be "en"

// ✅ Correct: Valid ISO language codes
targetLangs: [{ code: "en" }, { code: "fr" }, { code: "es" }];

Partial Translations​

Problem: Only some text gets translated.

Possible Causes:

  1. Content loaded dynamically: Text added after plugin initialization won't be translated
  2. Skipped elements: Elements with ptp-skip class are ignored
  3. Complex DOM structure: Deeply nested or unusual HTML might not be detected

Solutions:

  1. Check skip selectors: Review your skipSelectors configuration 
    LS: {
      skipSelectors: [".ads", ".cookie-banner"]; // Make sure these are intentional
    }

Performance Issues​

Slow Loading​

Problem: Plugin takes a long time to load or initialize.

Solutions:

  1. Check content size: Very large pages may take longer to process
  2. Optimize selectors: Use specific selectors to target only necessary content

Getting Help​

If you're still experiencing issues:

  1. Check browser console for error messages
  2. Verify configuration against the Configuration Reference
  3. Test with minimal configuration to isolate the issue
  4. Check network connectivity to the Participaite API
  5. **Contact us: ** https://participaite.de/kontakt/

Minimal Test Configuration​

Use this minimal configuration to test basic functionality:

<script>
  window.PTP_TRANSLATE_CONFIG = {
    translator: {
      enabled: true,
      sourceLang: "de",
      targetLangs: [{ code: "en" }],
    },
  };
</script>
<script src="https://translator.participaite.de/ptp-translate-plugin"></script>

Still Need Help?​