Entwicklerschnittstellen

FG Multilang WP stellt mehrere globale PHP-Helper und zwei Actions für die Integration in Themes und Plugins bereit. Die eigentlichen FGML-Klassen liegen im globalen Namespace; das gebündelte FG Core verwendet den Namespace Funckgroup\FGCore.

Für externe Integrationen sind die Helper-Funktionen gegenüber direkten Datenbankzugriffen zu bevorzugen.

Sprach-Helper

`fgml_current_language()`

Liefert den aktuell ermittelten Sprachcode.

$language = fgml_current_language();

Die gleichwertige Funktion fgml_get_current_language() ist ebenfalls vorhanden.

`fgml_default_language()`

Liefert den Sprachcode der Default-Sprache.

$default_language = fgml_default_language();

Die gleichwertige Funktion fgml_get_default_language() ist ebenfalls vorhanden.

Übersetzungs-Helper

`fgml_get_translation_id()`

fgml_get_translation_id(
    int $object_id,
    ?string $language_code = null,
    string $object_type = 'post'
)

Liefert die Objekt-ID einer verknüpften Sprachversion oder false, wenn keine Zuordnung gefunden wird.

Wird keine Sprache angegeben, verwendet die Funktion die aktuelle Sprache.

Beispiel für einen Post:

$english_id = fgml_get_translation_id(get_the_ID(), 'en');

Beispiel für einen Term:

$english_term_id = fgml_get_translation_id($term_id, 'en', 'term');

Die Funktion prüft nicht selbst, ob ein gefundener Zielpost veröffentlicht oder öffentlich sichtbar ist. Für öffentliche Links sollte der Zielstatus deshalb bei Bedarf zusätzlich geprüft werden.

`fgml_get_translation_url()`

fgml_get_translation_url(
    int $post_id,
    ?string $language_code = null
): string

Liefert den Permalink der verknüpften Post-Übersetzung. Existiert keine Zuordnung, wird der Permalink des Ausgangsposts zurückgegeben.

$url = fgml_get_translation_url(get_the_ID(), 'en');

Auch diese Funktion führt keine Veröffentlichungsprüfung der Ziel-ID durch.

Sprachumschalter

`fgml_language_switcher()`

fgml_language_switcher(array $args = []): string

Beispiel:

echo fgml_language_switcher([
    'format' => 'inline',
    'label' => 'code_upper',
    'separator' => ' / ',
    'show_current' => true,
]);

Unterstützte Formate sind list, inline und menu_items. Die Details der Ausgabe stehen unter Menüs und Sprachumschalter.

String-Helper

`fgml_string()`

fgml_string(string $source, ?string $language_code = null): string

Sucht einen exakt konfigurierten Quellstring in der optionalen String-Tabelle.

echo esc_html(fgml_string('Jetzt anfragen'));

Ohne Übersetzung wird der Originalstring zurückgegeben.

Static Export

`fgml_get_export_urls()`

fgml_get_export_urls(): array

Liefert die von FG Multilang berechnete URL-Liste unabhängig davon, ob FG Static Export aktiv ist.

$urls = fgml_get_export_urls();

Filter `fg_static_export_urls`

Typ: Filter eines integrierbaren Static-Export-Workflows.

FG Multilang hängt sich mit Priorität 20 an diesen Filter und ergänzt die übergebene Liste um seine eigenen URLs.

add_filter('fg_static_export_urls', function (array $urls): array {
    // Läuft nach FG Multilang, wenn eine Priorität > 20 verwendet wird.
    return $urls;
}, 30);

Im README des analysierten Projekts ist zusätzlich fgml_export_urls als Beispiel genannt. Dieser Filter wird im aktuellen Code nicht registriert oder angewendet; maßgeblich ist fg_static_export_urls.

Actions nach dem Anlegen einer Übersetzung

`fgml_created_post_translation`

Typ: Action

Parameter:

int $target_id
int $source_id
string $target_language

Die Action wird ausgelöst, nachdem der neue Post verknüpft, Taxonomien und Meta kopiert und gegebenenfalls das Beitragsbild gesetzt wurden.

add_action('fgml_created_post_translation', function (
    int $target_id,
    int $source_id,
    string $target_language
): void {
    // Projektspezifische Nachbearbeitung.
}, 10, 3);

`fgml_created_term_translation`

Typ: Action

Parameter:

int $target_id
int $source_term_id
string $taxonomy
string $target_language

add_action('fgml_created_term_translation', function (
    int $target_id,
    int $source_term_id,
    string $taxonomy,
    string $target_language
): void {
    // Projektspezifische Nachbearbeitung.
}, 10, 4);

Die aktuelle Implementierung übergibt vier Parameter. Das README des Projekts zeigt an dieser Stelle noch eine ältere Signatur mit drei Parametern.

Sprachfilter bewusst umgehen

Frontend-Queries für aktivierte Post Types und Taxonomien werden standardmäßig auf die aktuelle Sprache eingeschränkt.

Für technische Abfragen über alle Sprachen erkennt das Plugin die Query-Variable:

fgml_skip_language_filter

`WP_Query`

$query = new WP_Query([
    'post_type' => ['page', 'post'],
    'post_status' => 'publish',
    'fgml_skip_language_filter' => true,
]);

