Lesson 18 • Intermediate

Dates & Internationalization 📅

By the end of this lesson you'll create, read, and format dates correctly — and show times, currencies, and "3 hours ago" the way each user's country expects.

What You'll Learn in This Lesson

✓Create and parse dates safely with the Date object
✓Read and change parts (year, month, day, hour)
✓Use timestamps to do bug-free date arithmetic
✓Format dates per locale with Intl.DateTimeFormat
✓Format currency with Intl.NumberFormat
✓Show relative time and handle time zones

📚 Prerequisites: You should be comfortable with variables and functions. Knowing how objects and methods work will help, since a date is an object with methods.

💡 Running Code Locally: While this online editor runs real JavaScript, some advanced examples may have limitations. For the best experience:

Download Node.js to run JavaScript on your computer
Use your browser's Developer Console (Press F12) to test code snippets
Create a .html file with <script> tags and open it in your browser

🕰️ Real-World Analogy: A Date is like the single counter on a stopwatch that started ticking at midnight on Jan 1, 1970 (UTC):

• Inside, it only stores one number — how many milliseconds have ticked by
• The clock on your wall (local time) is just that number shown in your zone
• Two people in different countries read the same instant as different wall-clock times
• Intl is the translator that prints that instant the way each country writes it

1️⃣ The Date Object: One Number Underneath

A Date is JavaScript's built-in type for a moment in time. It does not store a time zone. It stores a single number: the milliseconds since the epoch (midnight, Jan 1 1970, UTC). Every other thing you see — local time, ISO strings, formatted text — is calculated from that number.

You create "now" with new Date(), read the raw number with getTime(), and get a universal string with toISOString().

What a Date Really Stores

See the single number behind every Date

Try it Yourself »

JavaScript

// new Date() with no arguments = right now
const now = new Date();

console.log(now.getTime());      // ✅ Expected output: a big number, e.g. 1750000000000 (ms since 1970)
console.log(typeof now.getTime()); // ✅ Expected output: number

// toISOString() always prints in UTC with a trailing "Z"
console.log(new Date(0).toISOString()); // ✅ Expected output: 1970-01-01T00:00:00.000Z

// The same instant, two views:
const launch = new Date("2025-06-16T12:00:00Z");
console.log(launch.getTime());   //
...

2️⃣ Creating & Parsing Dates Safely

There are three reliable ways to build a date. The safest take the guesswork out of which time zone JavaScript should assume. Notice the month is zero-indexed in the numeric constructor — 0 is January, 11 is December.

Three Ways to Create a Date

Explicit, ISO, and numeric constructors

Try it Yourself »

JavaScript

// 1) ISO string with "Z" = unambiguous UTC (recommended for stored data)
const iso = new Date("2025-01-01T09:30:00Z");
console.log(iso.toISOString()); // ✅ Expected output: 2025-01-01T09:30:00.000Z

// 2) Date.UTC(year, monthIndex, day, ...) returns a timestamp in UTC
const utc = new Date(Date.UTC(2025, 0, 1)); // month 0 = January!
console.log(utc.toISOString()); // ✅ Expected output: 2025-01-01T00:00:00.000Z

// 3) Numeric constructor uses LOCAL time (handy, but zone-dependent)
const local = 
...

3️⃣ Reading & Changing Parts of a Date

Each piece has a get method and a matching set method: getFullYear(), getMonth(), getDate() (day of month), getDay() (day of week, 0 = Sunday), getHours(), and so on. The set methods mutate the date in place and conveniently roll over — adding a day to Jan 31 lands on Feb 1.

Get and Set Date Parts

Read fields and let set methods roll over

Try it Yourself »

JavaScript

const d = new Date("2025-01-31T00:00:00Z");

console.log(d.getUTCFullYear()); // ✅ Expected output: 2025
console.log(d.getUTCMonth());    // ✅ Expected output: 0  (January is 0)
console.log(d.getUTCDate());     // ✅ Expected output: 31

// set methods MUTATE and roll over automatically
d.setUTCDate(d.getUTCDate() + 1); // 31 + 1 spills into the next month
console.log(d.toISOString());     // ✅ Expected output: 2025-02-01T00:00:00.000Z

🎯 Your Turn #1 — Build a Birthday

Remember: the month in Date.UTC() is zero-indexed. Fill in the blanks.

🎯 YOUR TURN — Make a date

Fill in the blanks marked with ___

Try it Yourself »

JavaScript

// 🎯 YOUR TURN — fill in the blanks marked with ___

// 1) Build December 25, 2025 at midnight UTC.
//    Months are zero-indexed, so December is 11.
const xmas = new Date(Date.UTC(2025, ___, 25)); // 👉 replace ___ with the month index for December

// 2) Read the day of the month back out.
const day = xmas.getUTCDate(); // 👉 nothing to change here, just observe

console.log(xmas.toISOString()); // ✅ Expected output: 2025-12-25T00:00:00.000Z
console.log(day);                // ✅ Expected outp
...

