If you have copy that changes based on the count of items it's referring to, you can define those different versions using Ditto's plurals feature. With plurals, you can attach multiple plural “forms” to an individual text item in Ditto and, in conjunction with Ditto’s Developer Integrations, conditionally display the correct text based on a numeric value.

For example:

"1 result found" vs. "No results found"
"1 second left" vs. "30 seconds left"

Pluralization basics

You can define plurals for any text in Ditto — on text items, on library components, and on any of their variants. You can create, edit and view plurals anywhere you can edit text in Ditto — in both the web app and the Figma Plugin. Like all other properties, plurals will be synced between library components and their linked project instances (text items).

You may add plurals to base text as well as variants. Pluralization usage does not need to match across variants — you may attach different plural forms to different variants of the same text item without issue.

Plural Forms

A plural form represents a number or group of numbers for which a particular piece of text should be used. In English, for instance, you may want to define two related strings, one for the singular case, “I have 1 item,” and another for the pluralized version, “I have 20 items.” Each of these cases can be represented by a plural form.

Ditto supports the six plural forms that are defined by the Unicode CLDR project: Zero, One, Two, Few, Many and Other. You may attach any subset of these forms to any piece of text in Ditto.

Supported forms by language

While Ditto will allow you to attach any subset of plural forms to a given piece of text, not all forms are supported in every language. For instance, English typically only supports two forms: singular (One) and plural (Other). Other languages, like Arabic, support all six. If you integrate with common libraries like i18next, only the supported forms will be recognized, while unsupported forms may be ignored.

For example, if you create an English text item with three forms: One, Two and Other, and then provide a count of 2, i18next will not recognize the unsupported Two form and will render the string assigned to Other, not the string assigned to Two.

In all languages, the “Other” form will be used as the default/fallback value - the string to use if the provided count does not match any of the more-specific defined values.

Click here for complete breakdown of supported plural forms and their definitions by language.

Working with Plurals in Ditto

You can view, add, edit and remove plurals (almost) everywhere that you can edit text in Ditto, in both the web app and the Figma Plugin.

Add plurals to a text item:

Click Plurals in the details panel. By default, this will create the two most-common plural forms, Other and One, each defaulting to the original text’s value, including variables.
Edit the text content for each plural forms individually
Click Add plural to add additional forms

💡 Remove a plural by clicking the trash icon 🗑️. If you remove all plurals, the item will revert back to its base form, without plurals.

Plurals can be added to Variants as well.

If a text item or component has plurals defined, it will be indicated in the UI with the plurals icon.

Plurals <> Figma

While you can attach multiple plural forms to a piece of text in Ditto, we can only sync a single value to your Figma designs. The same is true for certain parts of the Ditto UI outside of the text editor. In these cases, the first plural will serve as the master value for that text item. Whatever value is saved as the first plural in the list will be the value that syncs to Figma, and edits that are made directly in Figma will only sync back to the first plural, leaving the other plural forms unchanged.

Using plurals in development

To get the most out of plurals, use Ditto’s developer integrations to manage your text directly in your code.

Developer IDs

Following i18next standards, each plural form will be given its own developer id, of the format devId_form. For instance, if a text item has the Developer ID “heading”, its singular form will be given a Developer ID value of “heading_one” while its pluralized form would have a Developer ID value of “heading_other”.

These values will be represented as the id value returned from each API endpoint as well as the keys that are exported from the CLI.

API

When fetching text items and components from Ditto’s API endpoints, each response value will include a pluralForm property, mapping that text value to the individual form it represents. Each text item will always have an export with pluralForm: null representing the primary text value. If the item has plurals, this primary value will match that of the first plural. Additionally, we will return an individual value for each defined plural form, with the id property that combines its Developer ID and the plural form as described above.

The same is true for variants with plurals. Individual objects will be returned for each variant plural form as well as the primary (first plural) value with null pluralForm.

For example, a text item with Developer ID heading, and One and Other forms defined on the base text, French and Spanish variants would look like this (Note: the example below does not include all fields. See Fetch Text Items and Fetch Components for the complete response.)

[
  { id: "results", text: "{{num}} results", pluralForm: null, variantId: null },
  { id: "results_other", text: "{{num}} results", pluralForm: "other", variantId: null },
  { id: "results_one", text: "One result", pluralForm: "one", variantId: null },
  { id: "results", text: "{{num}} résultats", pluralForm: null, variantId: "french" },
  { id: "results_other", text: "{{num}} résultats", pluralForm: "other", variantId: "french" },
  { id: "results_one", text: "Un résultat", pluralForm: "one", variantId: "french" },
  { id: "results", text: "{{num}} resultados", pluralForm: null, variantId: "spanish" },
  { id: "results_other", text: "{{num}} resultados", pluralForm: "other", variantId: "spanish" },
  { id: "results_one", text: "Uno resultado", pluralForm: "one", variantId: "spanish" },
]

CLI

Similar to the API, the CLI will generate a key-value pair for the primary text, plus an additional row for each plural form, in each base/variant file. See our CLI docs for more details.

// project__base.json
{
  "results": "{{num}} results",
  "results_other": "{{num}} results",
  "results_one": "One result",
}

// project__french.json
{
  "results": "{{num}} résultats",
  "results_other": "{{num}} résultats",
  "results_one": "Un résultat",
}

// project__spanish.json
{
  "results": "{{num}} resultados",
  "results_other": "{{num}} resultados",
  "results_one": "Uno resultado",
}

If using an i18next library to render your strings, always provide the primary Developer ID (without any plural suffix) as the key and a count value where you would typically provide variables. i18next will automatically use the count value and your current language/locale to determine which of the defined plural forms to render. Refer to the i18next documentation for more details.

Developer Integrations