`get_terms()`

$terms = get_terms([
    'taxonomy' => 'category',
    'hide_empty' => false,
    'fgml_skip_language_filter' => true,
]);

Diese Variable wird von den plugininternen Tools, WP-CLI und der Static-Export-Generierung verwendet.

Shortcodes

Das Plugin registriert zwei gleichwertige Shortcodes:

[fg_language_switcher]
[fgml_language_switcher]

Attribute:

format="list|inline|menu_items"
label="native|name|code_upper|code_lower"
separator=" / "
show_current="true|false"

WP-CLI

Die Kommandos werden nur registriert, wenn WordPress im WP-CLI-Kontext läuft.

`wp fgml status`

Gibt interne Version, Default-Sprache, aktive Sprachen, aktive Post Types, Taxonomien und Anzahl der Export-URLs aus.

wp fgml status

Hinweis: Wegen der aktuellen Versionsinkonsistenz im Paket meldet dieses Kommando FGML_VERSION und damit 1.0.0, obwohl der Plugin-Header 1.0.1 enthält.

`wp fgml prepare`

Bereitet alle aktivierten Post Types und Taxonomien vor. Fehlende Sprach-Meta werden auf die Default-Sprache gesetzt und Gruppen erzeugt.

wp fgml prepare

Die Implementierung verarbeitet alle passenden Objekte in einem Lauf und besitzt keine eigene Batching- oder Fortschrittslogik.

`wp fgml create-missing`

Legt fehlende Post-Übersetzungen als Entwurf an.

wp fgml create-missing --lang=en --post_type=page

--lang ist erforderlich. --post_type ist optional und hat den Standard page.

Das Kommando verarbeitet nur Quellposts der Default-Sprache beziehungsweise Posts ohne _fgml_lang und überspringt bereits vorhandene Zielzuordnungen.

`wp fgml flush`

Aktualisiert die WordPress-Rewrite-Regeln und entfernt fgml_needs_rewrite_flush.

wp fgml flush

Datenstrukturen

Tabelle `fgml_languages`

Wesentliche Felder:

id
code
locale
name
native_name
url_prefix
is_default
is_active
sort_order
created_at
updated_at

code ist eindeutig.

Tabelle `fgml_translations`

Wesentliche Felder:

id
group_id
object_type
object_subtype
object_id
language_code
source_object_id
status
created_at
updated_at

Die Tabelle besitzt unter anderem eindeutige Schlüssel für object_type + object_id sowie für group_id + object_type + object_subtype + language_code.

Direkte Änderungen an diesen Tabellen sind keine dokumentierte stabile öffentliche API. Werden Translation-Zeilen trotzdem direkt über $wpdb verändert, können request-lokale Lookup-Caches der Klasse FGML_Translations veraltet sein.

Meta-Schlüssel

Relevante interne Meta-Schlüssel sind:

_fgml_lang
_fgml_group
_fgml_source
_fgml_status
_fgml_media_{language}_{field}

Diese Schlüssel sollten bei projektspezifischen Import-/Migrationsprozessen berücksichtigt werden.

FG Core StatusReporter

Das gebündelte FG Core stellt zusätzliche technische Extension Points bereit.

Statusmeldung deaktivieren

define('FG_CORE_STATUS_REPORTING', false);

oder:

add_filter('fg_core_status_reporting_enabled', '__return_false');

Endpoint überschreiben

define('FG_CORE_STATUS_ENDPOINT', 'https://example.test/status');

oder:

add_filter('fg_core_status_endpoint', function (string $endpoint): string {
    return 'https://example.test/status';
});

Payload filtern

add_filter('fg_core_status_payload', function (array $payload): array {
    return $payload;
});

Status-Actions

Nach erfolgreichem Request:

add_action('fg_core_status_report_sent', function (array $payload, $response): void {
    // Eigene Diagnose.
}, 10, 2);

Bei Fehler:

add_action('fg_core_status_report_failed', function (string $message, int $http_code): void {
    // Eigene Diagnose.
}, 10, 2);

Die übertragenen Daten stehen unter Datenverarbeitung.

REST, AJAX und JavaScript-Events

FG Multilang WP registriert im aktuellen Code:

keine eigenen REST-Endpunkte,
keine eigenen wp_ajax_*-Handler,
keine öffentlichen JavaScript-Events,
keine Frontend-JavaScript-API.

Das vorhandene JavaScript unter assets/admin.js dient ausschließlich der Administration, beispielsweise zum dynamischen Ergänzen von Formularzeilen.

Interne Klassen

Klassen wie FGML_Translations, FGML_Rewrite, FGML_Frontend, FGML_Terms und FGML_ACF sind global verfügbar, werden aber in der öffentlichen API des Projekts nicht ausdrücklich als stabiler Integrationsvertrag versioniert.

Für Theme- und Plugin-Integrationen sollten daher bevorzugt die dokumentierten Helper, Shortcodes und Actions verwendet werden.

Entwicklerschnittstellen

Sprach-Helper

fgml_current_language()

fgml_default_language()

Übersetzungs-Helper

fgml_get_translation_id()

fgml_get_translation_url()