Signatur
Beschreibung
dcgettext() ist eine Erweiterung der Standard-Gettext-Funktion gettext(). Sie erlaubt es, für eine einzelne Übersetzungsabfrage sowohl eine abweichende Domain (d. h. eine bestimmte .mo-Datei) als auch eine bestimmte LC-Kategorie anzugeben, ohne die global aktive Domain oder Kategorie dauerhaft zu überschreiben.
Typischerweise kommt diese Funktion zum Einsatz, wenn eine Anwendung mehrere Übersetzungsdateien (z. B. für verschiedene Module oder Bibliotheken) verwendet und man gezielt auf eine davon zugreifen möchte, ohne den globalen Zustand mit textdomain() und setlocale() zu verändern.
Der Parameter category entspricht einer der LC-Konstanten wie LC_MESSAGES, LC_ALL usw. In der Praxis wird fast immer LC_MESSAGES verwendet, da dieser Kategoriewert speziell für Nachrichtenübersetzungen vorgesehen ist.
Damit die Funktion korrekt arbeitet, muss zuvor mit bindtextdomain() ein Verzeichnis für die jeweilige Domain registriert worden sein und eine passende .mo-Datei für die aktive Locale vorliegen.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $domain Pflicht | string | Name der Gettext-Domain (entspricht dem Dateinamen der .mo-Datei ohne Endung), in der nach der Übersetzung gesucht werden soll. |
|
| $message Pflicht | string | Der zu übersetzende Originaltext (Message-ID), der als Schlüssel in der .mo-Datei dient. |
|
| $category Pflicht | int | Die LC-Kategorie, die für die Übersetzung herangezogen wird. Typischerweise LC_MESSAGES; weitere Werte sind z. B. LC_ALL, LC_CTYPE. |
Rückgabewert
message unverändert zurückgegeben.Beispiele
Einfache Verwendung mit LC_MESSAGES
<?php
// Locale und Domain-Verzeichnis einrichten
setlocale(LC_MESSAGES, 'de_DE.UTF-8');
// Domain 'shop' auf ein Verzeichnis binden
bindtextdomain('shop', '/var/www/locale');
bindtextdomain('admin', '/var/www/locale');
// Globale Domain ist 'shop'
textdomain('shop');
// Übersetzung aus der globalen Domain 'shop' holen
echo gettext('Welcome') . PHP_EOL;
// Übersetzung gezielt aus der Domain 'admin' holen,
// ohne die globale Domain zu ändern
echo dcgettext('admin', 'Dashboard', LC_MESSAGES) . PHP_EOL;
// Globale Domain ist weiterhin 'shop'
echo gettext('Welcome') . PHP_EOL;Fallback auf Originaltext bei fehlender Übersetzung
<?php
setlocale(LC_MESSAGES, 'de_DE.UTF-8');
bindtextdomain('myplugin', '/var/www/locale');
textdomain('main');
// Falls keine .mo-Datei oder kein passender Eintrag vorhanden,
// wird der Originaltext zurückgegeben
$text = dcgettext('myplugin', 'This string has no translation', LC_MESSAGES);
echo $text;// Wichtig · Fallstricke
Plattformabhängigkeit: dcgettext() setzt eine funktionierende Gettext-Bibliothek auf dem System voraus. Unter Windows kann die Verfügbarkeit und das Verhalten abweichen. Auf Systemen ohne native Gettext-Unterstützung steht die Funktion möglicherweise nicht zur Verfügung.
Dateistruktur: Die .mo-Dateien müssen im Format {basepath}/{locale}/LC_MESSAGES/{domain}.mo vorliegen, damit Gettext sie findet. Fehlt diese Struktur, liefert die Funktion stets den Originaltext zurück.
Kategorie-Konstanten: Nicht alle LC-Kategorien sind auf jedem Betriebssystem für Gettext sinnvoll. LC_MESSAGES ist der Standard und sollte bevorzugt verwendet werden. Abweichende Kategorien wie LC_TIME haben je nach Plattform unterschiedliche Auswirkungen.