Hooks für Plugins und Themes

Dokumentation / Entwickler

Die Hooks, die SwiftLing anderen Plugins und Themes bietet. SwiftLing Pro baut ausschließlich auf ihnen auf: Es verändert SwiftLing selbst nicht.

SWIFTLING_HOOKS ist die Versionsnummer dieser Liste. Sie steigt, wenn ein Hook hinzugefügt oder geändert wird. So kann ein Plugin prüfen, ob SwiftLing alles bietet, was es benötigt:

if ( ! defined( 'SWIFTLING_HOOKS' ) || SWIFTLING_HOOKS < 1 ) {
	return; // Too old a SwiftLing.
}

tests/HooksTest.php schlägt fehl, wenn ein Hook zu SwiftLing hinzugefügt wird, ohne hier beschrieben zu sein, oder wenn er hier beschrieben ist, aber in SwiftLing fehlt.

Verwaltungsseiten

swiftling_admin_screens

Filter, seit Hooks-Version 1. Die Verwaltungsseiten von SwiftLing, nach dem Slug ihrer Adresse (admin.php?page=<slug>) und in Menüreihenfolge geordnet. Ein Plugin kann eine Seite zum Menü oder zu einer Gruppe hinzufügen; siehe swiftling_admin_groups.

Key
menu	Name: the screen’s title, its menu item, and its name in the list of its group. Required.
view	A name for the screen, unique among the screens. Required.
file	Path of the PHP file that prints the screen. Without it, admin/views/<view>.php of SwiftLing.
group	A group of swiftling_admin_groups: the screen is out of the menu, unless it is the group’s first, and shows the group’s header and list.
part	The part of the group’s list the screen is listed in. Without it, the screen is in the group but not listed.
icon, tint	The screen’s picture in the list: the path of a 16 by 16 line drawing, on a tile of orange, blue, green, teal, amber, violet or ink.
hidden	Reachable only by link, never in the menu.
count	Since hooks 25: a number to show beside the screen’s menu item, as WordPress shows pending comments, such as replies waiting to be read. A screen of a group adds it to the group’s item; SwiftLing’s own item shows the sum of all, so it is seen with the menu closed. 0 shows nothing.
cap	Since hooks 12: the capability the screen takes; without it, manage_options. The Translations screens and the translation editor take swiftling_translate, see swiftling_can_translate. The menu and the list of a group show a user only the screens they may open.
before_setup	Since hooks 20: the screen opens before the first setup is answered, as an import that sets the languages up from another plugin’s (swiftling_import_languages()). Until then every other screen leads to the first setup.

Die Datei gibt die Seite innerhalb der SwiftLing-Seite mit deren Formatierung aus. Sie beginnt wie die Ansichten von SwiftLing mit SwiftLing\Admin\Ui::screenHeader(). Eine Seite ohne Namen oder Ansicht oder mit einer nicht lesbaren Datei wird ausgelassen. Eine Seite, deren Gruppe in SwiftLing nicht vorhanden ist, wird als eigenständige Seite angezeigt.

add_filter(
	'swiftling_admin_screens',
	static function ( array $screens ): array {
		$screens['swiftling-glossary'] = array(
			'menu'  => __( 'Glossary', 'my-plugin' ),
			'view'  => 'glossary',
			'file'  => __DIR__ . '/views/glossary.php',
			'group' => 'settings',
			'part'  => 'swiftling',
			'icon'  => 'M2 4h12M2 8h12M2 12h8',
			'tint'  => 'violet',
		);
		return $screens;
	}
);

swiftling_admin_groups

Filter, seit Hooks-Version 1. Die Seitengruppen, nach ID geordnet: translations und settings. Eine Gruppe ist ein einzelner Menüeintrag mit ihrem Namen, der ihre erste Seite öffnet. Jede ihrer Seiten zeigt den Gruppenkopf (name, description) und eine nach Bereichen gegliederte Liste ihrer Seiten (parts, mit den Bereichsnamen als Schlüsseln). Ein Plugin kann eine Gruppe oder Bereiche zu einer Gruppe hinzufügen.

