Fluent Syntax Selectors

fluent-syntax-selectors

Quick Reference

Select Expression Anatomy

message-id =
    { $variable ->
        [key1] Pattern for key1.
        [key2] Pattern for key2.
       *[default] Fallback pattern.
    }

Selector Types

CLDR Plural Categories by Language

All six possible CLDR categories: zero, one, two, few, many, other.

Critical Warnings

EVERY select expression MUST have exactly one *[default] variant. Omitting it is a syntax error. The grammar enforces this -- there is no workaround.

NEVER use ICU MessageFormat syntax {count, plural, one{...} other{...}} in FTL files. Fluent uses { $count -> [one] ... *[other] ... }.

ALWAYS include *[other] as the default variant for plural selectors. The other category exists in every language and is the safest default.

NEVER assume English plural categories apply to other languages. English uses only one and other. Polish uses one, few, many, other. Arabic uses all six categories.

ALWAYS remember that exact numeric matches ([0], [1]) are checked BEFORE CLDR category matches. Use exact matches to special-case specific values.

Decision Trees

Which Selector Type Do I Need?

Is the selector based on a number?
├── YES: Does it need ordinal suffixes (1st, 2nd, 3rd)?
│   ├── YES → Use NUMBER($var, type: "ordinal") selector
│   └── NO: Do you need special formatting (decimal places)?
│       ├── YES → Use NUMBER($var, minimumFractionDigits: N) selector
│       └── NO: Do you need exact value matches (0, 1, 42)?
│           ├── YES → Combine exact [N] keys with CLDR *[other]
│           └── NO → Use plain $var selector with CLDR categories
└── NO: Is it matching a string value?
    └── YES → Use $var selector with string variant keys

How Many CLDR Categories Do I Need?

What language are you localizing for?
├── Japanese/Chinese/Korean → Only *[other] (no plural forms)
├── English/German/Dutch → [one] and *[other]
├── French/Portuguese (BR) → [one] and *[other] (note: 0 is "one" in French)
├── Polish/Czech/Slovak → [one], [few], [many], *[other]
├── Arabic → [zero], [one], [two], [few], [many], *[other]
└── Unsure → Check CLDR plural rules, ALWAYS include *[other]

Select Expression Patterns

Cardinal Plurals (Basic)

emails =
    { $count ->
        [one] You have one unread email.
       *[other] You have { $count } unread emails.
    }

The runtime evaluates $count against CLDR cardinal plural rules for the current locale. For English: 1 matches [one], everything else matches *[other].

Cardinal Plurals (Multi-Category Language)

# Polish: one, few, many, other
emails =
    { $count ->
        [one] Masz jedną nieprzeczytaną wiadomość.
        [few] Masz { $count } nieprzeczytane wiadomości.
        [many] Masz { $count } nieprzeczytanych wiadomości.
       *[other] Masz { $count } nieprzeczytanych wiadomości.
    }

Exact Numeric Matches with CLDR Fallback

items-in-cart =
    { $count ->
        [0] Your cart is empty.
        [1] You have one item in your cart.
       *[other] You have { $count } items in your cart.
    }

Exact matches [0] and [1] are checked FIRST. If $count is 0, the [0] variant wins even though 0 would match *[other] by CLDR rules. If $count is 5, no exact match exists so CLDR resolves to *[other].

Ordinal Plurals

your-rank = { NUMBER($pos, type: "ordinal") ->
    [1] You finished first!
    [one] You finished {$pos}st
    [two] You finished {$pos}nd
    [few] You finished {$pos}rd
   *[other] You finished {$pos}th
}

The type: "ordinal" argument switches to ordinal CLDR categories. Exact match [1] is checked first. Then CLDR ordinal rules apply: in English, one = 1st/21st/31st, two = 2nd/22nd, few = 3rd/23rd, other = 4th-20th/24th-30th, etc.

String Selectors

# $gender is a string passed from the application
welcome =
    { $gender ->
        [masculine] Welcome, he is here.
        [feminine] Welcome, she is here.
       *[other] Welcome, they are here.
    }

String selectors match variant keys as literal string comparisons. The application passes $gender as "masculine", "feminine", or any other string. Non-matching values fall through to *[other].

Formatted Number Selectors

your-score =
    { NUMBER($score, minimumFractionDigits: 1) ->
        [0.0] You scored zero points. What happened?
       *[other] You scored { NUMBER($score, minimumFractionDigits: 1) } points.
    }

The NUMBER function with formatting options controls how the value is rendered AND which variant it matches. The formatted representation 0.0 is matched against [0.0].

Nested Selectors

response =
    { $gender ->
        [masculine] { $count ->
            [one] He wrote one message.
           *[other] He wrote { $count } messages.
        }
        [feminine] { $count ->
            [one] She wrote one message.
           *[other] She wrote { $count } messages.
        }
       *[other] { $count ->
            [one] They wrote one message.
           *[other] They wrote { $count } messages.
        }
    }

Nested selectors allow multi-dimensional variant selection. Each outer variant contains a complete inner select expression. Every inner expression MUST also have its own *[default] variant.

EBNF Grammar

SelectExpression ::= InlineExpression blank? "->" blank_inline? variant_list
variant_list     ::= Variant* DefaultVariant Variant* line_end
Variant          ::= line_end blank? VariantKey blank_inline? Pattern
DefaultVariant   ::= line_end blank? "*" VariantKey blank_inline? Pattern
VariantKey       ::= "[" blank? (NumberLiteral | Identifier) blank? "]"

Key rules enforced by this grammar:

1. variant_list contains exactly ONE DefaultVariant (the *-prefixed variant).
2. The default variant can appear at ANY position in the list, not only last.
3. Variant keys are either NumberLiteral (for exact matches) or Identifier (for CLDR categories or string matching).
4. A NumberLiteral in a variant key can be negative: -1 is valid.

Common Mistakes

Reference Links

• references/methods.md -- EBNF grammar details, CLDR category table per language
• references/examples.md -- Complete working examples for all selector types
• references/anti-patterns.md -- What NOT to do, with explanations

Official Sources

• https://projectfluent.org/fluent/guide/selectors.html
• https://projectfluent.org/fluent/guide/builtins.html
• https://raw.githubusercontent.com/projectfluent/fluent/master/spec/fluent.ebnf
• https://unicode.org/cldr/charts/latest/supplemental/language_plural_rules.html