Widget reference

Everything you need to add translation to a website, customize the language switcher and control what gets translated.

Installation

Add your website in the dashboard, then paste its snippet into the <head> of every page, ideally near the top:

<script src="https://alinio.app/widget.js" data-key="YOUR_SITE_KEY"></script>

Loading the script in the <head> without defer lets returning visitors see their language before the page is first painted. The script is small and cached by the browser. If you prefer, defer or async work as well; the page is then briefly shown in its original language.

Plugins for WordPress, Drupal and other systems

With a plugin you need no snippet. Copy the secret key from the Plugins box of your website in the dashboard into the plugin settings. The plugin brings its own copy of the widget and asks alinio from your web server, so the key never appears in your pages and the browsers of your visitors never connect to alinio. Your server sends the page text, the page path and the language. No IP address, browser data or cookies of your visitors reach alinio.

Step by step: set up alinio in WordPress.

Keep the secret key private: it works from any server, the allowed domains do not apply to it. If it got out, create a new one in the website settings and enter it in the plugin.

Other systems connect the same way. Your server sends Authorization: Bearer YOUR_SECRET_KEY to https://alinio.app/api/v1/server/config, /api/v1/server/translations/{lang}?path=… and /api/v1/server/translate/{lang}, and serves the widget with data-endpoint instead of data-key. The widget then calls this endpoint with ?op=config, ?op=translations&lang=…&path=… and ?op=translate&lang=….

Options

Configure the widget with attributes on the script tag:

AttributeValuesPurpose
data-keyyour site keyRequired. Identifies your website.
data-positionbottom-right, bottom-left, top-right, top-left, inline, noneWhere the switcher appears. Overrides the dashboard setting. none hides it, for example when you build your own.
data-containerCSS selectorRenders the switcher inside this element instead of floating, e.g. #language. An element with the class website-translator is used automatically.
data-de, data-fr, …URLYou already have a separate website for this language: visitors who pick it are sent there instead of translating in place, e.g. data-de="https://www.example.de/".

Links can open a page in a specific language with the parameter alinio_lang, e.g. https://www.example.com/?alinio_lang=fr. The parameter is removed from the address bar and the choice is remembered.

Your own language buttons

Any element with a data-alinio-lang attribute becomes a language button. An empty value switches back to the original language. The attribute aria-pressed is kept up to date for styling.

<button type="button" data-alinio-lang="de">Deutsch</button>
<button type="button" data-alinio-lang="fr">Français</button>
<button type="button" data-alinio-lang="">English</button>

Simplified language

Every language, including the original language of your website, can also be offered in two simplified versions for readers who find the original hard to understand. Choose them in the Plain Language and Easy Read tabs of your website settings; each counts as a language of your plan.

VersionCodeFor
Plain Languagede-x-plain, en-x-plain, …Everyone: short sentences, everyday words, technical terms explained. All information is kept.
Easy Readde-x-easy, en-x-easy, …People with learning difficulties or very little knowledge of the language: one statement per sentence, the simplest words, difficult words explained. You can have these texts reviewed at any time, for example by readers of the target group, and correct them in the translation editor.

The codes work everywhere a language code does, for example for a link in your site header:

<button type="button" data-alinio-lang="en-x-easy">Easy Read</button>

Automatic language detection never picks a simplified version; visitors choose it themselves.

Keeping content untranslated

Mark elements with the standard translate="no" attribute or the class notranslate. Code blocks, form fields, scripts and styles are never translated. Brand names and other terms can also be listed as do-not-translate terms in your website settings (under Advanced); they are kept as they are everywhere.

Numbers, dates and times at the end of a text are not translated: Expires in 20:33 is translated once as Expires in, and the value your page currently shows stays after it, however often it changes. Numbers elsewhere in a text are part of its translation; mark them with translate="no" if they change.

JavaScript API

The widget exposes window.alinio:

alinio.setLanguage('fr')Translate the page into a language enabled for your site.
alinio.restore()Show the original language again.
alinio.languageThe current language code, or null for the original.
alinio.refresh()Translate content you inserted without triggering DOM mutations (rarely needed).

Events are dispatched on document: alinio:change when the language changes and alinio:status with detail.state busy, done or error.

Content Security Policy

If your website sends a Content-Security-Policy header, allow the script and its API requests:

script-src … https://alinio.app;
connect-src … https://alinio.app;

Allowed domains

New translations are only produced for requests coming from the domains listed in your website settings. Add every domain that serves your pages, including staging domains. *.example.com allows all subdomains. Plugins use the secret key instead, which is not bound to these domains.

New texts are also checked against your page. Before a text is translated for the first time, alinio fetches the page from your website (user agent alinio-pagecheck) and translates only the texts it finds in the HTML. This keeps others from using your site key for texts of their own. Texts that JavaScript adds after loading are not in that HTML. alinio translates them as well when they belong to the page: when the rest of the page matches the HTML, or when it finds them in the scripts your website delivers with the page. For such texts there is a daily amount of new text per page and per website, so a large website that builds its pages with JavaScript can take a few days until every text is translated. Pages behind a login cannot be fetched. For those, or if you need everything at once, use a plugin or the server API, or write to us and we turn the check off for your website. If a firewall or bot protection blocks unknown clients, allow the user agent alinio-pagecheck.

