Available languages

The list of currently available languages and their language codes ("en," "fr," "de," ...) can be found here: https://conword.io/sprachen/

Prerequisites

The front end of Conword is written in plain JavaScript, so it does not rely on any frameworks. Although it does not depend on third-party code, it works well with jQuery and other commonly used tools.

Conword provides real-time translations without storing any data on the client's server. This makes Conword independent of the underlying CMS.

Basic Setup

Embed the JavaScript code in your HTML

Conword works on your website with this single line of code:

<script id="conword-root" charset="utf-8" src="https://static.conword.io/js/v2/[client-id]/conword.js"></script>

Setup Options

If you want to configure Conword, there is a JavaScript object called "conword_config" that you can use to pass your settings to the Conword instance.

Conword works on your website with this single line of code:

<script>
	var conword_config={
		disable_rtl_attribute:false,
		disable_language_switcher:false,
		ai_notification:false,
		skip_classes:[]
	};
</script>

<script id="conword-root" charset="utf-8" src="https://static.conword.io/js/v2/[client-id]/conword.js"></script>

Available Settings

Example: Disabling the default language switcher widget

<script>
	var conword_config={
		disable_language_switcher:true
	};
</script>

<script id="conword-root" charset="utf-8" src="https://static.conword.io/js/v2/[client-id]/conword.js"></script>

AI Notification

Some websites are required to inform their visitors that the content they are reading was generated by AI. With the ai_notification option, Conword automatically displays such a notification when the page is translated for the first time.

The notification is displayed once per browser (Conword stores this in local storage). The text is inserted in your site's source language (German or English; other source languages display the English text) right before the translation begins, so it is translated along with the rest of the page. It specifies your site's original language.

Option values

• false – no notification. This is the default, even if the option is missing from your configuration.
• "top" – A dismissible notification bar is inserted at the top of the page. It remains at the top of the viewport while the user scrolls, until the visitor closes it.
• "modal" – A modal dialog box opens, which the visitor must confirm.

Notification bar at the top of the page

The visitor can close the bar by clicking the "✕":

<script>
	var conword_config={
		ai_notification:"top"
	};
</script>

<script id="conword-root" charset="utf-8" src="https://static.conword.io/js/v2/[client-id]/conword.js"></script>

Modal dialog

The visitor must confirm the dialog:

<script>
	var conword_config={
		ai_notification:"modal"
	};
</script>

<script id="conword-root" charset="utf-8" src="https://static.conword.io/js/v2/[client-id]/conword.js"></script>

Displaying the notification again

If you want to display the notification again (e.g., on a "more information" link), use Conword.show_ai_notification(). The "Conword:ai_notification_shown" event is triggered whenever the notification is displayed.

Styling

The notification bar has the ID "cnw_ai_notification," and the modal dialog has the ID "cnw-ai-dialog." Both have the class "cnw_ai_notification," so you can customize their appearance using your own CSS.

Conword JavaScript API

If you want to incorporate Conword functionality into your design, you can use the Conword JavaScript API. To use the API, simply include the conword.js file on your page. See Basic Setup

API Endpoint

You can use the "Conword" JavaScript object to call API methods.
See the section below for more information.

API Methods

Conword.translate(language_key)

Conword.translate('es');

Conword.retranslate()

Conword.retranslate();

Conword.set_user_language(language_key)

Conword.set_user_language('es');

Conword.unset_user_language()

Conword.unset_user_language();

Conword.get_current_language()

var current_langauge = Conword.get_current_language();

Conword.get_available_languages()

var language_data = Conword.get_available_languages();

Conword.show_ai_notification(mode)

Conword.show_ai_notification('modal');

Conword.close_ai_notification()

Conword.close_ai_notification();

Custom Events

document.addEventListener("Conword:ready", function(){
	/* your code here */
});

List of Custom Events

• "Conword:ready" - will be triggered when Conword is loaded and initialized.
• "Conword:translation_started" - will be triggered when Conword begins translating.
• "Conword:translation_done" - will be triggered when Conword has finished a translation.
• "Conword:translation_failed" - will be triggered when a translation attempt fails.
• "Conword:ai_notification_shown" - will be triggered when the AI notification (see the ai_notification option) has been displayed.

Language Object

The Conword API provides an object that contains all available languages and their metadata. The object can be retrieved as follows:

