Signatur
Beschreibung
dcngettext() ist die Plural-Variante von dcgettext() und kombiniert die Funktionalität von dngettext() (domainspezifische Pluralübersetzung) mit der Möglichkeit, eine bestimmte Locale-Kategorie anzugeben. Sie sucht in der angegebenen Textdomain nach der passenden Übersetzung und wählt dabei anhand von $count entweder die Singular- oder Pluralform aus.
Die Funktion ist Teil der GNU gettext-Internationalisierungsbibliothek (i18n). Sie ermöglicht es, Anwendungen mehrsprachig zu gestalten, indem Übersetzungen aus .mo-Dateien geladen werden. Der Parameter $category bestimmt, welcher Aspekt der Locale verwendet wird – in der Regel LC_MESSAGES.
Wird keine passende Übersetzung gefunden (z. B. weil die Locale nicht gesetzt oder die .mo-Datei nicht vorhanden ist), gibt die Funktion automatisch $singular zurück, wenn $count gleich 1 ist, andernfalls $plural. Dies stellt einen sinnvollen Fallback im Quelltext sicher.
Typische Anwendungsfälle sind mehrsprachige Webanwendungen oder CLI-Tools, bei denen klar zwischen Singular- und Pluralformen unterschieden werden muss und gleichzeitig verschiedene Locale-Kategorien relevant sind.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $domain Pflicht | string | Der Name der Textdomain, in der nach der Übersetzung gesucht wird. Entspricht dem Dateinamen der .mo-Datei ohne Erweiterung. |
|
| $singular Pflicht | string | Die Zeichenkette im Singular (Einzahl), die übersetzt werden soll. Wird auch als Fallback zurückgegeben, wenn $count === 1 und keine Übersetzung gefunden wurde. |
|
| $plural Pflicht | string | Die Zeichenkette im Plural (Mehrzahl), die übersetzt werden soll. Wird als Fallback zurückgegeben, wenn $count !== 1 und keine Übersetzung gefunden wurde. |
|
| $count Pflicht | int | Die Anzahl, anhand derer entschieden wird, ob Singular oder Plural verwendet wird. Bei 1 wird die Singularform gewählt. |
|
| $category Pflicht | int | Die Locale-Kategorie als Integer-Konstante, z. B. LC_MESSAGES, LC_MONETARY oder LC_TIME. Bestimmt, welcher Bereich der aktuellen Locale verwendet wird. |
Rückgabewert
$singular (bei $count === 1) oder $plural (bei $count !== 1) zurückgegeben.Beispiele
Einfache Pluralübersetzung mit bestimmter Domain und Kategorie
<?php
// Locale und Textdomain einrichten
putenv('LANG=de_DE.UTF-8');
setlocale(LC_MESSAGES, 'de_DE.UTF-8');
bindtextdomain('meine_app', '/var/www/locales');
bind_textdomain_codeset('meine_app', 'UTF-8');
$count = 3;
$text = dcngettext('meine_app', '%d Nachricht', '%d Nachrichten', $count, LC_MESSAGES);
echo sprintf($text, $count);
// Ausgabe (wenn Übersetzung vorhanden): "3 Nachrichten"Fallback ohne verfügbare Übersetzungsdatei
<?php
// Keine .mo-Datei vorhanden – Fallback auf Original-Strings
putenv('LANG=de_DE.UTF-8');
setlocale(LC_MESSAGES, 'de_DE.UTF-8');
bindtextdomain('nicht_vorhanden', '/tmp/locales');
$count = 1;
$text = dcngettext('nicht_vorhanden', '%d item', '%d items', $count, LC_MESSAGES);
echo sprintf($text, $count) . PHP_EOL;
$count = 5;
$text = dcngettext('nicht_vorhanden', '%d item', '%d items', $count, LC_MESSAGES);
echo sprintf($text, $count) . PHP_EOL;// Wichtig · Fallstricke
Voraussetzung: Die GNU-gettext-Erweiterung muss in PHP kompiliert oder als shared extension geladen sein (extension=gettext). Ohne diese Erweiterung steht dcngettext() nicht zur Verfügung.
Die Locale muss auf dem System installiert sein (z. B. mit locale-gen de_DE.UTF-8 unter Debian/Ubuntu), sonst hat setlocale() keinen Effekt und Übersetzungen werden nicht geladen.
Für die meisten Anwendungsfälle reicht ngettext() oder dngettext() aus. dcngettext() ist nur dann notwendig, wenn bewusst eine von LC_MESSAGES abweichende Locale-Kategorie angegeben werden soll.
Die Funktion ist nicht threadsicher, wenn Locale-Einstellungen global verändert werden. In Umgebungen mit mehreren gleichzeitigen Anfragen (z. B. PHP-FPM) sollte die Locale-Verwaltung sorgfältig geplant werden.