add_filter(
	'swiftling_admin_groups',
	static function ( array $groups ): array {
		$groups['settings']['parts']['automatic'] = __( 'Automatic', 'my-plugin' );
		return $groups;
	}
);

swiftling_setup_offer

Aktion, seit Hooks-Version 24. Wird oberhalb der Frage der Ersteinrichtung nach der Sprache, in der die Website verfasst ist, ausgelöst. Dort kann ein anderes Plugin den Verantwortlichen eine besser zur Website passende Einrichtung von SwiftLing anbieten – etwa den Import von Übersetzungen eines zuvor verwendeten Mehrsprachigkeits-Plugins durch SwiftLing Pro auf einer Seite, die vor der Einrichtung geöffnet wird (before_setup oben). Wenn die Aktion etwas ausgibt, steht diese Ausgabe an erster Stelle und bildet den Haupttitel der Seite (<h1>). Die Frage folgt unter „oder SwiftLing manuell einrichten“, ihr Titel ist eine Ebene niedriger und ihre Schaltfläche nachrangig. Gibt die Aktion nichts aus, bleibt die Einrichtung unverändert.

add_action(
	'swiftling_setup_offer',
	static function (): void {
		if ( my_plugin_has_old_translations() ) {
			printf( '<section class="swiftling-card"><h1>%s</h1><p><a class="swiftling-button is-primary" href="%s">%s</a></p></section>', esc_html__( 'Bring your translations along', 'my-plugin' ), esc_url( admin_url( 'admin.php?page=my-import' ) ), esc_html__( 'Import', 'my-plugin' ) );
		}
	}
);

swiftling_setup_aside

Aktion, seit Hooks-Version 20. Wird unterhalb des ersten Einrichtungsschritts ausgelöst, in dem die Verantwortlichen nach der Sprache gefragt werden, in der die Website verfasst ist. Dort kann ein anderes Plugin anbieten, die Sprachen auf andere Weise einzurichten – auf einer Seite, die vor der Einrichtung geöffnet wird (before_setup oben). Für ein Angebot, das an erster Stelle stehen soll, siehe swiftling_setup_offer.

add_action(
	'swiftling_setup_aside',
	static function (): void {
		printf( '<p><a href="%s">%s</a></p>', esc_url( admin_url( 'admin.php?page=my-import' ) ), esc_html__( 'Import from my old plugin', 'my-plugin' ) );
	}
);

swiftling_admin_screen_assets

Aktion, seit Hooks-Version 1. Wird ausgelöst, wenn eine SwiftLing-Seite ihre Skripte und Stylesheets lädt, nachdem die von SwiftLing geladen wurden. Das Stylesheet von SwiftLing wird auf allen seinen Seiten geladen, auch auf denen anderer Plugins.

• string $slug: Slug der Seitenadresse, z. B. swiftling-languages.
• array $screen: die Seite, wie sie von swiftling_admin_screens bereitgestellt wird.

add_action(
	'swiftling_admin_screen_assets',
	static function ( string $slug ): void {
		if ( 'swiftling-glossary' === $slug ) {
			wp_enqueue_script( 'my-glossary', plugins_url( 'glossary.js', __FILE__ ), array(), '1.0.0', true );
		}
	}
);

Übersetzung

swiftling_can_translate

Filter, seit Hooks-Version 12. Legt fest, ob Benutzer, die die Website nicht verwalten, übersetzen dürfen. Die Berechtigung zum Übersetzen heißt swiftling_translate: Sie erhalten alle mit manage_options sowie die durch diesen Filter bestimmten Benutzer. Eine für eine Rolle gespeicherte Berechtigung, wie sie etwa ein Rolleneditor vergeben würde, zählt nicht. SwiftLing Pro vergibt sie an seine Übersetzerrolle und an die dafür ausgewählten Rollen.

