Skip to main content
Version: 4.0 (next)

Words-to-number engine reference

Orientation​

Choose a parser engine only after mapping the language's token normalization, cardinal composition, scales, and ordinal behavior. Render-side number words use a separate engine catalogue.

Example​

surfaces:
  number:
    parse:
      engine: 'token-map'
      normalizationProfile: 'LowercaseRemovePeriods'
      cardinalMap:
        one: 1
        two: 2

Words-To-Number Engines​

Every released locale root declares decimalMarker beside engine under surfaces.number.parse. WordsToDecimalNumber parses the integer and fractional digit phrases with that locale's existing words-to-number engine. Whitespace-delimited engines require token boundaries around the marker and fractional digits; East Asian positional engines may use their authored joined forms. Regional variants inherit only through their declared same-language, same-script variantOf chain.

compound-scale​

Fields:

  • cardinalMap
  • tens
  • largeScales
  • ignoredToken
  • negativePrefixes
  • ordinalNumberToWordsKind
  • sequenceMultiplierThreshold

Notes:

  • cardinalMap maps plain tokens to values.
  • tens is the ordered tens vocabulary used by the shared parser.
  • largeScales is the ordered scale-token list.
  • ignoredToken is a single token skipped during parsing.
  • ordinalNumberToWordsKind links to a number.words profile whose ordinal outputs can be mined for parsing support.
  • sequenceMultiplierThreshold changes how adjacent values are multiplied versus added.
  • ordinalNumberToWordsKind may use self when ordinal parsing should be derived from the locale's own number.words block at generation time.

contracted-scale​

Fields:

  • minusWord
  • cardinalMap

east-asian-positional​

Fields:

  • digits
  • smallUnits
  • largeUnits
  • negativePrefixes
  • ordinalPrefix
  • ordinalSuffix
  • ordinalMap

greedy-compound​

Fields:

  • cardinalMap
  • negativePrefixes
  • ordinalAbbreviationSuffixes
  • ordinalNumberToWordsKind
  • charactersToRemove
  • charactersToReplaceWithSpace
  • textReplacements
  • lowercase
  • removeDiacritics

Notes:

  • This engine normalizes aggressively, then greedily matches compound pieces.
  • textReplacements is an ordered replacement table applied before tokenization.
  • charactersToRemove and charactersToReplaceWithSpace should stay narrowly scoped to normalization, not spelling correction.

inverted-tens​

Fields:

  • cardinalMap
  • unitMap
  • tensTokens
  • tensLinker
  • scaleTokens
  • ordinalMap
  • ordinalNumberToWordsKind
  • negativePrefixes
  • ignoredTokens
  • ordinalSuffixes
  • unitPartReplacements
  • allowInvariantIntegerInput

linking-affix​

Fields:

  • cardinalMap
  • teenPrefix
  • teenBaseValue
  • linkedSuffixes
  • ignoredTokens
  • negativePrefixes

scale-leading-compound (parser)​

Fields:

  • unitsMap
  • tensMap
  • scales
  • conjunctionWord
  • terminalRemainderConjunctionWord
  • minusWord
  • ordinalPrefix
  • ordinalSuffix
  • ordinalMap

Nested scales fields:

  • value
  • name

Notes:

  • This parser is the number.parse counterpart to the scale-leading renderer used by Hausa (ha) and Swahili (sw). It accepts scale names before their count tokens and tokenizes multi-word unit and scale phrases.
  • Unlike the render-side unitsMap and tensMap arrays, parser maps are token-to-number dictionaries. Include every spelling variant that should parse.
  • scales must be ordered from larger to smaller values, and each larger value must be divisible by the next smaller value.
  • conjunctionWord joins tens-plus-units and terminal remainders. terminalRemainderConjunctionWord can override the terminal-remainder phrase and falls back to conjunctionWord when omitted.
  • Exact ordinal phrases belong in ordinalMap; otherwise the parser can strip ordinalPrefix/ordinalSuffix and parse the remaining cardinal phrase.

prefixed-tens-scale​

Fields:

  • cardinalMap
  • tensMap
  • scales
  • prefixedTens
  • negativePrefixes

suffix-scale​

Fields:

  • cardinalMap
  • bareScaleMap
  • scales
  • hundredSingularToken
  • hundredPluralToken
  • tensSuffixToken
  • teenSuffixToken
  • negativePrefixes

token-map​

Fields:

  • normalizationProfile
  • cardinalMap
  • ordinalMap
  • ordinalScaleMap
  • gluedOrdinalScaleSuffixes
  • gluedScaleSuffixes
  • compositeScaleMap
  • negativePrefixes
  • negativeSuffixes
  • ordinalPrefixes
  • ignoredTokens
  • leadingTokenPrefixesToTrim
  • multiplierTokens
  • tokenSuffixesToStrip
  • ordinalAbbreviationSuffixes
  • teenSuffixTokens
  • hundredSuffixTokens
  • allowTerminalOrdinalToken
  • useHundredMultiplier
  • allowInvariantIntegerInput
  • teenBaseValue
  • hundredSuffixValue
  • unitTokenMinValue
  • unitTokenMaxValue
  • hundredSuffixMinValue
  • hundredSuffixMaxValue
  • scaleThreshold
  • ordinalGenderVariant
  • ordinalNumberToWordsKind

Notes:

  • This is the most declarative parsing engine.
  • ordinalMap holds exact ordinal tokens.
  • ordinalScaleMap holds ordinal scale words such as "millionth".
  • gluedOrdinalScaleSuffixes supports glued ordinal forms where the scale is expressed as a suffix.
  • gluedScaleSuffixes supports glued cardinal forms where a cardinal count is immediately followed by a scale suffix.
  • compositeScaleMap supports composite multi-token scales.
  • ordinalGenderVariant is validated as token-map metadata when present. Do not rely on it by itself to create parseable ordinal tokens; token-map parsing recognizes explicit ordinal maps and the prefix/suffix rules emitted into TokenMapWordsToNumberRules.
  • ordinalNumberToWordsKind: 'self' is an authoring alias for the current locale's generated number-to-words profile. The generator normalizes that alias to the concrete locale profile key, but token-map locales should still author the ordinal lexemes they need to parse in ordinalMap, ordinalScaleMap, gluedOrdinalScaleSuffixes, or compositeScaleMap unless the token-map emitter is extended to synthesize additional ordinal maps.
  • normalizationProfile is the first field to pick for a new locale because it determines how aggressively the generated parser cleans incoming text before tokenization. The same normalization is applied to explicit ordinal tokens.
  • cardinalMap is the authoritative literal-token dictionary for this engine. If a cardinal token should parse, it must appear here; ordinal tokens must appear in one of the explicit ordinal/scale maps or be covered by the documented prefix/suffix rules.

vigesimal-compound​

Fields:

  • cardinalMap
  • ordinalMap
  • negativePrefixes
  • ignoredTokens
  • vigesimalLeadingToken
  • vigesimalFollowerTokens
  • vigesimalValue
  • teenLeaderToken
  • teenLeaderBases

Pitfall​

A number-to-words engine does not imply a matching parser. Prove cardinal and ordinal parsing independently, including normalization and ambiguous tokens.

Version notes​

These parser engines are the accepted main/preview contracts. Historical branches may expose fewer engines or handwritten converters.