4️⃣ Timestamps: Bug-Free Date Math

A timestamp is just that millisecond number. Because it's plain arithmetic, adding fixed durations (minutes, hours) is reliable. Date.now() gives the current timestamp directly. To add calendar units like days or months, prefer the set methods, which respect month lengths and daylight saving.

Math with Timestamps

Add durations and measure gaps

Try it Yourself »

JavaScript

const start = new Date("2025-06-16T12:00:00Z");

// Add 90 minutes by working in milliseconds
const later = new Date(start.getTime() + 90 * 60 * 1000);
console.log(later.toISOString()); // ✅ Expected output: 2025-06-16T13:30:00.000Z

// Difference between two dates, in days
const a = new Date("2025-01-01T00:00:00Z");
const b = new Date("2025-01-08T00:00:00Z");
const days = (b.getTime() - a.getTime()) / (1000 * 60 * 60 * 24);
console.log(days); // ✅ Expected output: 7

// Add 3 calendar months sa
...

5️⃣ Formatting with Intl.DateTimeFormat

Never build a display string by hand. Intl.DateTimeFormat takes a locale (like "en-US" or "en-GB") and an options object, then prints the date the way that country writes it — correct order, month names, and 12- vs 24-hour clock. Pass timeZone to control which zone it renders in.

Locale-Aware Date Formatting

Same instant, formatted for different countries

Try it Yourself »

JavaScript

const d = new Date("2025-06-16T18:05:00Z");

// US puts the month first; UK puts the day first
console.log(new Intl.DateTimeFormat("en-US").format(d)); // ✅ Expected output: 6/16/2025
console.log(new Intl.DateTimeFormat("en-GB").format(d)); // ✅ Expected output: 16/06/2025

// Spell it out with options + a fixed time zone
const long = new Intl.DateTimeFormat("en-GB", {
  weekday: "long",
  day: "numeric",
  month: "long",
  year: "numeric",
  timeZone: "UTC",
}).format(d);
console.log(long); // 
...

Intl.NumberFormat — Money & Numbers

The same family formats numbers. With style: "currency" and a currency code, Intl.NumberFormat adds the right symbol, decimals, and grouping for the locale. This is how you show prices correctly to a global audience.

Currency and Number Formatting

Format money for different locales

Try it Yourself »

JavaScript

const price = 1234.5;

// US dollars
console.log(new Intl.NumberFormat("en-US", {
  style: "currency", currency: "USD",
}).format(price)); // ✅ Expected output: $1,234.50

// British pounds
console.log(new Intl.NumberFormat("en-GB", {
  style: "currency", currency: "GBP",
}).format(price)); // ✅ Expected output: £1,234.50

// Plain grouped number
console.log(new Intl.NumberFormat("en-US").format(1000000)); // ✅ Expected output: 1,000,000

7️⃣ Intl.RelativeTimeFormat — "3 hours ago"

For feeds and notifications, show relative time. Negative numbers are the past, positive are the future. With numeric: "auto" it even says "yesterday" and "tomorrow" where a language has those words.

Relative Time

Human-friendly time differences

Try it Yourself »

JavaScript

const rtf = new Intl.RelativeTimeFormat("en", { numeric: "auto" });

console.log(rtf.format(-3, "hour")); // ✅ Expected output: 3 hours ago
console.log(rtf.format(2, "day"));   // ✅ Expected output: in 2 days
console.log(rtf.format(-1, "day"));  // ✅ Expected output: yesterday
console.log(rtf.format(1, "week"));  // ✅ Expected output: next week

🎯 Your Turn #2 — Price Tag

Use Intl.NumberFormat to print a euro price for a French audience.

🎯 YOUR TURN — Format currency

Fill in the blanks marked with ___

Try it Yourself »

JavaScript

// 🎯 YOUR TURN — fill in the blanks marked with ___

const amount = 49.99;

// 1) Choose the currency code for euros (3 letters, uppercase).
const euros = new Intl.NumberFormat("de-DE", {
  style: "currency",
  currency: "___", // 👉 replace ___ with the ISO code for the euro
}).format(amount);

console.log(euros); // ✅ Expected output: 49,99 €  (German formats euro after the number)

🧩 Mini-Challenge — Event Countdown

Now with the scaffolding removed. Work from the comment outline only.

🧩 MINI-CHALLENGE — Days until an event

Only a comment outline — you write the code

Try it Yourself »

JavaScript

// 🧩 MINI-CHALLENGE: Days until New Year 2026
// 1. Create a Date for the event: 2026-01-01 at midnight UTC (use an ISO string with "Z").
// 2. Create a Date for a fixed "today": 2025-12-16 at midnight UTC.
// 3. Subtract their getTime() values and divide by the ms in one day (1000 * 60 * 60 * 24).
// 4. Log the whole number of days using Math.round(...).
//
// ✅ Expected output: 16