Wer übersetzen darf, ohne die Website zu verwalten, kann die Übersetzungsseiten und den Übersetzungseditor öffnen und jeden Text in jeder Sprache übersetzen – auch Texte von Inhalten, die diese Person nicht bearbeiten darf, etwa Vorlagen, Formulare oder Texte eines Themes (swiftling_is_translator()). Die Einstellungen bleiben den Verantwortlichen der Website vorbehalten: Sprachen, Adressen, Sprachumschalter, Dienst, allgemeine Einstellungen, Protokolle, „Alles übersetzen“ sowie die Einstellungen auf den Übersetzungsseiten, etwa welche Felder von Begriffen Text enthalten, in welchen Sprachen Menüpunkte angezeigt werden und ob Texte von Themes und Plugins gesucht werden.

• bool $can: ob der Benutzer übersetzen darf; false, sofern kein anderes Plugin die Berechtigung erteilt hat.
• WP_User $user: der Benutzer.

swiftling_translator_machine

Filter, seit Hooks 13. Ob ein Übersetzer, der die Website nicht verwaltet, mit dem Übersetzungsdienst der Website übersetzen darf, dessen Nutzung den Website-Verwalter etwas kostet (swiftling_can_machine_translate()). Wird dies verweigert, antwortet die Route für maschinelle Übersetzung mit 403, und der Übersetzungseditor bietet keine maschinelle Übersetzung an – genau wie ohne verfügbaren Dienst. Wer die Website verwaltet, darf den Dienst immer nutzen. SwiftLing Pro fragt dies unter Einstellungen › Übersetzer ab.

• bool $can: true, sofern kein Plugin die Berechtigung verweigert.
• WP_User $user: der Übersetzer.

swiftling_translation_services

Filter. Die maschinellen Übersetzungsdienste, nach ID indiziert. Ein Plugin fügt einen eigenen Dienst hinzu, eine Unterklasse von SwiftLing\Translation\Service; die Seite „Übersetzungsdienst“ listet ihn zusammen mit den anderen auf.

• array<string, Service> $services

Ein Dienst erweitert SwiftLing\Translation\Service, wie es SwiftLing\Translation\Google tut:

Method
id(), name(), fullName()	deepl; DeepL, as in „Translate with DeepL“; DeepL API. The ID names its settings and the constant that can hold its key, SWIFTLING_DEEPL_API_KEY.
check( $key )	Checks a key with the service: array( 'languages' => codes ), or a WP_Error whose message says what to do. Since hooks 5, a service with models to choose from adds 'models' => array( ID => name ), the models the key may use. Since hooks 6, an error whose data has 'reason' => 'billing' is a key that works on an account that cannot pay (no credits, billing off, a spend limit reached): the screen says so as a warning, and the service does not translate until a check passes.
languageCode( $language )	The service’s code for a language of swiftling_languages(), or null when it does not translate it.
translate( $items, $source, $target )	Translates texts: see the method’s description. Since hooks 5, a language model adds tokens to its answer, the tokens it read and wrote, counted by month beside the characters (Services::tokens()).
freeCharacters(), pricingUrl()	Optional: characters translated free of charge each month, and the address of its prices.
quota()	Optional, since hooks 4: the usage of the billing period as the service counts it, array( 'used' => …, 'limit' => … ) (0 for a plan without a limit). The screen shows it instead of freeCharacters().
guide()	Optional, since hooks 2: how to get a key, shown on the Translation service screen while the service is not connected.
defaultModel()	Optional, since hooks 5: the model the service translates with until another is chosen. The Translation service screen offers the models of the last check in a list; model() gives the one chosen, the default, or the first.
sourceLanguage(), targetLanguage()	Since hooks 9: the languages of the translation under way, as swiftling_languages() gives them, told by setLanguages() before every translate(). A service heeds more than its codes with them: the formal variant of a locale (de_DE_formal is DE to DeepL), or what is set for the language.
kind()	Optional, since hooks 3: machine (the default), a translation engine billed per character, or ai, a language model billed per token. The Translation service screen lists services in a card per kind, each with SwiftLing’s icon of its kind, never a logo of the service.

