Skip to content

Narrative & i18n

Calculon generates localized turn-by-turn instructions in 34 languages using the rust-i18n crate.

Supported languages

Code Language Code Language
en-US English (US) ja-JP Japanese
en-GB English (UK) ko-KR Korean
en-AU English (AU) hi-IN Hindi
en-US-x-pirate Pirate English vi-VN Vietnamese
fr-FR French ar-SA Arabic
de-DE German tr-TR Turkish
es-ES Spanish pl-PL Polish
it-IT Italian cs-CZ Czech
pt-BR Portuguese (BR) hu-HU Hungarian
pt-PT Portuguese (PT) ro-RO Romanian
nl-NL Dutch bg-BG Bulgarian
ru-RU Russian el-GR Greek
uk-UA Ukrainian et-EE Estonian
sv-SE Swedish sk-SK Slovak
nb-NO Norwegian sl-SI Slovenian
da-DK Danish mn-MN Mongolian
fi-FI Finnish ca-ES Catalan

Set the language per request with the language field:

{
  "locations": [...],
  "language": "fr-FR"
}

Maneuver types

The maneuver builder groups path edges into high-level instructions. Each maneuver has a numeric type:

Type Name Description
1 Start Begin driving in a cardinal direction
2 StartRight Begin with a right turn
3 StartLeft Begin with a left turn
4 Destination Arrive at destination
5 DestinationRight Arrive on the right
6 DestinationLeft Arrive on the left
7 Becomes Road name changes without a turn
8 Continue Continue straight
9 SlightRight Bear right
10 Right Turn right
11 SharpRight Sharp right
12 UturnRight U-turn (right-side driving)
13 UturnLeft U-turn (left-side driving)
14 SharpLeft Sharp left
15 Left Turn left
16 SlightLeft Bear left
17 RampStraight Take ramp straight
18 RampRight Take ramp right
19 RampLeft Take ramp left
20 ExitRight Exit right
21 ExitLeft Exit left
22 StayStraight Stay straight at fork
23 StayRight Stay right at fork
24 StayLeft Stay left at fork
25 Merge Merge onto road
26 RoundaboutEnter Enter roundabout
27 RoundaboutExit Exit roundabout (with ordinal: 1st-10th exit)
28 FerryEnter Board ferry
29 FerryExit Disembark ferry

How maneuver building works

The maneuver builder is a stateful algorithm that walks the path edge by edge:

  1. Accumulate edges with the same street name and straight heading into a single maneuver
  2. Trigger a new maneuver on:
    • Name change (except inside a roundabout)
    • Roundabout entry or exit
    • Ramp entry or exit
    • Ferry entry or exit
    • U-turn detection
    • Turn type change
  3. Classify each maneuver based on heading delta and context (ramp, roundabout, fork)
  4. Track roundabout exits by counting name changes inside the roundabout

Narrative rendering

Each maneuver type has a dedicated renderer that produces localized text:

Maneuver Example output (en-US)
Start "Drive north on Main Street."
Right "Turn right onto Oak Avenue."
SlightLeft "Bear left onto Highway 101."
RoundaboutExit "Take the 2nd exit onto Rue de Rivoli."
Merge "Merge onto A7."
Destination "You have arrived at your destination."
FerryEnter "Take the ferry."

Template variables used in locale files:

  • %{street} — street name(s) joined with /
  • %{direction} — cardinal direction (north, northeast, etc.)
  • %{relative_direction} — left or right
  • %{ordinal_value} — 1st through 10th (for roundabout exits)

Adding a new language

  1. Copy locales/en-US.yml to locales/{code}.yml
  2. Translate all template strings, keeping %{variable} placeholders intact
  3. The new locale is automatically available — rust-i18n picks it up at compile time