Documentation Index
Fetch the complete documentation index at: https://docs.locadapt.com/llms.txt
Use this file to discover all available pages before exploring further.
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>
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>
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>
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>
.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
- Place in
<head>: Add the Locadapt script in the <head> of your HTML document.
- Server-side Rendering (SSR): Use the
data-ssr-defer attribute for (and only for) SSR applications.
- Single Page Applications (SPAs): For complex SPAs, consider using
data-link-prevent-default to handle navigation.
- 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.
