Documentation

Getting Started

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
});

Configuration Options

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.

Language Detection

LíngAwesome can automatically detect the language to use in several ways:

1. Query String: If the URL contains a query parameter ljs, LíngAwesome will use its value as the language code.

https://example.com?ljs=fr

2. Script Tag Attribute: If the script tag that includes LíngAwesome has a 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>

3. Initialization Option: The language can be explicitly set through the init function's language option.

window.lingAwesome.init({
    apiKey: "YOUR_API_KEY_HERE",
    language: 'de'
});

4. Browser Language: If none of the above are set, LíngAwesome will fall back to the browser's default language.

languageCode = navigator.language || navigator.userLanguage || "en";

API Methods

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);
    }
});

Observer for Dynamic Content

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

Example Usage

Marking Up HTML with Language Tokens

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>

Full Page Example

<!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>

Additional Features

Refresh the Whole Page

window.lingAwesome.refreshDocument();

---

Refresh a Specific Element

const element = document.getElementById("myElement");
window.lingAwesome.refreshDocument(element);

---

Change Language on the Page

window.lingAwesome.setLanguage('fr'); // Change to French

---

Dynamic Language Display

<p class="text-muted"><small>(<span ta-kit-language></span>)</small></p>