Ordinal

Arithmetic Internationalization

Synopsis

Converts numbers to ordinal format in multiple languages.

Schema

- ordinal:
    field: <ident>
    target_field: <string>
    language: <string>
    format: <string>
    case: <string>
    date_format: <string>
    gender: <string>
    superscript: <boolean>
    space_before_suffix: <boolean>
    description: <text>
    if: <script>
    ignore_failure: <boolean>
    ignore_missing: <boolean>
    on_failure: <processor[]>
    on_success: <processor[]>
    tag: <string>

Configuration

The following fields are used to define the processor:

Field	Required	Default	Description
field	Y	-	Source field containing number or date to convert
target_field	N	Same as field	Target field to store ordinal result
language	N	en	Language code (en, es, fr, de, it, pt, nl, ru, ja, zh)
format	N	suffix	Output format (suffix, word, both, number_suffix)
case	N	-	lower, upper, title or sentence. Unset means no transformation — it is not the same as lower
date_format	N	-	Template for rendering a date. Setting it switches the processor into date mode: the source field is parsed as a date and the markers below are substituted. See Date Mode
gender	N	-	Gender for languages with gender (masculine, feminine, neuter)
superscript	N	false	Wrap the suffix in <sup> tags. Has no effect when space_before_suffix is also set, since the suffix is then no longer adjacent to the digits
space_before_suffix	N	false	Add space before ordinal suffix
description	N	-	Explanatory note
if	N	-	Condition to run
ignore_failure	N	false	Continue processing if conversion fails
ignore_missing	N	false	Skip processing if referenced field doesn't exist
on_failure	N	-	See Handling Failures
on_success	N	-	See Handling Success
tag	N	-	Identifier
disabled	N	false	When true, the processor is skipped and the event continues to the next one. Lets you take a processor out of the path without removing its configuration

Details

Converts numeric values to ordinal representations supporting multiple languages and output formats. The processor handles both individual numbers and numbers embedded within strings.

The processor supports ten languages with proper linguistic rules for ordinal formation. For gendered languages like Spanish, French, Italian, and Portuguese, the gender parameter affects the ordinal suffix and word forms.

note

Languages use different ordinal conventions: English uses suffixes (1st, 2nd, 3rd), Romance languages use degree symbols (1º, 2ª), Germanic languages use periods (1.), and Asian languages use prefixes (第1, 1番目).

The processor can output ordinals in various formats: numeric with suffix (21st), word form (twenty-first), or both (21st (twenty-first)).

Date Mode

Setting date_format changes what the processor does: the source field is parsed as a date — RFC 3339 first, then 2006-01-02, or a Unix timestamp for a numeric field — and date_format is treated as a template, not as a layout string. Markers are substituted; everything else is copied through verbatim, so a template with no markers is returned unchanged.

Marker	Substituted with
\{day\}	Day of month as an ordinal, honouring language, format and gender
\{month\}, \{monthShort\}	Month name in English, full or first three letters
\{monthNum\}	Month number, unpadded
\{year\}	Four-digit year
\{weekday\}, \{weekdayShort\}	Weekday name in English, full or first three letters
\{hour\}, \{minute\}, \{second\}	Zero-padded, two digits

Month and weekday names are always English, whatever language is set to — only the day ordinal is localized.

warning

When processing strings containing multiple numbers, all numeric values in the text will be converted to ordinals. Use field isolation if you need to convert only specific numbers.

Examples

Basic Number Ordinals

Converting numbers to English ordinals...	{ "position": 23 } - ordinal: field: position target_field: position_ordinal format: suffix
creates ordinal form:	{ "position": 23, "position_ordinal": "23rd" }

Spanish Gendered Ordinals

Using Spanish feminine ordinals...	{ "floor": 3 } - ordinal: field: floor language: es gender: feminine format: both target_field: floor_description
generates Spanish feminine ordinal:	{ "floor": 3, "floor_description": "3ª (tercera)" }

Date Formatting with Ordinals

Rendering a date through a marker template...	{ "event_date": "2024-01-15T10:30:00Z" } - ordinal: field: event_date date_format: "\{day\} of \{month\}, \{year\}" target_field: formatted_date
substituting each marker, with the day rendered as an ordinal:	{ "event_date": "2024-01-15T10:30:00Z", "formatted_date": "15th of January, 2024" }

Word Form Ordinals

Converting to word form ordinals...	{ "rank": 1 } - ordinal: field: rank format: word case: title target_field: rank_word
creates word form:	{ "rank": 1, "rank_word": "First" }

Superscript HTML Format

Generating HTML superscript ordinals...	{ "place": 42 } - ordinal: field: place superscript: true target_field: html_ordinal
outputs HTML formatted ordinal:	{ "place": 42, "html_ordinal": "42<sup>nd</sup>" }

Multi-Language Processing

Processing French ordinals with proper formatting...	{ "chapter": 21 } - ordinal: field: chapter language: fr format: suffix case: lower target_field: chapitre
generates French ordinal:	{ "chapter": 21, "chapitre": "21ᵉ" }

String Number Conversion

Converting numbers within text strings...	{ "message": "User completed level 5 on attempt 3" } - ordinal: field: message target_field: ordinal_message
converts embedded numbers:	{ "message": "User completed level 5 on attempt 3", "ordinal_message": "User completed level 5th on attempt 3rd" }