Schlüssel, die auf der Seite „Übersetzungsdienst“ eingegeben werden, dürfen Buchstaben, Ziffern, -, _, : und . enthalten. Sind mehrere Dienste verbunden, übersetzt der auf dieser Seite ausgewählte Dienst (Services::current(), seit Hooks 2).

SwiftLing\Translation\Markup (seit Hooks 2) übernimmt für jeden Dienst die HTML-Verarbeitung, die Google benötigt: protect() und restore() erhalten die Attribute von Tags auf der Website, keep() und unkeep() erhalten Platzhalter, die Variablen von SEO-Plugins (swiftling_seo_variables()) und Wörter, die in <span translate="no"> nie übersetzt werden, und plainToHtml() und htmlToPlain() übertragen Klartext als HTML.

swiftling_translation_service

Filter. Der Dienst, der eine Seite, eine Vorlage oder eine Liste von Begriffen in eine Sprache übersetzt, sodass ein Plugin für unterschiedliche Sprachen oder Seiten unterschiedliche Dienste verwenden kann.

• Service|null $service: der verbundene Dienst oder null, wenn keiner verbunden ist.
• string $subject: Schlüssel des zu übersetzenden Objekts, z. B. post:12.
• array $language: die Sprache, wie sie von swiftling_languages() zurückgegeben wird.

Eine Seite auf dem Server prüfen

Seit Hooks 14 prüft swiftling_server_check( $key, $user_id = null ) die Seite eines Objekts (post:12, template:…, terms:category, siehe swiftling_subject()) auf dem Server, so wie der Übersetzungseditor sie im Browser prüft, und speichert das Ergebnis: für Übersetzungen ohne Browser, im Hintergrund, bei der Veröffentlichung, über die REST-API oder mit WP-CLI. Die Website ruft beide Seiten für die Prüfung selbst über einen Loopback-Aufruf ab, wie es auch Website-Zustand tut. Dabei verwendet sie ein signiertes Token, das einige Minuten lang für das betreffende Objekt und die jeweilige Seite gültig ist. Die Seiten werden für den angegebenen Benutzer gerendert (standardmäßig den aktuellen Benutzer), der das Objekt übersetzen dürfen muss. Die Funktion gibt das gespeicherte Ergebnis oder einen WP_Error zurück. Skripte werden nicht ausgeführt: Text, den ein Skript erst nach dem Laden der Seite erzeugt, wird nur bei der Prüfung im Browser gefunden.

Ohne den Editor übersetzen

Seit Hooks 15 führt includes/api.php die Schritte des Übersetzungseditors und des Durchlaufs „Alles übersetzen“ auf dem Server als aktueller Benutzer aus, mit denselben Berechtigungen und Prüfungen; die eigenen Routen des Editors rufen dieselben Funktionen auf. Jede Funktion gibt einen WP_Error zurück (mit einem status für eine REST-Antwort), wenn das Objekt, die Sprache oder die Berechtigungen des Benutzers nicht passen.

