4.6.x common.inc format_plural($count, $singular, $plural)
4.7.x common.inc format_plural($count, $singular, $plural)
5.x common.inc format_plural($count, $singular, $plural)
6.x common.inc format_plural($count, $singular, $plural, $args = array(), $langcode = NULL)
7.x common.inc format_plural($count, $singular, $plural, array $args = array(), array $options = array())

Format a string containing a count of items.

This function ensures that the string is pluralized correctly. Since t() is called by this function, make sure not to pass already-localized strings to it.

For example:

  $output = format_plural($node->comment_count, '1 comment', '@count comments');

Example with additional replacements:

  $output = format_plural($update_count,
    'Changed the content type of 1 post from %old-type to %new-type.',
    'Changed the content type of @count posts from %old-type to %new-type.',
    array('%old-type' => $info->old_type, '%new-type' => $info->new_type)));

Parameters

$count: The item count to display.

$singular: The string for the singular case. Please make sure it is clear this is singular, to ease translation (e.g. use "1 new comment" instead of "1 new"). Do not use @count in the singular string.

$plural: The string for the plural case. Please make sure it is clear this is plural, to ease translation. Use @count in place of the item count, as in "@count new comments".

$args: An associative array of replacements to make after translation. Incidences of any key in this array are replaced with the corresponding value. Based on the first character of the key, the value is escaped and/or themed:

  • !variable: inserted as is
  • @variable: escape plain text to HTML (check_plain)
  • %variable: escape text and theme as a placeholder for user-submitted content (check_plain + theme_placeholder)

Note that you do not need to include @count in this array. This replacement is done automatically for the plural case.

$langcode: Optional language code to translate to a language other than what is used to display the page.

Return value

A translated string.

Related topics

28 calls to format_plural()
actions_synchronize in includes/actions.inc
Synchronize actions that are provided by modules.
aggregator_view in modules/aggregator/aggregator.admin.inc
Displays the aggregator administration page.
comment_link in modules/comment/comment.module
Implementation of hook_link().
comment_nodeapi in modules/comment/comment.module
Implementation of hook_nodeapi().
format_interval in includes/common.inc
Format a time interval with the requested granularity.

... See full list

File

includes/common.inc, line 1249
Common functions that many Drupal modules will need to reference.

Code

function format_plural($count, $singular, $plural, $args = array(), $langcode = NULL) {
  $args['@count'] = $count;
  if ($count == 1) {
    return t($singular, $args, $langcode);
  }

  // Get the plural index through the gettext formula.
  $index = (function_exists('locale_get_plural')) ? locale_get_plural($count, $langcode) : -1;
  // Backwards compatibility.
  if ($index < 0) {
    return t($plural, $args, $langcode);
  }
  else {
    switch ($index) {
      case "0":
        return t($singular, $args, $langcode);
      case "1":
        return t($plural, $args, $langcode);
      default:
        unset($args['@count']);
        $args['@count[' . $index . ']'] = $count;
        return t(strtr($plural, array('@count' => '@count[' . $index . ']')), $args, $langcode);
    }
  }
}

Comments

gowriabhaya’s picture

I would like to see when $count = 0, it should be treated as singular rather than plural.

-Gowri

fgm’s picture

Whether 0 is treated as singular or plural is language-dependent. See http://en.wikipedia.org/wiki/Plural for details.

SKAUGHT’s picture

if count=0 should be checked for in a step before you get to outputting a positive results (:

Drave Robber’s picture

$singular The string for the singular case. Please make sure it is clear this is singular, to ease translation (e.g. use "1 new comment" instead of "1 new"). Do not use @count in the singular string.

I believe this is bad advice.

A great multitude of languages use singular for 21, 31 etc.; if $language->formula is defined correctly, format_plural is able to format these correctly; however, not using @count leads to '1 whatever' being displayed instead of '21 whatever', '31 whatever' etc.

See this issue for an example.

Drave Robber’s picture

...or maybe not. The whole problem appears to be a lot more complex – see this issue for more details.