let languages=Conword.get_available_languages();

The object looks like this:

(Depending on the languages included with your license.)

{
    "de": {
        "name_en": "German",
        "name_de": "Deutsch",
        "name": "Deutsch",
        "rtl": false,
        "text_title": "Sprache wählen:",
        "text_1": "Die Seite wird gerade übersetzt …",
        "text_2": "Einen Moment bitte.",
        "text_error": "Beim Übersetzen der Seite ist ein Fehler ist aufgetreten."
    },
    "en": {
        "name_en": "English",
        "name_de": "Englisch",
        "name": "English",
        "rtl": false,
        "text_title": "Select language:",
        "text_1": "The page is being translated ...",
        "text_2": "One moment please.",
        "text_error": "An error occurred while translating the page."
    },
    "tr": {
        "name_en": "Turkish",
        "name_de": "Türkisch",
        "name": "Türkçe",
        "rtl": false,
        "text_title": "Dil seçin:",
        "text_1": "Sayfa çevriliyor ...",
        "text_2": "Bir dakika lütfen.",
        "text_error": "Sayfa çevrilirken bir hata oluştu."
    },
    "it": {
        "name_en": "Italian",
        "name_de": "Italienisch",
        "name": "Italiano",
        "rtl": false,
        "text_title": "Selezionare la lingua:",
        "text_1": "La pagina è in corso di traduzione ...",
        "text_2": "Un momento, per favore.",
        "text_error": "Si è verificato un errore durante la traduzione della pagina."
    }
}
  					

Excluding Content

Forms

User input in form fields such as and will be ignored by Conword.</strong> Labels and placeholder attributes will be translated, however.<br> Since Conword cannot determine when user data is displayed, you may want to exclude this HTML from Conword's translations. So if you have a summary of the form input at the end of your form, you need to use the following method:

The "translate" attribute

If you want certain elements not to be translated, you can use the translate attribute. By setting its value to "no," Conword will ignore that element and all its children.

Example:

<div>
	<p>I will be translated</p>
	<p translate="no">
		I will NOT be translated.
		<small>Me neither, since my parent element uses the transate attrube.</small>
	</p>
	I will be translated as well
</div>

The "cnw_skip_translation" class

Conword will skip all HTML tags that contain the "cnw_skip_translation" class.

Example:

<div>
	<p>I will be translated</p>
	<p class="cnw_skip_translation">
		I will NOT be translated.
		<small>Me neither, since my parent element uses the cnw_skip_translation class.</small>
	</p>
	I will be translated as well
</div>

The "data-conword-skip-translation" attribute

A data attribute without a value. Conword will skip the element and all its children, just as it does with the class above. This is useful if you don't want to modify an element's classes.

Example:

<div>
	<p>I will be translated</p>
	<p data-conword-skip-translation>
		I will NOT be translated.
		<small>Me neither, since my parent element uses the data-conword-skip-translation attribute.</small>
	</p>
</div>

Your own classes: the "skip_classes" option

If your CMS or template already marks content that must not be translated with its own class, you don't need to add "cnw_skip_translation" everywhere. Instead, list your classes in the skip_classes option (see Setup Options). Elements with one of these classes, and all their children, are treated exactly the same as elements with "cnw_skip_translation".

Example:

<script>
	var conword_config={
		skip_classes:["no-translate", "legal-text"]
	};
</script>

<script id="conword-root" charset="utf-8" src="https://static.conword.io/js/v2/[client-id]/conword.js"></script>

<div>
	<p>I will be translated</p>
	<p class="legal-text">
		I will NOT be translated.
		<small>Me neither, since my parent element uses one of the configured classes.</small>
	</p>
</div>

Other ways

The "notranslate" class is also recognized. Scripts, stylesheets, SVG content, images, `noscript` elements, and `textarea` elements are always skipped. User input in form fields is never translated, but labels and placeholders are.

Note: Empty tags will be skipped automatically.

You can exclude entire pages by not loading Conword or by using the conword.lock() function, which is available in newer versions of Conword.

Examples

Dynamically excluding content with the class name ".formular_zusammenfassung"

Use the "Conword:ready" event for this type of marking: it is triggered right before a saved user language triggers the automatic translation, so the class is in place in time. "DOMContentLoaded" may be too late, because Conword itself starts on that event.