Function
swiftling_subject_texts( $key, $lang )	The texts of a subject (post:12, template:…, view:…, terms:category, menu:3, a builder’s subject) the user may translate, with their translations into a language: key, object, path, section, kind, type (text, html, code, url, or format for a text from code), original, translation, state (reviewed, machine, official, outdated, missing), previous and follows. The originals are never stored, so the page is checked on the server first (swiftling_server_check()).
swiftling_save_texts( $key, $lang, $items, $state )	Saves translations by key, as the editor saves what is typed: $items is a list of key, text and, for the check of placeholders, original; $state is reviewed or machine. An empty text removes a translation. Returns the states of what was saved, the keys refused for their placeholders and those ignored, the subject’s state in every language (languages), and a post’s address in the language.
swiftling_save_earlier_texts( $key, $lang, $items )	Since hooks 22, for an import: saves translations made for an earlier version of their originals, as another plugin kept them ($items: key of the text’s place now, text, and the earlier original it translated). Each text is outdated then, as when its original changed after it was translated here: visitors read the original, the editor shows the earlier translation, Translate everything leaves it to the editor, and the page counts as translated once its other texts are. A text translated now, one whose earlier version is the text now, and one another language waits with in another earlier version (a text has one previous version for all languages) are ignored; returns the keys saved too. The subject’s page must have been checked.
swiftling_save_address( $owner, $lang, $slug )	Saves the slug of a post (post:12) or of a term with a page of its own (term:5) in a language, as the editor saves a typed one: empty for the original slug, a number added to one taken there. Returns the address it gives: slug, state, original, prefix, url.
swiftling_machine_translate( $key, $lang, $items )	Translates texts (key, text, html) with the subject’s translation service, through swiftling_machine_items and swiftling_machine_translations, at most 100 texts and 20,000 characters at once; it does not save them. Returns translations, failed, kept and error.
swiftling_machine_translate_subject( $key, $lang, $again = array() )	Fills the empty texts of a subject with the service and saves them as machine translations, in batches of 50 texts and 4,000 characters, as the Translate everything run fills a page; with states in $again (machine, reviewed), translates the texts in those states again instead. Returns how many texts there were, how many were translated, their characters, the keys failed and refused, the service’s error if it stopped, and own_page when the language shows a separate copy of the post or keeps its original (the stored mode duplicate), where nothing is filled in.

Seit Hooks 19 legt swiftling_import_languages( $source, $targets, $address ) für einen Import die Sprachen der Website anhand der Sprachen eines anderen Plugins fest: Die Ausgangssprache (locale, slug) muss der bei der Ersteinrichtung festgelegten oder der bereits in SwiftLing eingestellten Sprache entsprechen (andernfalls swiftling_import_source). Zielsprachen (locale, slug, visible sowie name und rtl für eine Sprache, die WordPress nicht aufführt und die dadurch zu einer benutzerdefinierten Sprache wird) werden anhand ihrer Locale hinzugefügt; bereits vorhandene Zielsprachen bleiben erhalten. $address enthält format (parameter, directory; domain und subdomain behalten ihre domains, warten aber auf die Ansicht „Adressen“) und source_folder. Die Funktion gibt die hinzugefügten und beibehaltenen Locales (added und kept), die slugs, die Information, ob das Format auf hosts wartet, sowie die installierten und fehlenden WordPress-Sprachpakete (packs) zurück. Seit Hooks 20 läuft sie auch über die REST-API, WP-CLI und WP-Cron, nicht nur auf Administrationsseiten. Seit Hooks 21 wird ein für eine Locale angegebener name, den WordPress sonst anders vergeben würde – etwa „English“ für en_GB („English (UK)“) –, zum Namen, den der Sprachumschalter anzeigt, und zur Bezeichnung in der Ansicht „Sprachen“.

Kommentare sowie die Texte eines Themes oder Plugins erscheinen als seitenweise Listen in ihren jeweiligen Ansichten: Ihre Texte werden anhand von Schlüsseln gespeichert und übersetzt, hier aber weder aufgelistet noch ausgefüllt. Seit Hooks 23 liefert swiftling_subject_found( $subject, array( 'page' => 1 ) ) eine Seite einer Kommentarliste (comments:<post type>), wie sie im Kommentareditor erscheint: mit allen Kommentaren, die neuesten zuerst, und mit list (dessen page und pages; lang bezeichnet die Sprache, auf die sich die Anzahlen beziehen). So lassen sich ihre Übersetzungen mit swiftling_save_texts() anhand ihrer Schlüssel speichern.

swiftling_machine_items

Filter, seit Hooks 9. Die Texte aus dem Editor, die an den Übersetzungsdienst gesendet werden. Ein Plugin kann sie ergänzen: um unverändert zu lassende Teile (keep), etwa Begriffe aus einem Glossar für einen Dienst ohne Glossarfunktion, oder um Schlüssel, die ein eigener Dienst ausliest. SwiftLing belässt die Texte, die Angabe, ob sie HTML enthalten, und die eigenen unverändert zu lassenden Teile unverändert und sendet nur die Texte der Seite.

