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.
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.
Setup Options
If you want to configurate 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,
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
| Options 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. arbic). Conword automatically sets <html lang="rtl"> if this options is not set to false. |
false |
true, false |
| disable_language_switcher |
If you install conword, a dropdown to select switch the language will appear in the bottom left corner. Setting disable_language_switcher to true, will get rid of the the dropdown. |
false |
true, false |
| ai_notification |
Informs your visitors that the translated content has been generated by AI (available since Conword 3.3).
The notification is shown upon the first translation and only once per browser (Conword remembers this in the local storage).
false: no notification (default, also if the option is missing).
"top": a dismissable notification bar is inserted at the top of the page. It stays visible while scrolling until the visitor closes it.
"modal": a modal dialog is opened, which the visitor has to confirm.
The notification text is inserted in the source language of your site (German or English, other source languages get the English text) right before the translation starts, so it is translated by Conword into the chosen language together with the rest of the page. It mentions the original language of your site. See AI Notification. |
false |
false, "top", "modal" |
| skip_classes |
Additional html classes that exclude an element and all its children from the translation, exactly like the built-in class "cnw_skip_translation" (see Excluding Content). Useful if your CMS already marks such content with its own class, e.g. "no-translate" or "legal-text".
Pass a single class as a string, several classes as an array, or a space separated string. |
[] |
"my-class", ["class-a", "class-b"], "class-a class-b" |
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>
AI Notification
Some websites are required to inform their visitors, that the content they are reading has been generated by AI. With the ai_notification option, Conword shows such a notification automatically, when the page gets translated for the first time.
The notification is shown once per browser (Conword remembers this in the local storage). The text is inserted in the source language of your site (German or English, other source languages get the English text) right before the translation starts, so it is translated together with the rest of the page. It mentions the original language of your site.
Option values
- false – no notification. This is the default, also if the option is missing in your config.
- "top" – a dismissable notification bar is inserted at the top of the page. It sticks to the top of the viewport while scrolling, until the visitor closes it.
- "modal" – a modal dialog is opened, which the visitor has to confirm.
Notification bar at the top of the page
The visitor can close the bar with 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 dialog has to be confirmed by the visitor:
<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>
Showing the notification again
If you want to show the notification again (e.g. on a "more information" link), use Conword.show_ai_notification(). The event "Conword:ai_notification_shown" is fired whenever the notification is shown.
Styling
The notification bar has the id "cnw_ai_notification", the modal dialog the id "cnw-ai-dialog". Both carry the class "cnw_ai_notification", so you can adjust the look with your own css.
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.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.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();
Conword.show_ai_notification(mode)
Shows the AI notification (see the ai_notification option in Setup Options) right away, no matter if it has already been shown before or if the option is set at all.
The optional parameter mode can be "top" or "modal". If it is omitted, the mode from your conword_config is used ("top" if the option is not set).
The notification text (German or English, depending on the source language of your site) is inserted into the page. If the page is already translated, Conword translates the notification into the current language as well.
Example:
Conword.show_ai_notification('modal');
Conword.close_ai_notification()
Closes the AI notification bar or the AI notification modal, if one is currently shown.
Example:
Conword.close_ai_notification();
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 an translation attempt failed.
- "Conword:ai_notification_shown" - will be fired when the AI notification (see the ai_notification option) has been shown.
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_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 like <input> and <textarea> will be ignored by Conword. Labels and placeholder attributes will be translated, tho.
Since Conword can not know, when user data is shown, you may want to exclude this html from translations by Conword. So if you have a summary of the form input at the end of your form, you need to make use of the following method:
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>
The "data-conword-skip-translation" attribute
A data attribute without a value. Conword will skip the element and all its children, just like with the class above. Handy if you don't want to touch the classes of an element.
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 have to add "cnw_skip_translation" everywhere. List your classes in the skip_classes option instead (see Setup Options). Elements with one of these classes, and all their children, are treated exactly like 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 class "notranslate" is recognized as well. Scripts, stylesheets, svg content, images, noscript and textarea elements are always skipped. User input in form fields is never translated, labels and placeholders are.
Note: Empty Tags will be skipped automatically.
Excluding whole pages can be done, by not loading conword or using the conword.lock() function, which is available in newer conword versions.
Examples
Dynamically excluding content with the classname ".formular_zusammenfassung"
Use the "Conword:ready" event for this kind of marking: it is fired right before a saved user language triggers the automatic translation, so the class is in place in time. "DOMContentLoaded" can 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 to english
<a href="javascript:Conword.translate('en');">Translate to english</a>
Custom integration of Conword to your page:
Three complete language switchers (links, select, 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, with css
<style>
body .cnw_translationbox {
right: 30px;
left: auto;
}
</style>
More positions and colour schemes for the default switcher, applied live: demo: restyling the default language switcher.
Prevent all "mailto:" links from being translated, using js 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');
}
});
Show different images (or other content) for each language
For localization reasons, you might want to switch content on your website, when changing the language.
There are several ways to control this: e.g. via 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 to languages changes and replaces the image src to the attribute value.
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
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>
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.
