Signatur
Beschreibung
dngettext ist die Kombination aus dgettext (domänenspezifische Übersetzung) und ngettext (Pluralauflösung). Die Funktion sucht in der angegebenen Gettext-Domäne nach der passenden Pluralform des Strings und gibt diese zurück – abhängig vom übergebenen Zählwert.
Sie wird im Kontext von Internationalisierung (i18n) und Lokalisierung (l10n) eingesetzt, wenn eine Anwendung mehrere Übersetzungsdomänen verwendet (z. B. separate .mo-Dateien für verschiedene Module) und gleichzeitig grammatikalisch korrekte Pluralformen benötigt. Ohne passende Übersetzung gibt die Funktion den $singular- oder $plural-String zurück, je nachdem ob $count gleich 1 ist oder nicht.
Voraussetzung für die Nutzung ist, dass die Gettext-Erweiterung in PHP aktiviert ist (ext/gettext), die gewünschte Locale mit setlocale() gesetzt wurde und die entsprechenden .mo-Dateien im richtigen Verzeichnis liegen (gebunden mit bindtextdomain()).
Für einfache Pluralübersetzungen ohne Domänenangabe steht ngettext() zur Verfügung; für domänenspezifische Übersetzungen ohne Plural reicht dgettext().
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $domain Pflicht | string | Name der Gettext-Domäne (entspricht dem Dateinamen der .mo-Datei ohne Endung), in der nach der Übersetzung gesucht wird. |
|
| $singular Pflicht | string | Der Singular-Ausgangsstring, der als Schlüssel in der Übersetzungsdatei genutzt wird und als Fallback zurückgegeben wird, wenn $count === 1 und keine Übersetzung gefunden wurde. |
|
| $plural Pflicht | string | Der Plural-Ausgangsstring, der als Fallback zurückgegeben wird, wenn $count !== 1 und keine Übersetzung gefunden wurde. |
|
| $count Pflicht | int | Der Zählwert, anhand dessen die korrekte Pluralform ermittelt wird. Sprachspezifische Regeln (z. B. für Slavische Sprachen mit mehreren Pluralformen) werden aus den .mo-Metadaten gelesen. |
Rückgabewert
$singular zurückgegeben, wenn $count === 1, sonst $plural.Beispiele
Grundlegende Nutzung mit einer eigenen Domäne
<?php
// Locale und Domäne konfigurieren
putenv('LANG=de_DE.UTF-8');
setlocale(LC_ALL, 'de_DE.UTF-8');
// Pfad zur .mo-Datei: /var/www/locales/de_DE/LC_MESSAGES/shop.mo
bindtextdomain('shop', '/var/www/locales');
bind_textdomain_codeset('shop', 'UTF-8');
$anzahl = 3;
// Sucht in der Domäne 'shop' nach der deutschen Pluralform
$text = dngettext('shop', '%d Artikel', '%d Artikel', $anzahl);
echo sprintf($text, $anzahl);
// Ausgabe (wenn Übersetzung vorhanden): z. B. "3 Artikel"Fallback ohne vorhandene Übersetzung
<?php
putenv('LANG=de_DE.UTF-8');
setlocale(LC_ALL, 'de_DE.UTF-8');
bindtextdomain('meinmodul', '/var/www/locales');
bind_textdomain_codeset('meinmodul', 'UTF-8');
// Kein passender Eintrag in der .mo-Datei vorhanden
$count = 1;
echo dngettext('meinmodul', 'Eine Nachricht', '%d Nachrichten', $count);
echo "\n";
$count = 5;
echo sprintf(dngettext('meinmodul', 'Eine Nachricht', '%d Nachrichten', $count), $count);// Wichtig · Fallstricke
Voraussetzungen: Die PHP-Erweiterung ext/gettext muss aktiviert sein. Auf manchen Systemen (insbesondere Windows) ist die Unterstützung eingeschränkt oder erfordert zusätzliche Konfiguration.
Locale-Abhängigkeit: Die Funktion arbeitet nur korrekt, wenn eine gültige Locale mit setlocale() gesetzt wurde und diese Locale auf dem System installiert ist. Ein häufiger Fallstrick ist das Setzen einer nicht installierten Locale, woraufhin die Übersetzungen stillschweigend ausbleiben.
Thread-Sicherheit: setlocale() ist nicht thread-sicher; in Multi-Thread-Umgebungen (z. B. mit PHP-FPM und bestimmten Setups) kann es zu Race Conditions kommen. Als Alternative bieten sich Bibliotheken wie Symfony Translation oder php-gettext an.
Pluralregeln: Komplexe Sprachen (Polnisch, Russisch, Arabisch) besitzen mehr als zwei Pluralformen. Diese werden über den Plural-Forms-Header in der .po/.mo-Datei definiert und von dngettext automatisch ausgewertet.