• array<string, array> $items: Schlüssel => text, html, keep; siehe Service::translate().
• Service $service: der Dienst, der sie übersetzt.
• array $language: die Sprache, in die sie übersetzt werden, in der von swiftling_languages() gelieferten Form.

swiftling_machine_translations

Filter, seit Hooks 9. Die vom Dienst zurückgegebenen Übersetzungen, bevor SwiftLing ihre Platzhalter und die Variablen von SEO-Plugins prüft und der Editor sie einsetzt. So kann ein Plugin die Übersetzungen ändern, etwa an den freigehaltenen Stellen Begriffe aus einem Glossar einfügen. Enthalten sind nur die übersetzten Texte, jeweils weiterhin als Text.

• array<string, string> $translations: Schlüssel => Übersetzung.
• array<string, array> $items: die gesendeten Elemente; siehe swiftling_machine_items.
• Service $service
• array $language

swiftling_translated_changed

Aktion. Wird ausgelöst, sobald die Sprachen, in die bestimmte Beiträge übersetzt wurden, erneut gespeichert wurden.

• int[] $post_ids

swiftling_translate_all_modes

Filter, seit Hooks 7. Die Ausführungsarten der Seite „Alles übersetzen“, nach Modus benannt und als Karten dargestellt: fill, die SwiftLing-eigene Art, füllt leere Übersetzungen aus. Ein Plugin fügt eine Ausführungsart mit label (dem Namen der Karte), description (der Zeile unter dem Seitentitel), hint (der Beschreibung auf der Karte), icon und tint (ihrem Erscheinungsbild, wie bei einer Seite in swiftling_admin_screens) sowie file hinzu (der PHP-Datei, die ihre Ansicht unter den Karten unter admin.php?page=swiftling-translate-all&mode=<mode> ausgibt). Ohne Plugin bietet SwiftLing nur eine Ausführungsart und zeigt keine Karten an. Die Skripte werden über swiftling_admin_screen_assets für swiftling-translate-all geladen; dort stehen auch die Seitenprüfung (window.swiftlingPageCheck) und die gemeinsame maschinelle Übersetzung (window.swiftlingMachine) bereit.

Ein Durchlauf, der Texte erneut übersetzt, fragt bei der Probe-Route mit fill für again nach machine, reviewed oder beidem. Sie liefert dann statt der leeren Texte die in diesen Zuständen übersetzten Texte zurück, jeweils mit ihrem state; niemals jedoch einen Text aus WordPress, einem Theme oder einem Plugin und niemals einen, dessen Original sich geändert hat. swiftling_translate_all_scan() zählt sie pro Seite und Sprache unter translated (machine, reviewed; null für eine noch nie geprüfte Seite).

swiftling_translate_all_aside

Aktion, seit Hooks 17. Wird oben in der Seitenspalte von „Alles übersetzen“ über „So funktioniert es“ ausgelöst, sobald ein Übersetzungsdienst verbunden ist. Dort kann ein Plugin eine eigene Karte zur Übersetzung der gesamten Website ausgeben (<section class="swiftling-card swiftling-side">), etwa SwiftLing Pro dazu, dass Seiten direkt nach ihrer Veröffentlichung übersetzt werden können. In Hooks 16 gab es stattdessen swiftling_translate_all_notices unter dem Seitentitel; diesen Hook gibt es nicht mehr.

swiftling_translate_all_start_actions

Aktion, seit Hooks 18. Wird im Schritt „Start“ von „Alles übersetzen“ neben der Schaltfläche ausgelöst, die den Durchlauf im Tab startet. Dort kann ein Plugin eine weitere Startmöglichkeit hinzufügen, etwa SwiftLing Pro für einen Durchlauf auf dem Server.

• string $lang: die Sprache, die in den Schritten zuerst angezeigt wird, oder "", wenn keine bearbeitet werden kann.

Ein vom Server gesteuerter Durchlauf

