The Global Clock: Localizing Dates with JavaScript

Table of Contents

1. Challenge

   Step 1: Understand the date display problem

   Welcome to The Global Clock: Localizing Dates with JavaScript Code Lab.

   Showing one instant to people around the world is less about changing the data and more about presenting it in a form each audience can read naturally. In this lab, you will work on a global event display where clarity depends on locale-aware dates, times, and time zones.

   You'll also build a command-line schedule that formats shared event timestamps for New York, London, and Tokyo and organizes the presentation logic into reusable helpers. To begin, you'll distinguish the stored instant from its regional display so later changes preserve the event data.

   The application directory already contains the project with event data, rendering functions, and formatter stubs ready for your implementations. You will be responsible for modifying code within the src subdirectory.

   ---

   Note: If you're feeling stuck, check out the matching solution/stepN/ folder for the step you're on to see a working implementation. Give it a try on your own first. The solution folder is your safety net, not your starting point.

   Lastly, you can manually run a validation test in the terminal with the command ./runTest.sh taskX if you'd like to view the results in a larger window. Replace taskX with the specific task number, of which there are 10 in this lab.

2. Challenge

   Step 2: Format dates with `Intl.DateTimeFormat`

   With the difference between stored timestamps and displayed values clear, you can make the schedule readable without altering its source data. You will build formatDateTime in stages, then route event rendering through it. This gives you a reusable locale-aware date and time path based on Intl.DateTimeFormat. ### Locale-aware calendar formatting

   An ISO timestamp identifies an instant, while Intl.DateTimeFormat controls how that instant is presented for a locale. Parse the timestamp with Date, configure the formatter with calendar fields such as year, month, and day, and format the parsed value. The general shape is new Intl.DateTimeFormat(languageTag, displayOptions).format(new Date(timestampText)), where the identifiers are placeholders for runtime inputs. ### Combined date and time options

   An Intl.DateTimeFormat options object can describe calendar and clock fields together. Adding hour and minute fields lets the formatter follow the locale's ordering, punctuation, and hour-cycle conventions. Prefer formatter options over manually assembling numeric date and time pieces. ### Formatter composition in a renderer

   A renderer should compose the formatter rather than repeat date-formatting rules. Array.map() can transform each event into a display line before join() builds the multiline schedule. A placeholder pattern is records.map((record) => formatValue(record.value, region)).join(separator).

3. Challenge

   Step 3: Compare locales and time zones

   Readable dates now flow through the renderer, which lets audience settings vary independently from event data. You will define regional profiles, add time-zone formatting, and compose single-audience sections into a grouped schedule. This makes the role of locale versus time zone concrete while keeping one source instant. ### Locale and time-zone profiles

   Audience profiles keep regional presentation settings as data instead of scattering them through rendering logic. Each profile associates a display label and locale with an IANA time-zone identifier. A placeholder profile has the shape { label: "Region", locale: "xx-YY", timeZone: "Area/City" }. ### Locale versus time zone

   A locale controls language and display conventions, while a time zone controls which local clock time represents an instant. The same Date value can therefore produce different output when only the formatter's timeZone option changes. Prefer IANA identifiers such as Area/City because they encode regional time-zone rules. ### Rendering for one audience

   A focused rendering helper can bind a collection of events to one audience's presentation settings. It should use the profile's locale and time zone for every timestamp while keeping the source events unchanged. A placeholder transformation is items.map((item) => formatForContext(item, profile)). ### Mapping profiles to sections

   Once one helper renders a single audience section, mapping all profiles through that helper scales the same behavior across the schedule. Joining the resulting strings creates one grouped display while leaving both input arrays unchanged. A placeholder pattern is profiles.map((profile) => renderSection(items, profile)).join(sectionBreak).

4. Challenge

   Step 4: Create reusable formatter helpers

   Audience-specific schedules are in place, so you can centralize how formatters and event lines are constructed. You will extract a formatter factory, add an event display helper, and delegate renderer work to that helper. This leaves each function with a focused responsibility and makes presentation rules easier to reuse. ### Formatter factories

   A factory packages formatter configuration into a reusable Intl.DateTimeFormat instance. Returning the configured instance lets callers use its format() method without rebuilding the options themselves. A placeholder factory has the shape (settings) => new Formatter(settings). ### Event-line formatting

   Formatting one event line is a distinct responsibility from assembling an audience section. A dedicated helper can combine event data, audience settings, and the existing date-time formatter into a consistent line. Keeping the bullet prefix in that helper gives every renderer caller the same presentation. ### Delegating display responsibilities

   Delegation keeps the schedule renderer focused on section structure while a specialized helper owns event-line formatting. Importing and calling that helper also prevents the two modules from developing separate display rules. A placeholder pattern is items.map((item) => renderItem(item, context)). Congratulations on completing the global event display!

   You built a command-line schedule that presented shared event timestamps for New York, London, and Tokyo without changing their stored instants. You used locales and IANA time zones to produce audience-specific date and time strings.

   You also separated formatter creation, event-line formatting, and schedule rendering into reusable helpers. Those boundaries give you a transferable pattern for keeping internationalized presentation logic consistent across a JavaScript application.