JavaScript und npm
Das Widget per JavaScript steuern und mit dem npm-Paket in React, Vue, Nuxt oder Next.js einbinden
Ohne Build-Schritt
Das Script aus dem Bereich Einbindung reicht:
<script src="https://a11y.pocket-rocket.io/widget.js?token=IHR_TOKEN" defer></script>Sobald das Widget läuft, steht window.RocketA11y bereit:
| Aufruf | Wirkung |
|---|---|
RocketA11y.open() | Widget öffnen |
RocketA11y.close() | Widget schließen |
RocketA11y.toggle() | öffnen oder schließen |
RocketA11y.isOpen() | true, wenn offen |
RocketA11y.openSignLanguage(thema) | das Fenster Gebärdensprache und Leichte Sprache öffnen, optional mit Thema (content, navigation, statement, offers); false, wenn die Website keine Inhalte dafür hat |
RocketA11y.languages() | die Sprachen der Sprachauswahl als Liste mit code, name (in der eigenen Sprache), label, flag (Code für /api/widget/flags/<flag>.svg, leer ohne Flagge), original (Sprache der Seite) und current; leer, wenn das Paket keine Übersetzung enthält |
RocketA11y.language() | die aktuelle Sprache, ohne Übersetzung die Sprache der Seite |
RocketA11y.setLanguage(code) | übersetzt in diese Sprache, "none" oder die Sprache der Seite zeigt das Original; false bei einer Sprache, die nicht in der Liste steht |
Ereignisse
Das Widget meldet sich am document:
| Ereignis | Wann |
|---|---|
rocket-a11y:ready | das Widget läuft |
rocket-a11y:error | das Widget startet nicht; event.detail enthält reason (token, domain, network, rate-limit, server), status und message |
rocket-a11y:open | das Widget wurde geöffnet |
rocket-a11y:close | das Widget wurde geschlossen |
rocket-a11y:language-change | die Sprache hat gewechselt; event.detail enthält language und original |
document.addEventListener("rocket-a11y:open", () => console.log("Widget offen"))
document.addEventListener("rocket-a11y:language-change", (event) => console.log(event.detail.language))Mit languages() und setLanguage() baut eine Website eine eigene Sprachauswahl, die das Widget übersetzen lässt:
document.addEventListener("rocket-a11y:ready", () => {
for (const entry of RocketA11y.languages()) {
console.log(entry.code, entry.name, entry.current)
}
RocketA11y.setLanguage("en")
})Eigene Sprachauswahl der Website
Hat die Website eine eigene Sprachauswahl oder eine eigene Leichte Sprache, kann sie diese dem Widget überlassen. Dann übersetzt das Widget nicht selbst, sondern bittet die Website darum, und beide zeigen immer dieselbe Sprache. Dafür setzt die Website zwei Attribute am <html>-Element:
| Attribut | Inhalt |
|---|---|
data-rocket-a11y-languages | die Sprachen der eigenen Auswahl, mit Leerzeichen getrennt, zum Beispiel de en ar fr it tr uk |
data-rocket-a11y-easy-language | on oder off, je nachdem, ob die eigene Leichte Sprache gerade an ist; fehlt das Attribut, macht das Widget Leichte Sprache selbst |
Wählt jemand im Widget eine dieser Sprachen oder schaltet Leichte Sprache um, meldet das Widget am document:
| Ereignis | event.detail |
|---|---|
rocket-a11y:language-request | { language: "en" } |
rocket-a11y:easy-language-request | { on: true } oder { on: false } |
Die Website wechselt dann selbst die Sprache und setzt wie gewohnt lang am <html>-Element sowie data-rocket-a11y-easy-language. Das Widget zeigt daraufhin dieselbe Sprache und denselben Zustand von Leichter Sprache. Sprachen, die nicht in der Liste stehen, übersetzt das Widget weiter selbst. Die Wahl speichert die Website, nicht das Widget.
document.documentElement.setAttribute("data-rocket-a11y-languages", "de en fr")
document.addEventListener("rocket-a11y:language-request", (event) => {
window.location.assign(`/${event.detail.language}/`)
})Andere Übersetzungswerkzeuge
Ohne data-rocket-a11y-languages erkennt das Widget verbreitete Übersetzungswerkzeuge selbst und verhält sich, als hätte die Website das Attribut gesetzt: Es zeigt deren Sprachen zuerst und übergibt sie an das Werkzeug, alle anderen Sprachen übersetzt es selbst.
| Werkzeug | Erkannt an | Wechsel der Sprache |
|---|---|---|
| Weglot | window.Weglot | Weglot.switchTo() |
| GTranslate ohne eigene Adressen | gtranslateSettings und doGTranslate() | doGTranslate() |
| TranslatePress, WPML, Polylang und jede Website mit Sprachversionen | mindestens zwei Sprachen in <link rel="alternate" hreflang="…"> | Aufruf der Adresse der Sprachversion |
Setzt die Website data-rocket-a11y-languages selbst, gilt nur das Attribut.
translate="no" und class="notranslate" an einzelnen Elementen beachtet das Widget, diese Texte bleiben unübersetzt. Am <html>- oder <body>-Element ignoriert es sie: Werkzeuge wie Weglot setzen sie dort, um die Übersetzung des Browsers abzuschalten, nicht die des Widgets. Findet das Widget auf einer Seite gar keinen übersetzbaren Text, meldet es, dass die Übersetzung nicht möglich ist, und zeigt die Seite im Original.
npm-Paket
Für Websites mit Build-Schritt gibt es das Paket @pocket-rocket/a11y. Es lädt das Widget, ist mit Server-Rendering verträglich und bringt Typen mit:
npm install @pocket-rocket/a11yimport { loadA11y } from "@pocket-rocket/a11y"
const a11y = await loadA11y({ token: "IHR_TOKEN" })
a11y.open()
a11y.on("close", () => console.log("Widget zu"))Startet das Widget nicht, lehnt loadA11y mit einem A11yLoadError ab; error.reason nennt den Grund, zum Beispiel domain, wenn die Website unter Sicherheit fehlt.
Für Server gibt es @pocket-rocket/a11y/server mit translate und simplify über die API. Es braucht einen Server-API-Schlüssel (ra11y_sk_…), der nie in den Browser gehört.
Beispiele für React, Next.js, Vue und Nuxt stehen in der README des Pakets.