Seit Hooks 18 zeichnet swiftling_translate_all_record( $lang, $args ) auf, was ein Durchlauf von „Alles übersetzen“ mit einer Seite gemacht hat oder dass eine Sprache abgeschlossen ist – wie es die Fortschrittsroute beim Durchlauf im Browser tut – und gibt den Zustand des Durchlaufs zurück (swiftling_translate_all_state()). $args: page (post:12), outcome (done oder skipped), reason, texts, characters, total, finish, stopped und driver (browser oder server). Ein Plugin, das einen Durchlauf auf dem Server steuert, plant ihn mit swiftling_translate_all_plan( $lang ), übersetzt jede Seite mit swiftling_machine_translate_subject() und zeichnet sie mit driver server auf.

Pro Sprache kann jeweils nur einer den Durchlauf steuern: Wer ihn aufzeichnet, steuert ihn, bis er gestoppt wird (stopped), abgeschlossen ist oder drei Minuten (Browser) beziehungsweise fünf Minuten (Server) lang kein Fortschritt erfolgt ist. Der jeweils andere wird währenddessen mit swiftling_translate_all_busy (409) abgewiesen. driver im Zustand gibt an, wer den Durchlauf gerade steuert. Die Kachel einer vom Server bearbeiteten Sprache weist darauf hin und kann nicht ausgewählt werden.

swiftling_editor_actions

Aktion, seit Hooks 7. Wird im Kopfbereich des Übersetzungseditors nach den Werkzeugen zum Ausfüllen leerer Felder ausgelöst, damit ein Plugin dort eigene Werkzeuge ausgeben kann.

• array $subject: das Übersetzungsobjekt, siehe swiftling_subject().
• array $language: die angezeigte Sprache, in der von swiftling_languages() gelieferten Form.
• Service|null $service: der Dienst, der den Text übersetzt, oder null.

Das Skript wird über swiftling_admin_screen_assets auf swiftling-translation nach swiftling-editor geladen und greift über window.swiftlingEditor auf die Felder zu, sobald ready true ist oder das Ereignis swiftling:editor-ready auf document ausgelöst wurde:

texts( states )	The text fields translated in those states (machine, reviewed): key, state, characters of the original. Never one from WordPress, a theme or a plugin, one whose original changed, or one with changes not saved.
translateAgain( states )	Translates those fields again with the service in use and saves them as machine translations, as „Translate empty fields“ does: a promise of translated, failed and stopped (why the service stopped, or empty).
service	The name of the service in use, or empty.
dirty()	How many fields have changes not saved.

Sprachen

Seit Hooks 10 schaltet swiftling_switch_translation( $slug ) vorübergehend auf eine Sprache um, auch außerhalb der Seite, die ein Besucher liest – etwa für eine E-Mail an einen Kunden, die im Adminbereich oder durch eine geplante Aufgabe erstellt wird. Gespeicherte Werte, Texte aus dem Code und Links werden in dieser Sprache gelesen, und WordPress verwendet deren Locale, bis swiftling_resume_translation() aufgerufen wird. swiftling_pause_translation() bewirkt dasselbe für die Originalsprache. Die Aufrufe können verschachtelt werden; jeder benötigt einen entsprechenden Resume-Aufruf. Ein Slug, der keiner Sprache der Website entspricht, steht für die Originalsprache. So verfasst SwiftLing Pro WooCommerce-E-Mails an Kunden in der Sprache ihrer Bestellung.

swiftling_language_forgotten

Action. Wird ausgelöst, nachdem auf der Seite „Sprachen“ die gespeicherten Daten einer Sprache gelöscht wurden, die nicht mehr zur Website gehört. So kann ein Plugin auch seine Daten für diese Sprache löschen.

• string $locale: Locale der Sprache.
• array $done: was gelöscht wurde: texts und copies.

swiftling_starting_over

