go to conword.io

Introduction Version 2.8 / Last updated: September 30, 2025

Welcome to the conword manual.

On this page you will 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 frontend of conword is written in plain JavaScript, so it does not rely on any frameworks. While it is not dependent on third-party code, it works well with jQuery and other commonly used tools.

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

Summarized:

Conword works with every CMS on every server.

Installation

To run conword, you need to include the basic JavaScript setup, as given in the next section. When the basic JavaScript is loaded, several functions and objects will be available.

Basic Setup

Embed the JS code into 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>

Note

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 the Conword setup, there is a JavaScript object "conword_config" 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 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 selecting the language will appear in the bottom left corner. Setting disable_language_switcher to true will remove the dropdown menu. false true, false

Note

You can use Conword without the config object.

Example: Deactivating the standard 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 rework the conword functionality into your design, you can use the Conword JavaScript API. To use the API, you simply need to integrate conword.js into your page. See Basic Setup

API endpoint

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

API Methods

Conword.translate(language_key)

Starts the translation process.
This is probably the most important function you need.
Note: When calling Conword.translate, Conword.set_user_language() is also called, automatically saving the language in 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 well aware of that and observes the changes, sometimes there are issues and the translations need to be triggered again.
The retranslate method attempts to translate the page once again into the chosen 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 language in the local storage. It is automatically called when Conword.translate() is triggered.
Only use this function when you want to save the user's language without translating the page.
When the user language is set, Conword will translate the page automatically the next time it is loaded.
The following example sets the user storage to Spanish: 
Conword.set_user_language('es');

Conword.unset_user_language()

Removes (forgets) the user language configuration.
Example: 
Conword.unset_user_language();

Get current language

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

Get available languages

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

Custom events

Conword fires custom events, which can be listened to, by using a custom EventLister. 
document.addEventListener("Conword:ready", function(){
	/* your code here */
});

List of custom events

  • "Conword:ready" - will be fired when Conword is loaded and initialized.
  • "Conword:translation_started" - will be fired when Conword is starting to translate.
  • "Conword:translation_done" - will be fired when Conword has finished a translation.
  • "Conword:translation_failed" - will be fired 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 available 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 inputs in form fields such as and

The "translate" attribute

If you want elements not to be translated, you can make use of the translate attribute. By setting its value to "no", Conword will ignore this 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 containing 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.

Excluding entire pages can be done 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, with CSS
<style>
	body .cnw_translationbox {
		right: 30px;
		left: auto;
	}
</style>
Prevent all "mailto:" links from being translated, using js 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++){
		mailto_links[i].classList.add('cnw_skip_translation');
	}
});

Tracking

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

Example script to track 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 with 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 are happy to help.
Send to email