\n\n\n\n�The sun never sets on your users, but your code still sleeps in one timezone.�
Why timezone and locale sneak into every feature
\n\n\n\nWe are shipping software to browsers and phones from everywhere. The App Store just opened and folks in Tokyo, Madrid, and S�o Paulo are signing up the same day. That is great for growth and also a magnet for sneaky bugs. The two most silent troublemakers I keep running into are timezone and locale. These are not shiny features. They are the wiring behind everyday things like timestamps on receipts, the total on an invoice, or the date you show in an email subject. Get them wrong and you get chargebacks, angry tickets, and long nights.
\n\n\n\nThis is a hands on look at Java i18n from real projects. The code examples use Java 6, servlets, JSP, Spring, and friends that many of us run today. The lessons are the kind that survive framework fashion. If your app has users outside your hometown, this matters.
\n\n\n\nThe night a clock jump ate our jobs
\n\n\n\nWe had a daily billing job set for 02:15 server time. It ran fine until a spring forward in the south flipped the clock and that time never existed. No job ran, no emails went out, and we found out when support woke up to a queue full of confused customers. A week later the opposite happened. Clocks moved back, the 01:30 hour happened twice, and we double charged a tiny slice of users. Same code, two different failures. The culprit was not the job runner. It was us treating local wall time as if it were hard truth.
\n\n\n\nIn another incident, a merchant in Mexico saw totals with a comma for decimals and thought a ten dollar order was a thousand. Their browser locale was es MX, our formatter ignored it, and we printed 1,000 where they expected 1.000. The numbers were right in the database. The display broke trust. That one email thread taught me to never let locale be a footnote.
\n\n\n\nDeep dive 1: Store and move time in UTC
\n\n\n\nYou can avoid most timezone bugs by treating UTC as the only truth for storage and transport. Convert to the user timezone at the edges. That rule looks simple because it is. The tricky part is doing it consistently across app servers, JDBC, and the database.
\n\n\n\nServer default. Set JVM default timezone to UTC on every server. Do not rely on whatever the OS thinks.
\n\n\n\npublic class Bootstrap {\n static {\n java.util.TimeZone.setDefault(java.util.TimeZone.getTimeZone("UTC"));\n }\n}Persist with a UTC Calendar. With JDBC, always pass a UTC calendar when setting or reading timestamps. This avoids surprise conversions.
\n\n\n\nTimeZone utcTZ = TimeZone.getTimeZone("UTC");\nCalendar utc = Calendar.getInstance(utcTZ);\n\n// write\nPreparedStatement ps = conn.prepareStatement(\n "INSERT INTO events(id, occurred_at_utc) VALUES(?, ?)"\n);\nps.setLong(1, id);\nps.setTimestamp(2, new Timestamp(System.currentTimeMillis()), utc);\nps.executeUpdate();\n\n// read\nPreparedStatement q = conn.prepareStatement(\n "SELECT occurred_at_utc FROM events WHERE id = ?"\n);\nq.setLong(1, id);\nResultSet rs = q.executeQuery();\nif (rs.next()) {\n Timestamp ts = rs.getTimestamp(1, utc);\n long epochMillis = ts.getTime();\n}Pick the right column type. In MySQL, DATETIME is naive and stores the string of wall time with no timezone. TIMESTAMP is stored in UTC and converted based on connection settings. Both can be fine if you are consistent. Either set the connection timezone to UTC, or stick to DATETIME and treat values as UTC by contract. In PostgreSQL, use TIMESTAMP WITH TIME ZONE to normalize to UTC.
\n\n\n\nUse ISO 8601 for APIs and logs. Build and parse UTC strings like 2008-07-26T02:21:05Z. Avoid time abbreviations like PST. They are ambiguous across places and seasons.
\n\n\n\nSimpleDateFormat iso = new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss'Z'");\niso.setTimeZone(TimeZone.getTimeZone("UTC"));\n\nString stamp = iso.format(new Date()); // "2008-07-26T02:21:05Z"\nDate parsed = iso.parse("2008-07-26T02:21:05Z");Do not use week year by accident. In Java patterns, Y is week based year. y is calendar year. Using Y can shift into next year around the last week of December. This shows up in reports and invoices. Use y.
\n\n\n\n// Good\nnew SimpleDateFormat("yyyy-MM-dd")\n\n// Risky around year end\nnew SimpleDateFormat("YYYY-MM-dd")Consider Joda Time. The core Date and Calendar APIs are mutable and easy to misuse. Joda gives you an immutable DateTime and a better DateTimeZone model.
\n\n\n\norg.joda.time.DateTime nowUtc = new org.joda.time.DateTime(\n org.joda.time.DateTimeZone.UTC\n);\n\norg.joda.time.DateTime userTime = nowUtc.withZone(\n org.joda.time.DateTimeZone.forID("America/Mexico_City")\n);Deep dive 2: Format and parse with Locale not guesswork
\n\n\n\nLocale is not only language. It is how people write dates, numbers, and currency. Let the platform do the heavy lifting. Never hand roll separators with String.replace.
\n\n\n\nGet the locale from the user. Best is a profile setting. Next best is the Accept Language header. As a fallback, use site default.
\n\n\n\n// Servlet example\nLocale userLocale = request.getLocale(); // from Accept-Language\n// or prefer a stored user preference\n// Locale userLocale = user.getPreferredLocale();Format currency safely. Use NumberFormat with a specific Currency. Do not assume the default for the locale fits your product. Some stores charge in USD globally. Some need ARS or MXN. Choose it.
\n\n\n\nLocale loc = new Locale("es", "AR");\nNumberFormat money = NumberFormat.getCurrencyInstance(loc);\nmoney.setCurrency(java.util.Currency.getInstance("ARS"));\n\nString total = money.format(new BigDecimal("1234.56"));\n// "ARS 1.234,56" for es-ARLocale sensitive dates. For display, build a DateFormat from the user locale. For URLs and storage, stick to ISO 8601 in UTC.
\n\n\n\nLocale loc = Locale.FRANCE;\nDateFormat df = DateFormat.getDateInstance(DateFormat.LONG, loc);\nString shown = df.format(new Date()); // "26 juillet 2008" for fr-FRMessages with parameters. ResourceBundle plus MessageFormat lets translators move words and placeholders as needed. Hard coded string concat breaks in many languages.
\n\n\n\n// messages_es.properties\nwelcome=Hola {0}, tu pedido #{1} llega el {2}\n\n// Java\nResourceBundle rb = ResourceBundle.getBundle("messages", new Locale("es"));\nString msg = MessageFormat.format(\n rb.getString("welcome"),\n user.getFirstName(),\n order.getNumber(),\n DateFormat.getDateInstance(DateFormat.MEDIUM, new Locale("es"))\n .format(order.getEtaDate())\n);Use UTF 8 everywhere. From browser to database. Mismatch here shows as question marks and broken accents.
\n\n\n\n// JSP top\n<%@ page contentType="text/html; charset=UTF-8" pageEncoding="UTF-8" %>\n\n// Servlet\nresponse.setCharacterEncoding("UTF-8");\nrequest.setCharacterEncoding("UTF-8");\n\n// MySQL JDBC URL\n// jdbc:mysql://host/db?useUnicode=true&characterEncoding=UTF-8Right to left text is rare in some apps but not optional if you sell worldwide. Plan for it in CSS by not fixing alignment unless the design demands it. Use logical properties where you can. For content that mixes scripts, insert Unicode bidi marks only when needed.
\n\n\n\nDeep dive 3: DST, schedules, and the Olson database
\n\n\n\nDaylight Saving Time is not just spring forward and fall back. Governments change rules, sometimes with short notice. Your stack learns about these changes from the Olson timezone database, which your OS and JVM bundle. If the rules change and your server does not have the update, your math is wrong for that place.
\n\n\n\nKeep timezone data fresh. On Linux, update the tzdata package with your usual package manager. On Sun JVMs, run the tzupdater tool from Sun. This matters before new seasons in places like Brazil or Australia where rules are not stable.
\n\n\n\nPick zones by region. Use IANA region IDs like America/Buenos_Aires or Europe/Madrid. Do not use short names like CST, which refer to many places with different offsets or rules.
\n\n\n\nScheduling with wall time vs fixed cadence. Some jobs should track the clock on the wall at the user location. The 09:00 newsletter is a good example. Other jobs should run every N minutes from a UTC anchor, like a poller. Treat them differently.
\n\n\n\n- Wall time jobs: store timezone plus local time. Recompute the next fire time with the zone rules.
- Fixed cadence jobs: store next fire as epoch millis in UTC and add your interval.
Quartz with per zone triggers. Quartz lets you set a timezone on a CronTrigger. That keeps 09:00 in S�o Paulo consistent across DST changes.
\n\n\n\norg.quartz.CronTrigger trigger = new org.quartz.impl.triggers.CronTrigger();\ntrigger.setCronExpression("0 0 9 * * ?");\ntrigger.setTimeZone(java.util.TimeZone.getTimeZone("America/Sao_Paulo"));\nscheduler.scheduleJob(jobDetail, trigger);Beware missing and repeated times. On the spring jump, times like 02:15 do not exist in some zones. On the fall repeat, 01:30 happens twice. For user input in a zone, validate and disambiguate.
\n\n\n\n// Joda example disambiguation on fall repeat\nDateTimeZone zone = DateTimeZone.forID("America/New_York");\nLocalDate date = new LocalDate(2008, 11, 2);\nLocalTime time = new LocalTime(1, 30);\n\nList<Long> candidates = zone.getTransition(date.toDateTime(time, zone).getMillis()) != 0\n ? java.util.Arrays.asList(\n date.toDateTime(time, zone).getMillis(),\n date.toDateTime(time, zone).plusHours(1).getMillis()\n )\n : java.util.Collections.singletonList(date.toDateTime(time, zone).getMillis());\n// present choices to user if ambiguousAPIs that accept offsets only. Some external services only take a numeric offset like GMT minus 3. That is not enough around DST switches because the offset can change. If the API allows it, send region IDs. If not, refresh offsets often from a zone and cache them.
\n\n\n\nField checklist you can paste in a ticket
\n\n\n\n- Servers run with default timezone UTC. Logs print ISO 8601 with Z.
- Database stores timestamps in UTC. JDBC uses a UTC Calendar for set and get.
- User profile stores locale and preferred timezone. Do not guess.
- All display formats use user locale. All parsing uses the same locale.
- APIs and URLs carry time as ISO 8601 UTC strings.
- Message bundles and MessageFormat handle text with parameters.
- UTF 8 from request to response to database. No mixed encodings.
- Quartz or cron jobs are labeled wall time or fixed cadence and scheduled accordingly.
- OS tzdata and JVM tz rules updated before seasons change. Watch vendor notices.
- No short timezone names. Only region IDs like America Mexico_City.
Reflective close
\n\n\n\nThe past few weeks have been a rush. New users are finding apps from their phones and laptops in every corner. We spend hours on features that show up on screenshots, but the small choices about timezone and locale make the difference between smooth and brittle. The fixes are not mysterious. Store in UTC. Format with the user locale. Keep tzdata fresh. Be explicit about whether a schedule follows the sun or the clock in Greenwich.
\n\n\n\nIf you are starting a new module this weekend, wire these defaults first. If you have a mature codebase, audit the edges. Search for SimpleDateFormat without a timezone, for NumberFormat without a locale, and for raw string glue between numbers and labels. Swap in better patterns. Run tests in a different zone than your laptop. Flip the default locale for a test run. You will catch the same class of bugs that used to find us at 3 in the morning.
\n\n\n\nSoftware now travels everywhere. The most reliable teams I know treat time and language as first class inputs just like user id or price. Do that and the sun can spin all it wants while your app keeps its cool.
\n