Action, seit Hooks 11. Wird ausgelöst, wenn SwiftLing über Einstellungen › Allgemein zurückgesetzt wird, noch bevor etwas entfernt wird. So kann ein Plugin, das auf SwiftLing aufbaut, seine Daten entfernen, während es noch auf Daten zugreifen kann, die SwiftLing anschließend entfernt, etwa den Schlüssel eines Übersetzungsdienstes. Bei everything entfernt SwiftLing danach alle Optionen und Transients mit seinem Namen, einschließlich swiftling_. Dazu gehören auch die eines Plugins, das diesen Namensbestandteil verwendet, wie SwiftLing Pro. Beim Löschen von SwiftLing wird nichts entfernt: Das Zurücksetzen ist die einzige Möglichkeit, seine Daten zu entfernen.

• string $scope: everything oder keep, wenn die Übersetzungen beibehalten werden.

swiftling_started_over

Action. Wird ausgelöst, nachdem SwiftLing über Einstellungen › Allgemein zurückgesetzt wurde.

• string $scope: everything oder keep, wenn die Übersetzungen beibehalten wurden.

swiftling_start_over_removed

Filter, seit Hooks 11. Fügt der Liste dessen, was beim Zurücksetzen unter Einstellungen › Allgemein entfernt wird, weitere Zeilen hinzu. So erfahren Nutzer dort auch, was ein auf SwiftLing aufbauendes Plugin entfernt.

• string[] $removed: Zeilen als reiner Text.

swiftling_language_switcher

Action für Themes. Gibt den Sprachumschalter aus; gibt nichts aus, wenn SwiftLing nicht aktiv ist.

• array $args: optional, dieselben Argumente wie bei swiftling_language_switcher(): style (dropdown, horizontal, vertical), flag, name, code, current, class.

<?php do_action( 'swiftling_language_switcher', array( 'style' => 'horizontal' ) ); ?>

swiftling_switcher_html

Filter, seit Hooks 8. Das HTML eines Sprachumschalters an jeder Stelle, an der einer ausgegeben wird (Menü, Footer, Block, Shortcode, Widget, swiftling_language_switcher). So kann ein Plugin ihn ergänzen. SwiftLing Pro fügt daneben seinen Währungsumschalter ein. Wird nicht aufgerufen, wenn keine andere Sprache zur Auswahl steht.

• string $html: der Umschalter, ein div.swiftling-switcher.
• array $args: seine Optionen: style (dropdown, horizontal, vertical), flag, name, code, current, class, flag_size.

Seiten

swiftling_hreflangs

Filter. Die alternativen Adressen der angezeigten Seite, die als hreflang-Links ausgegeben werden.

• array<string, string> $links: Sprach-Tag oder x-default => Adresse.
• array $page: die Adresse der Seite in der Originalsprache ohne Sprachangabe (url), der Beitrag, dessen Übersetzungen die verfügbaren Sprachen bestimmen (post, 0 für die Beitragsübersicht und Archive), und die Grundlage für die Erstellung ihrer Adresse (build).

swiftling_search_limit

Filter. Die Höchstzahl der Beiträge, die eine Suche aus dem Übersetzungsindex abruft.

• int $limit
• WP_Query $query

Caches

swiftling_purge_all

Aktion. Wird einmal am Ende einer Anfrage ausgelöst, nach der jede Seite veraltet sein kann, damit Seiten-Caches ihren gesamten Inhalt leeren können.

swiftling_purge_urls

Aktion. Wird einmal am Ende einer Anfrage ausgelöst, nach der einige Seiten veraltet sind, damit Seiten-Caches diese leeren können.

• string[] $urls: Adressen in allen Sprachen, in denen sie veraltet sind.
• int[] $post_ids: Beiträge, zu denen die Adressen gehören, für Caches, die nach Beitrag geleert werden.

Protokolle und Support

swiftling_log_areas

Filter. Die Bereiche der Protokollansicht, mit Bereichen als Schlüsseln und Namen als Werten. So kann ein Plugin einen eigenen Bereich benennen und mit swiftling_log( $level, $area, $message, $args ) in dasselbe Protokoll schreiben.

• array<string, string> $areas

swiftling_request_url

Filter. Legt fest, wohin Supportanfragen zu einem Plugin, Theme oder Formular gesendet werden; siehe includes/requests.php.

• string $url