_n() WP 2.8.0
Translates and retrieves the singular or plural form based on the supplied number (1 comment, 2 comments).
Used when you want to use the appropriate form of a string based on whether a number is singular or plural.
We need to pass translation strings and number to the function, then:
-
If a single number (1) is passed, the function returns the translated value of the first parameter: $single.
-
If a plural is passed (2 3 4), the function returns the translated value of the second parameter: $plural.
- If it is not possible to get the translation of the desired line from the translation file, the function will return the original value of the line.
If the transfer ID ($domain) is specified. The function will pass the $single, $plural, and $number parameters to the Translations::translate_plural() method. Then the result and all parameters will be passed to the ngettext
filter.
To translate a string to singular or plural form based on the supplied number with context, use the similar function _nx().
Hooks from the function
Return
String. The translated or original string specified in the $single or $plural parameter, depending on the passed $number parameter.
Usage
_n( $single, $plural, $number, $domain );
- $single(string) (required)
- The text to be used if the number is singular.
- $plural(string) (required)
- The text to be used if the number is plural.
- $number(int) (required)
- The number to compare against to use either the singular or plural form.
- $domain(string)
- Text domain. Unique identifier for retrieving translated strings.
Default: 'default'
Examples
#2 Usage understanding
To understand how to use _n() function, let's separate usage on steps.
First, see what the function returns:
echo _n( '%s star', '%s stars', 1, 'textdomain' ); // Displays: %s star echo _n( '%s star', '%s stars', 3, 'textdomain' ); // Displays: %s stars
Second, we need to replays playsholder in given string to the number. To do it we use sprintf() function (suppose we translate to Russian):
$rating = 1; echo sprintf( _n( '%s star', '%s stars', $rating, 'textdomain' ), $rating ); // Displays: 1 звезда $rating = 4; echo sprintf( _n( '%s star', '%s stars', $rating, 'textdomain' ), $rating ); // Displays: 4 звезды $rating = 6; echo sprintf( _n( '%s star', '%s stars', $rating, 'textdomain' ), $rating ); // Displays: 6 звезд
Or we can display it simpler, with printf():
$rating = 1; printf( _n('%s person', '%s people', $rating, 'text-domain'), $rating );
It is assumed that there is a translation .mo file that it is registered with
load_plugin_textdomain() and has 'textdomain' identifier. Also this translation file has a correct translations for single/plural forms of number.
#2 Never do a calculation inside the sprintf() function!
The following won't work:
$text = sprintf( _n( '%s star', '%s stars', $rating, 'your-text-domain' ), 2 <= $rating ? $rating -1 : $rating );
Correct is:
$rating = 2 <= $rating ? $rating - 1 : $rating; $text = sprintf( _n( '%s star', '%s stars', $rating, 'your-text-domain' ), $rating );
Changelog
Since 2.8.0 | Introduced. |
Since 5.5.0 | Introduced ngettext-{$domain} filter. |