LíngAwesome: Comprehensive Guide for Developers
Include the LíngAwesome script in your HTML file. Place this before the closing </body>
tag.
<script src="https://www.lingawesome.com/cdn/script/lingAwesome-1-1.min.js"></script>
Initialize the toolkit with the API key we emailed to you and your desired language. Ensure you replace "YOUR_API_KEY_HERE" with the API key from the email.
window.lingAwesome.init({
apiKey: "YOUR_API_KEY_HERE",
language: 'en',
autoTranslate: true, // Automatically translate the entire page on load
});
Here are the available options you can pass to the init
function:
apiKey
(required): Your API key for accessing LíngAwesome.language
(optional, default: browser's language): The initial language for the translations.base
(optional, default: "en"): The base language code to use as a fallback if the translation is not available.observe
(optional, default: true): Whether to automatically observe the DOM for changes and update translations.autoTranslate
(optional, default: true): Whether to automatically translate the entire page on load.storagePrefix
(optional, default: "lingAwesome"): The prefix used for storing language toolkits in the browser's local storage.tokenAttribute
(optional, default: "ta-kit"): The attribute name used to identify translation tokens in the HTML elements.onLangChange
(optional): Callback function for language change events.LíngAwesome can automatically detect the language to use in several ways:
ljs
, LíngAwesome will use its value as the language code.https://example.com?ljs=fr
ta-lang
attribute, LíngAwesome will use its value as the language code.<script id="lingAwesomejs" src="https://www.lingawesome.com/cdn/script/lingAwesome-1-1.min.js" ta-lang="es"></script>
init
function's language
option.window.lingAwesome.init({
apiKey: "YOUR_API_KEY_HERE",
language: 'de'
});
languageCode = navigator.language || navigator.userLanguage || "en";
window.lingAwesome.init(options)
Initializes the LíngAwesome toolkit with the specified options.
window.lingAwesome.translateDocument(node)
Translates the entire document or a specific node.
window.lingAwesome.translateDocument(); // Translates the entire document
const element = document.getElementById("myElement");
window.lingAwesome.translateDocument(element); // Translates a specific element
window.lingAwesome.refreshDocument(node)
Refreshes the translations for the entire document or a specific node.
window.lingAwesome.refreshDocument(); // Refreshes the entire document
const element = document.getElementById("myElement");
window.lingAwesome.refreshDocument(element); // Refreshes a specific element
window.lingAwesome.setLanguage(langCode)
Sets the current language and translates the document.
window.lingAwesome.setLanguage('fr'); // Changes the language to French
window.lingAwesome.getLanguage()
Returns the current language code.
const currentLanguage = window.lingAwesome.getLanguage(); // Gets the current language code
window.lingAwesome.register(email, callback)
Registers an API key using an email address.
window.lingAwesome.register("[email protected]", function(error, data) {
if (error) {
console.error("Error registering API key:", error.message);
} else {
console.log("API Key:", data.apiKey);
}
});
LíngAwesome can automatically observe the DOM for changes and update translations when new elements are added or modified. This feature is controlled by the observe
option, which is true
by default.
Example: Using the Observer
Enable the observer by setting the observe
option to true
(default behavior). Add new translatable content dynamically to the DOM.
window.lingAwesome.init({
apiKey: "YOUR_API_KEY_HERE",
language: 'en',
observe: true // Automatically observe and translate new content
});
// Dynamically adding a new translatable element
const newElement = document.createElement('h5');
newElement.setAttribute('ta-kit', 'dynamic-content');
newElement.innerText = 'Dynamic Content';
document.body.appendChild(newElement);
// LíngAwesome will automatically translate the new element
Mark up your HTML elements with LíngAwesome language tokens to make them translatable. Explore the language kit of over 600 tokens.
<h5 class="m-b-4" ta-kit="hello-world">Hello World</h5>
<h5 class="m-b-4" ta-kit="welcome">Welcome</h5>
<h5 class="m-b-4" ta-kit="welcome-back">Welcome Back</h5>
<p class="text-muted"><small>(<span ta-kit-language></span>)</small></p>
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>LingAwesome Example</title>
</head>
<body>
<h5 class="m-b-4" ta-kit="hello-world">Hello World</h5>
<h5 class="m-b-4" ta-kit="welcome">Welcome</h5>
<h5 class="m-b-4" ta-kit="welcome-back">Welcome Back</h5>
<p class="text-muted"><small>(<span ta-kit-language></span>)</small></p>
<div class="mb-2">
<button class="btn btn-light btn-sm" ta-kit-select="en" lang="en">English</button>
<button class="btn btn-light btn-sm" ta-kit-select="pt" lang="pt">Portuguese</button>
<button class="btn btn-light btn-sm" ta-kit-select="fr" lang="fr">French</button>
<button class="btn btn-light btn-sm" ta-kit-select="es" lang="es">Spanish</button>
<!-- Add more buttons as needed -->
</div>
<script src="https://www.lingawesome.com/cdn/script/lingAwesome-1-1.min.js"></script>
<script>
window.lingAwesome.init({
apiKey: "YOUR_API_KEY_HERE",
language: 'en',
autoTranslate: true, // Automatically translate the entire page on load
});
</script>
</body>
</html>
window.lingAwesome.refreshDocument();
const element = document.getElementById("myElement");
window.lingAwesome.refreshDocument(element);
window.lingAwesome.setLanguage('fr'); // Change to French
<p class="text-muted"><small>(<span ta-kit-language></span>)</small></p>