​
Simple Integration

For non-complex, non-SSR frameworks or static site generators (SSG), integrating Locadapt is straightforward. Simply add the following script and stylesheet tags to your HTML:

<link rel="stylesheet" href="https://cdn.locadapt.com/locadapt.min.css" />
<script src="https://cdn.locadapt.com/locadapt.min.js" data-project-id="YOUR_PROJECT_ID"></script>

This is sufficient for most static sites built with frameworks like Gatsby, Jekyll, or simple React/Vue applications without server-side rendering.

That said, please note that in the latter case (when you don’t have pre-rendered HTML, like with vanilla React), you may want to use data-start-hidden and a loading indicator to prevent flashes of un-translated content. See Next.js for an example or refer to the Custom Attributes section below.

​
React

For a standard React application using Create React App, add Locadapt in your public/index.html file:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>React App</title>
    <link rel="stylesheet" href="https://cdn.locadapt.com/locadapt.min.css" />
    <script 
      src="https://cdn.locadapt.com/locadapt.min.js" 
      data-project-id="YOUR_PROJECT_ID"
    ></script>
  </head>
  <body>
    <div id="root"></div>
  </body>
</html>

​
Svelte

For Svelte applications, add Locadapt in your index.html or app.html file:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>Svelte App</title>
    <link rel="stylesheet" href="https://cdn.locadapt.com/locadapt.min.css" />
    <script 
      src="https://cdn.locadapt.com/locadapt.min.js" 
      data-project-id="YOUR_PROJECT_ID"
    ></script>
  </head>
  <body>
    <div id="app"></div>
  </body>
</html>

If you’re using SvelteKit, add the data-ssr-defer (and possibly defer if the compiler complains) attributes to the script tag:

<script 
  src="https://cdn.locadapt.com/locadapt.min.js" 
  data-project-id="YOUR_PROJECT_ID"
  data-ssr-defer
></script>

​
Next.js (Loading Spinner)

For Next.js, add Locadapt iin your pages/_document.js or app/layout.tsx file. This example also shows the use of data-start-hidden and a loading indicator to prevent flashes of un-translated content.

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <head>
        <link rel="stylesheet" href="https://cdn.locadapt.com/locadapt.min.css" />
        <script
          src="https://cdn.locadapt.com/locadapt.min.js"
          data-project-id="YOUR_PROJECT_ID"
          data-ssr-defer
          data-link-prevent-default
          data-start-hidden
          defer
        ></script>
      </head>
      <body>
        <div id="locadapt-optional-loading-indicator">
          {/* Add your loading indicator here if using `data-start-hidden` */}
        </div>
        {/* Must set `custom-base-content` to `display: none`, and use this ID, if set `data-start-hidden` */}
        <div id="custom-base-content" style={{ display: 'none' }}>
          {children}
        </div>
      </body>
    </html>
  )
}

​
Vue.js

For Vue.js applications, add Locadapt in your main index.html file:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8">
    <link rel="icon" href="/favicon.ico">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Vue App</title>
    <link rel="stylesheet" href="https://cdn.locadapt.com/locadapt.min.css" />
    <script 
      src="https://cdn.locadapt.com/locadapt.min.js" 
      data-project-id="YOUR_PROJECT_ID"
    ></script>
    <!-- note: you may also need to add `defer` to the script tag -->
  </head>
  <body>
    <div id="app"></div>
    <script type="module" src="/src/main.js"></script>
  </body>
</html>

For server-side rendered Vue applications, use the data-ssr-defer attribute:

<link rel="stylesheet" href="https://cdn.locadapt.com/locadapt.min.css" />
<script 
  src="https://cdn.locadapt.com/locadapt.min.js" 
  data-project-id="YOUR_PROJECT_ID"
  data-ssr-defer
  defer
></script>

​
Special Data Attributes

In short, special attributes are used to handle the complexities of different frontend frameworks.

You saw a few of these in the Next.js section above — copied directly from Locadapt’s site! (Our is particularly complex due to running both SSR and non-SSR versions of Locadapt, as well as an MDX blog.)

  • data-ssr-defer: Defers Locadapt initialization to the client. Use this for SSR applications. You may otherwise see hydration issues if the server returns translated content, but client generates un-translated content.
  • data-link-prevent-default: Makes Locadapt handle link clicks internally for smooth SPA transitions. If link rewriting is not working, set this.
  • data-start-hidden: Initially hides page content, revealing it after Locadapt finishes initializing. Useful for preventing flashes of untranslated content in complex applications not on the subdomain schema. We recommend setting a #locadapt-optional-loading-indicator in your HTML to show while Locadapt initializes. If you use this, you must also wrap your page content in a div with id="custom-base-content", and set its style to display: none; (it will be unset after Locadapt initializes).

Please note that due to the technical limitations of a client-side script used on a JS framework, it is not possible to avoid a flash of un-translated content on load. This is why we recommend using data-start-hidden and a loading spinner. By default, this spinner will only be around for a max of 1-2 seconds, as if new translations are required, these will be requested once the spinner is removed.

​
Example Loading Indicator

Here’s an example of a simple loading indicator you can use:

<div id="locadapt-optional-loading-indicator" class="lds-screen-container">
  <div class="lds-ring">
    <div></div>
    <div></div>
    <div></div>
    <div></div>
  </div>
</div>

And the corresponding CSS:

.lds-screen-container {
  display: flex;
  justify-content: center;
  align-items: center;
  width: 100%;
  height: 85vh;
}

.lds-ring {
  display: inline-block;
  position: relative;
  width: 30px;
  height: 30px;
}
.lds-ring div {
  box-sizing: border-box;
  display: block;
  position: absolute;
  width: 34px;
  height: 34px;
  margin: 3px;
  border: 3px solid #666;
  border-radius: 50%;
  animation: lds-ring 1.2s cubic-bezier(0.5, 0, 0.5, 1) infinite;
  border-color: #666 transparent transparent transparent;
}
.lds-ring div:nth-child(1) {
  animation-delay: -0.45s;
}
.lds-ring div:nth-child(2) {
  animation-delay: -0.3s;
}
.lds-ring div:nth-child(3) {
  animation-delay: -0.15s;
}
@keyframes lds-ring {
  0% {
    transform: rotate(0deg);
  }
  100% {
    transform: rotate(360deg);
  }
}

​
Programmatic Control

For more fine-grained control over Locadapt’s behavior in your frontend application, you can use the Locadapt JavaScript object. This allows you to programmatically update content, change languages, and more. See our API Reference for detailed information on available methods and properties.

​
General Advice

  1. Place in <head>: Add the Locadapt script in the <head> of your HTML document.
  2. Server-side Rendering (SSR): Use the data-ssr-defer attribute for (and only for) SSR applications.
  3. Single Page Applications (SPAs): For complex SPAs, consider using data-link-prevent-default to handle navigation.
  4. Dynamic Content: Locadapt’s mutation observer will handle newly added content automatically if support_dynamic_content is enabled in your project settings.

In exceptional cases, such as with very brief loading spinners, Locadapt’s mutation observer may not catch the initial content update. In this case, you can manually call window.locadapt.updateContent(); to translate the content when it has been loaded.

​
Need Help?

If you have a specific use case or need assistance with integration, please don’t hesitate to contact us at support@locadapt.com. We’re here to help you successfully implement Locadapt in your project.

SquarespaceOther Platforms