Signatur
Beschreibung
bindtextdomain() legt fest, in welchem Verzeichnis PHP nach den Übersetzungsdateien für eine bestimmte Gettext-Domain sucht. Die Übersetzungsdateien werden dabei im Format VERZEICHNIS/LOCALE/LC_MESSAGES/DOMAIN.mo erwartet, wobei LOCALE z. B. de_DE oder de_DE.UTF-8 ist.
Die Funktion ist ein zentraler Bestandteil des Gettext-Internationalisierungs-Workflows in PHP. Zuerst wird mit bindtextdomain() das Verzeichnis für eine Domain registriert, anschließend mit textdomain() die aktive Domain gesetzt, und schließlich werden Übersetzungen per gettext() oder dem Alias _() abgerufen.
Wird null als $directory übergeben (ab PHP 8.0.3), gibt die Funktion den aktuell gebundenen Pfad für die Domain zurück, ohne eine Änderung vorzunehmen. Ist noch kein Pfad gebunden, wird false zurückgegeben.
Wichtig: Die Funktion setzt voraus, dass die Gettext-Erweiterung (ext-gettext) installiert und aktiviert ist. Auf vielen Linux-Systemen ist sie standardmäßig verfügbar, auf Windows kann die Konfiguration aufwendiger sein.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $domain Pflicht | string | Name der Textdomain, der mit der Übersetzungsdatei verknüpft wird. Dieser Name entspricht dem Dateinamen der .mo-Datei ohne Dateiendung, z. B. 'messages' für messages.mo. |
|
| $directory Pflicht | string|null | Absoluter oder relativer Pfad zum Basisverzeichnis, das die Locale-Unterordner enthält. Wird null übergeben, wird der aktuell gebundene Pfad zurückgegeben, ohne ihn zu ändern. |
Rückgabewert
string zurück. Gibt false zurück, wenn kein Pfad gesetzt ist und null als Verzeichnis übergeben wurde.Beispiele
Grundlegende Gettext-Initialisierung für eine deutsche Übersetzung
<?php
// Locale setzen (Systemlocale muss verfügbar sein, z. B. 'de_DE.UTF-8')
putenv('LC_ALL=de_DE.UTF-8');
setlocale(LC_ALL, 'de_DE.UTF-8');
// Verzeichnis für die Domain 'messages' festlegen
// Erwartet: /var/www/html/locale/de_DE.UTF-8/LC_MESSAGES/messages.mo
$path = bindtextdomain('messages', '/var/www/html/locale');
echo 'Gebundener Pfad: ' . $path . PHP_EOL;
// Zeichenkodierung der Domain auf UTF-8 setzen
bind_textdomain_codeset('messages', 'UTF-8');
// Domain aktivieren
textdomain('messages');
// Übersetzung abrufen
echo gettext('Hello World');
// Gibt z. B. 'Hallo Welt' aus, wenn die Übersetzung in der .mo-Datei vorhanden istAktuellen gebundenen Pfad abfragen ohne Änderung (ab PHP 8.0.3)
<?php
// Domain zuerst binden
bindtextdomain('myapp', '/srv/translations');
// Pfad nur abfragen, ohne ihn zu ändern
$currentPath = bindtextdomain('myapp', null);
if ($currentPath !== false) {
echo 'Aktueller Pfad für myapp: ' . $currentPath . PHP_EOL;
} else {
echo 'Kein Pfad gebunden.' . PHP_EOL;
}Mehrere Domains für verschiedene Module registrieren
<?php
putenv('LC_ALL=fr_FR.UTF-8');
setlocale(LC_ALL, 'fr_FR.UTF-8');
$localeBase = __DIR__ . '/locale';
// Separate Domains für verschiedene Anwendungsbereiche
bindtextdomain('frontend', $localeBase);
bindtextdomain('backend', $localeBase);
bindtextdomain('emails', $localeBase);
bind_textdomain_codeset('frontend', 'UTF-8');
bind_textdomain_codeset('backend', 'UTF-8');
bind_textdomain_codeset('emails', 'UTF-8');
// Domain je nach Kontext wechseln
textdomain('frontend');
echo gettext('Welcome') . PHP_EOL; // Aus frontend.mo
textdomain('emails');
echo gettext('Your order has been placed') . PHP_EOL; // Aus emails.mo// Wichtig · Fallstricke
Systemlocale: Damit Gettext funktioniert, muss die entsprechende Locale auf dem Server installiert sein (z. B. de_DE.UTF-8 unter Debian/Ubuntu via locale-gen de_DE.UTF-8). Ein häufiger Fehler ist, dass setlocale() eine gültige Locale zurückgibt, die Übersetzung aber dennoch nicht funktioniert, weil die Locale systemseitig fehlt.
Caching: Gettext kann Übersetzungsdateien aggressiv cachen. Änderungen an .mo-Dateien erfordern unter Umständen einen Neustart des Webservers oder PHP-FPM-Prozesses, um wirksam zu werden.
Relative Pfade: Die Verwendung relativer Pfade kann in verschiedenen Ausführungskontexten (z. B. CLI vs. Webserver) zu unterschiedlichen Ergebnissen führen. Es wird empfohlen, absolute Pfade zu verwenden, z. B. mit __DIR__.
Thread-Safety: Gettext-Locale-Einstellungen sind prozessweit und nicht thread-safe. In Umgebungen mit mehreren gleichzeitigen Anfragen (z. B. Apache mit Threads) kann es zu Race Conditions kommen. Eine Alternative zu Gettext in solchen Szenarien sind PHP-basierte Übersetzungsbibliotheken wie Symfony Translation oder gettext-basierte Wrapper.