Skip to content
Multigrid

Why AI Gets the Week Number Wrong Across Locales

9 min read · updated August 11, 2026

Your report says week 53. The ERP says week 1. Neither is broken: they are applying two different, both correct, definitions of which week of the year a date falls in, and the definitions disagree for a few days every January.

Two systems, two answers

Week numbering needs two parameters, and every convention is a choice of both: which day starts a week, and how many days of the new year a week must contain to count as week 1. The Unicode CLDR models exactly this pair as firstDay and minDays in its territory week data. Pick Monday and 4 and you have ISO 8601. Pick Sunday and 1 and you have the common US convention. Both are in wide use, both are implemented in mainstream libraries, and the default differs by platform.

For roughly fifty weeks of the year they agree to within a small offset. Around the turn of the year they can differ by a full week and, more disruptively, disagree about which year the week belongs to.

The ISO 8601 rule

ISO 8601, published by the International Organization for Standardization (the current edition is ISO 8601-1:2019), defines it as follows:

  • The week begins on Monday and ends on Sunday.
  • Week 1 is the week containing the first Thursday of January — equivalently, the week containing 4 January, equivalently the first week with at least four of its days in the new year. All three phrasings pick the same week; the minDays = 4 formulation is the one in the data.
  • Every week therefore belongs entirely to one ISO week-year, and a year has either 52 or 53 weeks.

The consequence people find counter-intuitive is that up to three days of late December can belong to week 1 of the following year, and up to three days of early January can belong to week 52 or 53 of the previous one. The ISO notation makes it explicit: 2026-W01-3 is the Wednesday of ISO week 1 of 2026, whatever calendar month it falls in.

A year has 53 ISO weeks when 1 January is a Thursday, or when it is a Wednesday in a leap year. 2026 opens on a Thursday, so 2026 is a 53-week year — which matters below.

The US and broadcast rules

The common North American convention starts the week on Sunday and takes week 1 as the week containing 1 January — minDays = 1. A consequence is that week 1 can be a single day long: if 1 January falls on a Saturday, week 1 is that Saturday alone, and week 2 starts the next day.

A third convention exists in media planning: the broadcast calendar, where weeks run Monday to Sunday and the broadcast year begins on the Monday on or before 1 January, giving twelve months of four or five whole weeks. It is not ISO and it is not the US civil convention, and media-agency reporting that quotes “week 32” is often using it.

Two dates, worked both ways

Take Wednesday 31 December 2025. Its Monday-start week runs Monday 29 December 2025 to Sunday 4 January 2026. Does that week contain 4 January? Yes — it ends on it. Its Thursday is 1 January 2026. So under ISO:

31 Dec 2025 (Wednesday)
  ISO week runs   Mon 29 Dec 2025 - Sun 4 Jan 2026
  contains 4 Jan  yes  -> this is week 1
  ISO value       2026-W01-3     (week 1 of 2026, in December)

  US convention   week starts Sun 28 Dec 2025;
                  week 1 of 2025 began Sun 29 Dec 2024
                  -> 2025, week 53

Same date. ISO says week 1 of 2026; the US convention says week 53 of 2025. Not merely a different number — a different year.

Now take Friday 1 January 2027, which is in the other direction:

1 Jan 2027 (Friday)
  ISO week runs   Mon 28 Dec 2026 - Sun 3 Jan 2027
  contains 4 Jan  no   -> not week 1 of 2027
  2026 opened on a Thursday, so 2026 has 53 ISO weeks
  ISO value       2026-W53-5     (week 53 of 2026, in January)

  US convention   week starts Sun 27 Dec 2026, contains 1 Jan
                  -> 2027, week 1

A New Year’s Day that ISO files under the previous year and the US convention files under week 1 of the new one. If two systems join on a week label, these are the rows that will not match, and they are a handful of rows a year, in the period when nobody is looking closely.

The week-year is a different field

Because an ISO week can straddle the boundary, the year that goes with a week number is not the calendar year. It is a separate field, and every serious date library distinguishes them — usually as lowercase y for the calendar year and uppercase Y for the week-based year.

// the classic bug
new SimpleDateFormat("YYYY-MM-dd").format(dec29_2025);  // "2026-12-29"
new SimpleDateFormat("yyyy-MM-dd").format(dec29_2025);  // "2025-12-29"

Uppercase YYYY asks for the week-based year and gets 2026, because 29 December 2025 is in ISO week 1 of 2026 — and then pairs it with a December month, producing a date a year in the future. This is not a Java quirk; the same distinction exists in the CLDR date pattern syntax that ICU, java.time, Swift and most other implementations follow, so the same one-character typo produces the same bug across languages. It surfaces every year in the last week of December and is invisible for the other fifty-one.

The rule is simple once seen: use Y only next to w, as in YYYY-'W'ww, and never next to a month.

Getting a correct week number

  • Decide which convention you are in and write it down. “Week numbers in this system are ISO 8601” is a one-sentence decision that prevents a class of reconciliation failures. If you exchange week numbers with anyone, put the convention in the interface documentation.
  • Label it in the UI. Showing “W01” alone is ambiguous to a user whose payroll system uses the other rule. “ISO week 1” costs four characters.
  • Do not ask a model to compute it. Week numbering is a small arithmetic problem with two boundary conditions, and a model will produce a confident answer that is right for most of the year. Use the platform: java.time with WeekFields.ISO, a date library’s ISO week function, or ICU with the appropriate firstDay and minDays.
  • Test the four dates that matter — 28 December to 4 January, in a 53-week year and a 52-week one. Any implementation that is wrong is wrong there and correct everywhere else, so a test suite of mid-year dates proves nothing.

The related display question — which column a date sits under in a rendered calendar — uses the firstDay half of the same data and is covered in why AI calendars default to the wrong start of week. The two bugs look identical to a user and have different fixes.

Related