_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.

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

Code of _n() n ^{WP 5.7.2}

<?php
function _n( $single, $plural, $number, $domain = 'default' ) {
	$translations = get_translations_for_domain( $domain );
	$translation  = $translations->translate_plural( $single, $plural, $number );

	/**
	 * Filters the singular or plural form of a string.
	 *
	 * @since 2.2.0
	 *
	 * @param string $translation Translated text.
	 * @param string $single      The text to be used if the number is singular.
	 * @param string $plural      The text to be used if the number is plural.
	 * @param string $number      The number to compare against to use either the singular or plural form.
	 * @param string $domain      Text domain. Unique identifier for retrieving translated strings.
	 */
	$translation = apply_filters( 'ngettext', $translation, $single, $plural, $number, $domain );

	/**
	 * Filters the singular or plural form of a string for a domain.
	 *
	 * The dynamic portion of the hook, `$domain`, refers to the text domain.
	 *
	 * @since 5.5.0
	 *
	 * @param string $translation Translated text.
	 * @param string $single      The text to be used if the number is singular.
	 * @param string $plural      The text to be used if the number is plural.
	 * @param string $number      The number to compare against to use either the singular or plural form.
	 * @param string $domain      Text domain. Unique identifier for retrieving translated strings.
	 */
	$translation = apply_filters( "ngettext_{$domain}", $translation, $single, $plural, $number, $domain );

	return $translation;
}

Related Functions

From tag: localize (l10n i18n Internationalization localization)

More from category: Localization