Introduction Version 2.0.4 / Last updated: 6. February 2024

Welcome to the conword manual.

On this page you will find answers to common questions and everything you need in order to get conword up and running on your or your client's website.

Available languages

The list of currently available languages and its languagecodes ('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.

Summarised:

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 to 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 licence for your domain in order to use conword. If your domain is not whitelisted, conword will not work on your website.

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 must simply integrate the 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 called as well, saving the language automatically in the local storage. The following example translates the current page to 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 tries 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 into the localstorage. 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.
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()

Unsets (forgets) the user language config.
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 return 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.

Language Object

The Conword API provides an object which contains all the available languages and their metadata. The object can be retrieved like this:

let languages=Conword.get_available_languages();

The object looks like this:

(Depending on the languages available with your licence.)


{
    "de": {
        "name_en": "German",
        "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": "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": "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": "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."
    }
}

Examples

Example: HTML Link to start translating the page to english


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

Custom integration of Conword to 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;

	}
});

Excluding Content

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</p>
	I will be translated as well
</div>

Note: Empty Tags will be skipped automatically.

Excluding whole pages can be done, by not loading conword. This should be done by the programmer, who integrates conword into the website.

Tracking

In order 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>