Go to conword.io

Introduction Version 2.8 / Last updated: June 2, 2026

Welcome to the Conword manual.

On this page, you'll find answers to common questions and everything you need to get Conword up and running on or your client's website.

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.

Summary:

Conword works with any CMS on any server.

Installation

To run Conword, you need to include the basic JavaScript setup, as described in the next section. Once the basic JavaScript has loaded, several functions and objects will be available.

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>

Grade

You must have a valid license for your domain in order to use Conword. If your domain is not whitelisted, Conword will not work on your website.

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
	};
</script>

<script id="conword-root" charset="utf-8" src="https://static.conword.io/js/v2/[client-id]/conword.js"></script>
Available Settings
Option Name Description Default Value Possible Values
disable_rtl_attribute Disables the rtl attribute in the <html> tag if a language with the rtl feature is used (e.g., Arabic). Conword automatically sets <html lang="rtl"> if this option is not set to false.</html></html> false true, false
disable_language_switcher If you install Conword, a dropdown menu for switching languages will appear in the bottom-left corner. Setting `disable_language_switcher` to `true` will remove the dropdown menu. false true, false

Grade

You can use Conword without the config object.

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>

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)

Starts the translation process.
This is probably the most important feature you'll need.
Note: When calling Conword.translate, Conword.set_user_language() is also called, automatically saving the language to local storage. The following example translates the current page into Spanish: 
Conword.translate('es');

Conword.retranslate()

There are some websites where content is dynamically added to the page. While Conword is aware of this and monitors the changes, sometimes issues arise and the translations need to be regenerated.
The retranslate method attempts to translate the page once again into the selected language.
If the page has not been translated before, this method will do nothing.
Example: 
Conword.retranslate();

Conword.set_user_language(language_key)

This method saves the user's language to local storage. It is automatically called when Conword.translate() is triggered.
Use this function only when you want to save the user's language without translating the page.
Once the user's language is set, Conword will automatically translate the page the next time it is loaded.
The following example sets the user language to Spanish: 
Conword.set_user_language('es');

Conword.unset_user_language()

Resets (clears) the user language settings.
Example: 
Conword.unset_user_language();

Conword.get_current_language()

This method returns the current language key (e.g., 'en', 'es', or 'fr').
Example: 
var current_langauge = Conword.get_current_language();

Conword.get_available_languages()

This method returns the JavaScript language object (see Language Object).
var language_data = Conword.get_available_languages();

Custom Events

Conword triggers custom events, which can be monitored using a custom EventLister. 
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.

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 in 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 `

The "translate" attribute

If you want certain elements to remain untranslated, you can use the translate attribute. By setting its value to "no", Conword will ignore that element and all its child elements.

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>

Note: Empty tags will be skipped automatically.

You can exclude entire pages by not loading Conword. This should be done by the programmer who integrates Conword into the website.

Examples

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:
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>
Prevent all "mailto:" links from being translated using JavaScript and the cnw_skip_translation class
document.addEventListener("DOMContentLoaded", 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 src 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>

Any questions?

Drop us a line. We're happy to help.
Send an email