Translate HubSpot Forms

709

Below is a step-by-step guide for adding Localize to your HubSpot forms. This allows them to be translated along with your website. HubSpot forms are presented inside an iframe on your website. Iframes are essentially web pages within another web page, and browser security doesn't allow the parent page to control the child iframe page. Therefore, we need to install Localize in the form and use a messaging system to communicate between the parent and child.

If you do not have a Localize Project yet, signup here!

1. Create a Form in HubSpot

Create/edit your form in HubSpot.

Edit the embed code to add an onFormReady parameter.

The following sample code shows the code to use in the onFormReady parameter.
This code will run once the form has been loaded into your web page.
1. The code will install Localize in the <head> tag of the iframe that contains the HubSpot form.
Replace the following placeholders in the scripts below: PARENT_DOMAIN, PROJECT_KEY, PORTAL_ID, FORM_ID, REGION

<script>
  hbspt.forms.create({
      portalId: "PORTAL_ID",
      formId: "FORM_ID",
      region: "REGION",
      target: "#hubspotForm",
      onFormReady: function() {
          var d = document;
          const iframe = document.getElementById("hs-form-iframe-0");
          const iframeWindow = iframe.contentWindow;
          const iframeDoc = iframeWindow.document;

          // Post a message to the parent page to let it know that the HubSpot iframe is ready.
          const messageData = {
              type: 'iframeHasLoaded',
              payload: 'The HubSpot iframe has been loaded.'
          };
          iframeWindow.parent.postMessage(messageData, "PARENT_DOMAIN");

          // Inject the Localize code snippet into the HubSpot form after the form has loaded.
          var script = iframeDoc.createElement("script");
          script.type = "text/javascript";
          script.async = true;
          script.onload = function() {
              (function(a){
                  if (!a.Localize){
                      a.Localize={};
                      for (var e=["translate","untranslate","phrase","initialize","translatePage","setLanguage","getLanguage","detectLanguage","getAvailableLanguages","untranslatePage","bootstrap","prefetch","on","off","hideWidget","showWidget","getSourceLanguage"],t=0;t<e.length;t++)
                        a.Localize[e[t]]=function(){};
                  }
              })(iframeWindow);

              iframeWindow.Localize.initialize({
                  key: 'PROJECT_KEY',
                  rememberLanguage: true,
                  disableWidget: true,
                  // other options go here, separated by commas
              });

              // Set up a listener so we can change the language to whatever the language is in the parent window.
              iframeWindow.addEventListener("message", receiveMessageFromParent, false);
              function receiveMessageFromParent(event) {
                  if (event.origin !== "PARENT_DOMAIN")
                      return;

                  if (event.data.to !== undefined) {
                      iframeWindow.Localize.setLanguage(event.data.to);
                    }
              }
          };

          script.src = 'https://global.localizecdn.com/localize.js';
          iframeDoc.getElementsByTagName('head')[0].appendChild(script);
      }
});
</script>

Export the embed code.
Add the embed code to your webpage where you want to display the form.

2. Add the Parent Page Code

Note: The code below replaces the standard Localize code snippet in the parent page.
The parent page code below assumes the id of the HubSpot form is hs-form-iframe-0.
Replace the following placeholders in the script below: PARENT_DOMAIN, PROJECT_KEY

<script src="https://global.localizecdn.com/localize.js"></script>
<script>
    (function(a) {
        if (!a.Localize) {
            a.Localize = {};
            for (var e = ["translate", "untranslate", "phrase", "initialize", "translatePage", "setLanguage", "getLanguage", "getSourceLanguage", "detectLanguage", "getAvailableLanguages", "setWidgetLanguages", "hideLanguagesInWidget", "untranslatePage", "bootstrap", "prefetch", "on", "off", "hideWidget", "showWidget"], t = 0; t < e.length; t++)
                a.Localize[e[t]] = function() {};
        }
    }
    )(window);

    // Set up a listener so we know when the iframe has loaded.
    window.addEventListener("message", receiveMessageFromIframe, false);
    var iframeHasLoaded = false;

    // Once the iframe has been loaded by HubSpot, set the language in the iframe.
    function receiveMessageFromIframe(event) {
        const eventData = event.data; 
        if (event.origin !== "PARENT_DOMAIN" || event.data.type !== 'hsFormCallback')
            return; 

        iframeHasLoaded = true;
        window.removeEventListener("message", receiveMessageFromIframe);

        const curLanguage = Localize.getLanguage();
        if (curLanguage) {
            // We're setting up a 'data' object here so we're compatible with the data object used in the setLanguage() call.
            const data = {
                to: curLanguage,
            };
            document.querySelector('iframe[id="hs-form-iframe-0"]').contentWindow.postMessage(data, '*');
        }
    }
    
    Localize.on("setLanguage", function(data) {
        // Pass the data object onto the iframe with id="hs-form-iframe-0" so it can change the current language to match the parent language.
        if (iframeHasLoaded) {
            document.querySelector('iframe[id="hs-form-iframe-0"]').contentWindow.postMessage(data, '*');
        }
    });

    Localize.initialize({
        key: 'PROJECT_KEY',
        rememberLanguage: true,
        // other options go here, separated by commas
    });
</script>

3. Add Initialization Options

Add any desired options to the Localize.initialize() calls above, check here for the full list of possible options.

Some popular options include:

autoApprove - use to fully automate your translation workflow
localizeImages - allows for localization of images in your site

4. Reload your website.

Visit your website in a browser.
Select one of your target languages using the language-switching widget.
Refresh the page.
When you change the language on the parent page, the language in the child iframe will be kept in sync.

Need Help?
Contact support for custom integration help or troubleshooting!