// your code here

Time Zones in Practice

Store the instant in UTC; convert only when you display. Pass an IANA zone name (like "America/New_York") to timeZone and the formatter handles the offset and daylight saving for you.

One Instant, Many Clocks

Render a UTC moment in several zones

Try it Yourself »

JavaScript

const instant = new Date("2025-06-16T16:00:00Z");

const show = (zone) =>
  new Intl.DateTimeFormat("en-GB", {
    hour: "2-digit",
    minute: "2-digit",
    timeZone: zone,
  }).format(instant);

console.log("London:", show("Europe/London"));     // ✅ Expected output: London: 17:00 (BST in summer)
console.log("New York:", show("America/New_York")); // ✅ Expected output: New York: 12:00
console.log("Tokyo:", show("Asia/Tokyo"));           // ✅ Expected output: Tokyo: 01:00

// Discover the visi
...

📦 A Note on Date Libraries: The built-in Date is fine for the basics, but it is mutable and quirky. Two things worth knowing:

• date-fns — a popular toolkit of small, pure functions (addDays, format, differenceInDays) that never mutate your dates.
• Temporal — the new standard built into JavaScript, designed to replace Date with immutable, time-zone-aware types. It's rolling out now; learn it when it lands in your runtime.

Common Errors & Fixes

1️⃣ Months are off by one

new Date(2025, 12, 1); // 👈 month 12 rolls into JANUARY 2026!
new Date(2025, 11, 1); // ✔ December: months are 0-indexed (0–11)

2️⃣ "One day off" from an ambiguous string

new Date("2025-01-01");        // parsed as UTC midnight, shown locally → may read Dec 31
new Date("2025-01-01T00:00:00"); // ✔ add a time, or use Date.UTC(2025, 0, 1)

3️⃣ set methods mutate the original

const start = new Date("2025-01-01T00:00:00Z");
const end = start;          // 👈 same object, not a copy!
end.setUTCDate(10);         // this also changes "start"
const copy = new Date(start); // ✔ clone first, then mutate the copy

4️⃣ Invalid input gives "Invalid Date", not an error

const d = new Date("not a date");
console.log(isNaN(d.getTime())); // ✔ true → check this before trusting the date

5️⃣ Forgetting the time zone when formatting

// Output depends on the server/visitor's zone — flaky in tests
new Intl.DateTimeFormat("en-GB").format(d);
// ✔ pin it: pass { timeZone: "UTC" } (or the zone you mean)

Quick Reference — Dates & Intl

Task	Code
Now	`new Date()` / `Date.now()`
From ISO (UTC)	`new Date("2025-06-16T12:00:00Z")`
From parts (UTC)	`new Date(Date.UTC(2025, 0, 1))`
Raw timestamp	`d.getTime()`
Universal string	`d.toISOString()`
Read part	`d.getUTCFullYear()`, `getUTCMonth()` (0–11)
Format date	`new Intl.DateTimeFormat("en-GB", {…}).format(d)`
Format currency	`new Intl.NumberFormat("en-US", { style: "currency", currency: "USD" })`
Relative time	`new Intl.RelativeTimeFormat("en", { numeric: "auto" }).format(-3, "hour")`

Frequently Asked Questions

Why is the month 11 for December?

JavaScript months are zero-indexed: January is 0 and December is 11. Always subtract 1 when you build a date from a human month number, and add 1 when you read getMonth() back for display.

Why does new Date('2025-01-01') sometimes show December 31?

A date-only string like '2025-01-01' is parsed as midnight UTC, then displayed in your local time. If you are behind UTC (e.g. New York), midnight UTC is the evening of the day before, so it looks 'one day off'. Add an explicit time and zone, or use Date.UTC().

What's the difference between getTime() and Date.now()?

Both return milliseconds since the Unix epoch (Jan 1 1970 UTC). Date.now() is a static method that gives the current time without creating a Date object; getTime() is called on an existing Date instance.

How do I format money for different countries?

Use Intl.NumberFormat with style: 'currency' and a currency code like 'USD' or 'GBP'. It picks the right symbol, decimal separators, and digit grouping for the locale you pass.

Should I use a date library like date-fns instead?

For simple formatting and arithmetic the built-in Date plus Intl is enough. For heavy parsing, time-zone math, or durations, a library such as date-fns is safer. The upcoming Temporal API aims to replace Date entirely with an immutable, time-zone-aware design.

Lesson Complete — Dates & Internationalization!

✅ A Date is one number: milliseconds since the 1970 UTC epoch
✅ Months are zero-indexed; prefer ISO strings with Z or Date.UTC()
✅ Do math with timestamps; use set methods for calendar units
✅ Format with Intl.DateTimeFormat, Intl.NumberFormat, and Intl.RelativeTimeFormat
✅ Store in UTC, display in the user's time zone

You can now handle dates the way production apps do — accurately, and in any language. 🌍