document.addEventListener("Conword:ready", function() {
	var formular_zusammenfassungen = document.querySelectorAll('.formular_zusammenfassung');
	for(var i = 0; i < formular_zusammenfassungen.length; i++){
		formular_zusammenfassungen[i].classList.add('cnw_skip_translation');
	}
});

Example: HTML link to start translating the page into English

<a href="javascript:Conword.translate('en');">Translate to english</a>
						

Custom integration of Conword into your page:

Three complete language switchers (links, dropdown menus, buttons with flags), live and with code: demo: building your own language switcher.

document.addEventListener("Conword:ready", function(){
	my_languages=Conword.get_available_languages();
	for (var langkey in my_languages) {

		language_meta=my_languages[langkey];

		// now you can make use of the language object - see the chapter above.
		// eg:  language_meta.name or language_meta.name_en ...
		console.debug(language_meta.name,language_meta.name_en);

		// to check if the langkey is the currently active language:
		active=false;
		if(Conword.get_current_language()==langkey) active=true;

		// jquery example of adding menu items
		$language_dropdown.append('<li><a class="'+active+'" href="javascript:start_conwordio_translation(\''+langkey+'\');" data-lang="'+langkey+'" data-langname="'+language_meta.name+'" title="Diese Seite auf \''+language_meta.name+'\' übersetzen">'+language_meta.name+'</a></li>');

	}
});

// example of a wrapper to call multiple actions (translation, menu controls, tracking, ...) at the same time
function start_conwordio_translation(lang){
	Conword.translate(lang);
	hide_menu();
	matomo_track('Translation',lang);
}

Moving the default language switch to the right using CSS

<style>
	body .cnw_translationbox {
		right: 30px;
		left: auto;
	}
</style>

More positions and color schemes for the default switcher, applied in real time: demo: restyling the default language switcher.

Prevent all "mailto:" links from being translated using JavaScript and the cnw_skip_translation class

document.addEventListener("Conword:ready", function() {
	var mailto_links = document.querySelectorAll('a[href^="mailto:"]');
	for(var i = 0; i < mailto_links.length; i++){
		if(mailto_links[i].innerHTML.indexOf('@')>-1) mailto_links[i].classList.add('cnw_skip_translation');
	}
});

Display different images (or other content) for each language

For localization purposes, you may want to switch the content on your website when changing the language.
There are several ways to do this, such as using HTML attributes. Here is an example of how to switch images.

First, create an image with data attributes like this:

<img src="bild_de.jpg" data-conword-src-de="bild_de.jpg" data-conword-src-en="image_en.jpg" data-conword-src-fr="fr.jpg" class="image_with_different_sources">

The JavaScript listens for language changes and replaces the image's `src` attribute with the value of the attribute.

document.addEventListener("Conword:translation_done", function(){
	current_language=Conword.get_current_language();
	images_with_different_sources = document.querySelectorAll('.image_with_different_sources'); // or select [data-conword-src-de]
	images_with_different_sources= [...images_with_different_sources]; // convert list to array
	images_with_different_sources.forEach(img => {
		img.src=img.getAttribute('data-conword-src-'+current_language); // change src
	});
});

Tracking

To track Conword requests, we recommend wrapping the JavaScript translation call.

Example script for tracking translations with Matomo (Piwik):

<a href="javascript:custom_start_translation('en');">English</a>

<script>

	function custom_start_translation(languagekey){
		Conword.translate(language);
		matomo_track( 'Translation '+languagekey, location.href);

	}

	function matomo_track(category,action){
		if(typeof _paq !== 'undefined') {
			_paq.push(['trackEvent', category, action, 1]);
			return true;
		}
		return false
	}

</script>

Alternatively, tracking can be done using Conword's custom events.
Here is an example of how to track Conword translations with Piwik (Matomo):

<script>

	function matomo_track(category,action){
		if(typeof _paq !== 'undefined') {
			_paq.push(['trackEvent', category, action, 1]);
			return true;
		}
		return false
	}

	document.addEventListener("Conword:translation_started", function(){
		matomo_track( 'Translation '+Conword.get_current_language(), location.href);
	});

</script>

The following example shows how to track Conword translations using Google Analytics:

<script>

	document.addEventListener("Conword:translation_started", function(){
		gtag('event', 'translation', {
			'url': location.href,
			'language': Conword.get_current_language()
		});
	});

</script>