Privacy policy

Visitors must be told what the language switcher transmits and stores. Copy this section into your privacy policy. It is a template, not legal advice. Adjust it to your website.

English
<h3>Website translation with alinio</h3>
<p>This website uses the translation service <a href="https://alinio.app">alinio</a>. When you open a page, your browser loads the alinio script and the language settings of this website from the servers of alinio; as with every request to a web server, your IP address and technical request data (time, requested address, browser type) are transmitted. When a language is selected (by you, or automatically based on your browser's language settings), the page text, the page path and the selected language are also transmitted. alinio sets no cookies and creates no user profiles.</p>
<p>The language switcher stores its settings, the selected language and translations in the local storage of your browser. This is strictly necessary for the language selection; you can delete the data at any time in your browser settings.</p>
<p>We use alinio based on our legitimate interest in making our website available to visitors in their language (Art. 6 (1) (f) GDPR). alinio processes the data on our behalf (Art. 28 GDPR). More information: <a href="https://alinio.app/privacy">privacy policy of alinio</a>.</p>
Deutsch
<h3>Übersetzung der Website mit alinio</h3>
<p>Diese Website nutzt den Übersetzungsdienst <a href="https://alinio.de">alinio</a>. Beim Aufruf einer Seite lädt Ihr Browser das Skript von alinio und die Spracheinstellungen dieser Website von den Servern von alinio; wie bei jedem Abruf eines Webservers werden dabei Ihre IP-Adresse und technische Daten der Anfrage (Zeitpunkt, abgerufene Adresse, Browsertyp) übertragen. Wird eine Sprache ausgewählt (von Ihnen oder automatisch anhand der Spracheinstellungen Ihres Browsers), werden zusätzlich der Seitentext, der Pfad der Seite und die gewählte Sprache übermittelt. alinio setzt keine Cookies und erstellt keine Nutzerprofile.</p>
<p>Der Sprachumschalter speichert seine Einstellungen, die gewählte Sprache und Übersetzungen im lokalen Speicher (Local Storage) Ihres Browsers. Das ist für die Sprachauswahl unbedingt erforderlich (§ 25 Abs. 2 Nr. 2 TDDDG); Sie können die Daten jederzeit in den Einstellungen Ihres Browsers löschen.</p>
<p>Rechtsgrundlage ist unser berechtigtes Interesse, unsere Website Besucherinnen und Besuchern in ihrer Sprache zugänglich zu machen (Art. 6 Abs. 1 lit. f DSGVO). alinio verarbeitet die Daten in unserem Auftrag (Art. 28 DSGVO). Weitere Informationen: <a href="https://alinio.de/privacy">Datenschutzerklärung von alinio</a>.</p>
English, with a plugin
<h3>Website translation with alinio</h3>
<p>This website uses the translation service <a href="https://alinio.app">alinio</a>. When a language is selected (by you, or automatically based on your browser's language settings), our web server sends the page text, the page path and the selected language to alinio and receives the translations. Your browser does not connect to alinio: your IP address and the data of your browser are not transmitted to alinio. alinio sets no cookies and creates no user profiles.</p>
<p>The language switcher stores its settings, the selected language and translations in the local storage of your browser. This is strictly necessary for the language selection; you can delete the data at any time in your browser settings.</p>
<p>We use alinio based on our legitimate interest in making our website available to visitors in their language (Art. 6 (1) (f) GDPR). alinio processes the data on our behalf (Art. 28 GDPR). More information: <a href="https://alinio.app/privacy">privacy policy of alinio</a>.</p>
Deutsch, with a plugin
<h3>Übersetzung der Website mit alinio</h3>
<p>Diese Website nutzt den Übersetzungsdienst <a href="https://alinio.de">alinio</a>. Wird eine Sprache ausgewählt (von Ihnen oder automatisch anhand der Spracheinstellungen Ihres Browsers), sendet unser Webserver den Seitentext, den Pfad der Seite und die gewählte Sprache an alinio und erhält die Übersetzungen zurück. Ihr Browser verbindet sich nicht mit alinio: Ihre IP-Adresse und die Daten Ihres Browsers werden nicht an alinio übertragen. alinio setzt keine Cookies und erstellt keine Nutzerprofile.</p>
<p>Der Sprachumschalter speichert seine Einstellungen, die gewählte Sprache und Übersetzungen im lokalen Speicher (Local Storage) Ihres Browsers. Das ist für die Sprachauswahl unbedingt erforderlich (§ 25 Abs. 2 Nr. 2 TDDDG); Sie können die Daten jederzeit in den Einstellungen Ihres Browsers löschen.</p>
<p>Rechtsgrundlage ist unser berechtigtes Interesse, unsere Website Besucherinnen und Besuchern in ihrer Sprache zugänglich zu machen (Art. 6 Abs. 1 lit. f DSGVO). alinio verarbeitet die Daten in unserem Auftrag (Art. 28 DSGVO). Weitere Informationen: <a href="https://alinio.de/privacy">Datenschutzerklärung von alinio</a>.</p>

Search engines

Translations are applied in the browser, so search engines index your original language. Use a dedicated multilingual setup if translated pages must rank in search results.

Support

Questions or problems? Write to us.