チュートリアル//9 読了時間

日時のローカライゼーション：フォーマット、タイムゾーン、そして生じるバグ

Eray Gündoğmuş
共有
目次

日時のローカライゼーション：フォーマット、タイムゾーン、そして生じるバグ

オーストラリアのユーザーに間違った日付を表示する機能をリリースしたことがある方、あるいはUTCを意図していたのにローカルタイムゾーンで時刻を保存してしまったことがある方は、日時処理がいかに容赦ないかをその身で知っているはずです。これらはエッジケースではありません。これが通常の状態です。

日時のローカライゼーションは、二つの異なる難しい問題の交差点に位置します。国際化（異なるフォーマット、カレンダー、言語）と分散システム（タイムゾーン、夏時間のトランジション、クロックスキュー）です。どちらか一つでも誤ると、ユーザーには意味のないデータが表示されます。さらに恶いことに、表面上は層定的に見えるのに実際には数時間や数日ずれているデータが表示されることもあります。

この記事ではスタック全体を記述します。日付の保存、送信、表示の正しい方法を説明し、JavaScript、Python、Rubyの動作するコード例を通じて、詳細を省いたチームが陥る特定のバグにも言及します。

フォーマット問題：MM/DD/YYYY対えDD/MM/YYYY対それ以外

日付の書き方には普遂に認められた一つの正解がありません。この一文だけで、数えきれないユーザー混乱のチケットが発生しています。

最も一般的な衝突は、米国形式（MM/DD/YYYY）と欧州／世界形式（DD/MM/YYYY）の間です。日付04/05/2024は米国では4月5日、ドイツでは5月4日を意味します。ユーザーのロケールを知らなければ、文字列からだけではどちらが正しいか判断する方法はありません。

この順序の衝突以外にも、フォーマットはさらに分岐します：

  • 日本、中国、韓国：YYYY/MM/DDまたはYYYY年MM月DD日
  • ISO 8601：YYYY-MM-DD（唯一の曖昧性のないフォーマット。ストレージとAPIに使用する理由がこれです）
  • インド：DD-MM-YYYY、ただしドットやスラッシュで書かれることが多い
  • イラン、アフガニスタン、エチオピア：グレゴリオ暦の順序が異なるだけでなく、全く異なるカレンダー（ペルシア暦、エチオピア暦）を使用

表示に関するルールは、日付フォーマットをハードコードしないことです。常にユーザーのロケールから導出してください。これは、ローカライゼーションと国際化の違いというより大きな課題の一流にすぎません。この区別は日付フォーマット以上に多くのことに影鿹を与えます。言語ごとの複数形ルールの理解も、ロケール固有の振る舞いが注意深い取り扱いを必要とする関連分野です。

ISO 8601：ストレージとAPIに使用すべき唯一のフォーマット

日付を保存する場合やサービス間で渡す場合は、ISO 8601を使用してください。常に。例外なし。

ISO 8601の日付は、日付の場合2024-04-05、日時の場合2024-04-05T14:30:00Zとなります。バックエンド使用に適した主な特徴：

  • 曖昧性なし：ロケール依存の順序なし
  • ソート可能：辞書順ソートが時系列順ソートと一致
  • タイムゾーン明示：Zサフィックス（または+05:30のオフセット）でタイムゾーンが値の一部になる
  • ユニバーサルサポート：すべての主要プログラミング言語で追加ライブラリなしにパースできる

日付処理で最も一般的な失敗は、データベースにローカルの日時文字列を保存することです。その文字列がフランクフルトのサーバーで作成された場合はある意味を持ち、ニューヨークのサーバーで読み込まれた場合は別の意味になります。明示的なUTCオフセット付きのISO 8601でこの曖昧性は解沈されます。

# Python: 常にUTCで保存し、常にタイムゾーン情報を含める
from datetime import datetime, timezone

# 不正解: ナイーブな datetime、タイムゾーン情報なし
bad = datetime.now()  # "2024-04-05 14:30:00" — ローカル時刻？UTC？不明

# 正解: タイムゾーンを意識したUTC datetime
good = datetime.now(timezone.utc)  # "2024-04-05T14:30:00+00:00"
good_str = good.isoformat()  # "2024-04-05T14:30:00+00:00"

// JavaScript: シリアライズにはISO文字列を使用
const now = new Date();

// 不正解: ロケール依存で移植不可
const bad = now.toLocaleDateString(); // "4/5/2024" (US), "05.04.2024" (DE)

// 正解: ISO 8601、明示的UTF
const good = now.toISOString(); // "2024-04-05T14:30:00.000Z"

# Ruby: UTCとISO 8601を使用
# 不正解
Time.now.to_s  # "2024-04-05 14:30:00 +0200" — ローカルのタイムゾーンが漏れる

# 正解
Time.now.utc.iso8601  # "2024-04-05T12:30:00Z"

タイムゾーン：UTCで保存、ローカル時刻で表示

タイムゾーン処理の基本原則は単純ですが、絵第のプレッシャー下では忘れがちです：UTCで保存し、ユーザーのローカル時刻で表示する。

UTCはタイムゾーンではなく、標準です。夏時間は観察しません。スレもありません。UTCタイムスタンプは、地球上のどこでも全く同じ意味を持つ絶対的な時点です。

UTCで保存してユーザーのタイムゾーンを知っていれば、常に正しいローカル時刻を計算できます。タイムゾーンなしにローカル時刻を保存すると、回復不可能な情報を失ってしまいます。

ユーザーのタイムゾーンはどこから取得するか？信頼性のおおまかな順序でいくつかのソースがあります：

  1. ユーザーの明示的な設定：プロファイルに保存（最も正確で、ユーザー自身が管理）
  2. ブラウザーのAPI：Intl.DateTimeFormat().resolvedOptions().timeZoneでIANAタイムゾーン文字列を取得
  3. IPジオロケーション（おおまかな位置、モバイルユーザーには不向き、VPNでは失敗）
// ブラウザーからユーザーのタイムゾーンを取得
const userTimezone = Intl.DateTimeFormat().resolvedOptions().timeZone;
// 例： "America/New_York", "Europe/Berlin", "Asia/Kolkata"

タイムゾーンを取得したら、フォーマットロジックに渡してください。UTCタイムスタンプを手動でローカル時刻に変換しようとしないでください。夏時間のトランジションを理解する定評のライブラリを使用してください。

夏時間：手動のオフセット計算が失敗する理由

夏時間（DST）が、タイムゾーンオフセットをハードコードしてはならない理由です。

「ドイツはUTC+1」は年の半分は間違いです。ドイツは冬にCET（UTC+1）、夏にCEST（UTC+2）を適用します。+1をハードコードして、ユーザーが3月に午前10時にイベントを作成すると、夏になると保存されたオフセットが間違っているため、イベントが間違った時刻に表示されます。

オルソン（IANA）タイムゾーンデータベース—America/New_York、Europe/Berlin、Asia/Kolkataなどの名前—には、全タイムゾーンのDSトランジションの完全な履歴と将来のスケジュールが含まれています。すべてのプラットフォームに搭載されています。生のオフセットではなく、名前付きのタイムゾーンを使用してください。

注意すべきDSTトランジションのバグ：

  • 曖昧な1時間：時計が戻るので、午前1時30分が2回発生します。どちらの発生か知らなければ「1:30」は曖昧です。
  • 存在しない時間：時計が進むので、午前2時30分は存在しません。指定なしに調整するパーサーもあります。
  • ズレた定期イベント：「ローカル時刻の午後3時」に設定された週次イベントは、DSTトランジション後もローカル午後3時のままであるべきです。つまりUTC時刻が1時間変化することになります。
// JavaScript: Intl APIにDSTを任せる
const formatter = new Intl.DateTimeFormat('de-DE', {
  timeZone: 'Europe/Berlin',
  hour: '2-digit',
  minute: '2-digit',
  day: '2-digit',
  month: '2-digit',
  year: 'numeric',
});

// CETとCESTの両方で安全
const utcDate = new Date('2024-03-31T01:30:00Z'); // ヨーロッパのDSTトランジション日
console.log(formatter.format(utcDate)); // "31.03.2024, 03:30"

# Python: zoneinfo (Python 3.9+)またはpytzを使用
from zoneinfo import ZoneInfo
from datetime import datetime

utc_time = datetime(2024, 3, 31, 1, 30, tzinfo=ZoneInfo("UTC"))
berlin_time = utc_time.astimezone(ZoneInfo("Europe/Berlin"))
print(berlin_time)  # 2024-03-31 03:30:00+02:00 — DSTを考慮した変換

# Ruby: 信頼性の高いDST処理にはTZInfo gemを使用
require 'tzinfo'

tz = TZInfo::Timezone.get('Europe/Berlin')
utc = Time.utc(2024, 3, 31, 1, 30)
local = tz.utc_to_local(utc)
# DSTを正しく考慮した時刻を返す

JavaScript Intl.DateTimeFormat：日付をフォーマットする正しい方法

Intl.DateTimeFormat APIはすべてのモダンなJavaScriptランタイムに組み込まれています。外部依存なしに、ロケール固有のフォーマット、タイムゾーン変換、カレンダーシステムを処理します。

// 基本的なロケール対応日付フォーマット
const date = new Date('2024-08-15T09:00:00Z');

// 米国英語
new Intl.DateTimeFormat('en-US', { dateStyle: 'long' }).format(date);
// "August 15, 2024"

// ドイツ語
new Intl.DateTimeFormat('de-DE', { dateStyle: 'long' }).format(date);
// "15. August 2024"

// 日本語
new Intl.DateTimeFormat('ja-JP', { dateStyle: 'long' }).format(date);
// "2024年8月15日"

// 時刻とタイムゾーン付き
new Intl.DateTimeFormat('en-GB', {
  dateStyle: 'full',
  timeStyle: 'short',
  timeZone: 'Europe/London',
}).format(date);
// "Thursday, 15 August 2024 at 10:00"

相対時間のフォーマット（例：「3時間前」）はIntl.RelativeTimeFormatを使用します：

const rtf = new Intl.RelativeTimeFormat('fr-FR', { numeric: 'auto' });

rtf.format(-1, 'day');   // "hier" (昨日)
rtf.format(-3, 'hour');  // "il y a 3 heures"
rtf.format(2, 'week');   // "dans 2 semaines"

Intl.RelativeTimeFormatは値と単位を自分で計算する必要があることに注意してください。何かが「昨日」か「3日前」かは自動判定しません。date-fnsやTemporal（現在のDate APIの後継者）などのライブラリがこのロジックをIntlの上に層として追加しています。

PythonとRuby：Babel、strftime、その限界

Python：ロケール対応フォーマットにはBabel

Pythonの標準ライブラリstrftimeはシステムロケール経由でのみロケール対応出力を生成しますが、プロダクション環境では信頼性が低いです。正しいi18nにはBabelを使用してください：

from babel.dates import format_date, format_datetime, format_time
from datetime import datetime, timezone

dt = datetime(2024, 8, 15, 9, 0, 0, tzinfo=timezone.utc)

# 異なるロケール向けにフォーマット
format_date(dt, locale='en_US')    # 'Aug 15, 2024'
format_date(dt, locale='de_DE')    # '15.08.2024'
format_date(dt, locale='ja_JP')    # '2024/08/15'
format_date(dt, format='long', locale='ar_SA')  # '١٥ أغسطس ٢٠٢٤'

# タイムゾーン変換付き
from babel.dates import get_timezone
format_datetime(
    dt,
    format='full',
    tzinfo=get_timezone('America/New_York'),
    locale='en_US'
)
# 'Thursday, August 15, 2024 at 5:00:00 AM Eastern Daylight Time'

Ruby：strftimeはロケールに非対応

Rubyの組み込みstrftimeはロケールを認識しません。Time.now.strftime('%B %d, %Y')はアプリのロケールに関わらず常に英語の月名を生成します。ロケール対応出力には、ロケール固有のフォーマット文字列を上てi18n gem（Rails標準）を使用するか、CLDRベースのフォーマットにtwitter_cldrを使用してください：

require 'twitter_cldr'

date = DateTime.new(2024, 8, 15, 9, 0, 0)

# 英語
date.localize(:en).to_long_s  # "August 15, 2024"

# ドイツ語
date.localize(:de).to_long_s  # "15. August 2024"

# 日本語
date.localize(:ja).to_long_s  # "2024年8月15日"

# 相対時間
time_ago = 3.hours.ago
time_ago.localize(:fr).ago.to_s  # "il y a 3 heures"

RailsアプリはロケールYAMLファイルと共にI18n.l(date, format: :long)を使用するのが慣例的な手法ですが、そのYAMLファイル内のフォーマット文字列は依然として各言語の手動ローカライゼーションが必要です。

本番環境のバグを引き起こす一般的な誤り

1. データベースにローカル時刻を保存する

-- 不正解: これはどのタイムゾーンか？
created_at DATETIME DEFAULT NOW()

-- 正解: 常にUTCで保存
created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW() AT TIME ZONE 'UTC'

データベースのカラムタイプがタイムゾーン非対応のDATETIMEなら、すでに情報を失っています。TIMESTAMP WITH TIME ZONE（または等価物）に切り替え、アプリケーション層が常にUTCで書き込むようにしてください。

2. ISO以外の文字列のパースにJavaScript Date()を使用する

// 不正解: ISO以外の文字列のパース動作は実装依存
new Date('05/04/2024')  // 5月4日か4月5日か？環境のロケール次第

// 正解: ISO 8601文字列のみ、またはライブラリを使用
new Date('2024-05-04')  // 常に2024年5月4日

3. サーバーのタイムゾーンがUTCだと仮定する

多くのクラウド環境はデフォルトでUTCですが、そうでないものも多くあります。TZ環境変数を確認せずにnew Date()がUTCを返すと仮定するコードは、異なるデプロイ環境で異なる動作をします。

// 不正解: サーバーがUTCだと仮定
const today = new Date().toISOString().split('T')[0];

// 正解: 何を計算しているかを明示的にする
const todayUTC = new Date().toISOString().split('T')[0]; // toISOString経由でこれはUTC
const todayLocal = new Intl.DateTimeFormat('en-CA', {
  timeZone: userTimezone
}).format(new Date()); // "2024-08-15"

4. 真夜中は安全なデフォルト時刻ではない

特定の日付の真夜中UTCにイベントを作成すると、UTC-5からUTC-12のユーザーには前日のイベントとなります。「終日イベント」は日時ではなく日付のみ（YYYY-MM-DD）を保存すべきです。

5. オフセットをタイムゾーンとして扱う

+05:30はオフセットであり、タイムゾーンではありません。インド（Asia/Kolkata）は常にUTC+5:30でDSTを適用しないため、この場合は区別は無害です。しかし+10:00の場合、Australia/Sydney（DST適用）またはPacific/Port_Moresby（DST非適用）のどちらかになり得ます。生のオフセットの代わりに、またはそれと並んで、常にIANAタイムゾーン名を保存してください。

Webアプリにおけるユーザーのタイムゾーン設定の管理

完全な実装には3つのことが必要です：

  1. 登録時にタイムゾーンを検出または取得：ブラウザーのAPIをデフォルトとして使用し、設定でユーザーが変更できるようにする。
  2. ユーザープロファイルにIANAタイムゾーン文字列を保存：オフセットでも都市名でもなく。
  3. 保存時ではなくレンダリング時に適用：タイムスタンプはデータベース内でUTCのままです。変換はユーザー表示時にアプリケーション層で行う。
// フロントエンド：検出してバックエンドに送信
const detectedTimezone = Intl.DateTimeFormat().resolvedOptions().timeZone;

// 登録またはプロファイル保存時：
await api.updateProfile({ timezone: detectedTimezone });

// APIから取得した日付のレンダリング時：
function formatEventTime(isoString, userTimezone, locale) {
  return new Intl.DateTimeFormat(locale, {
    timeZone: userTimezone,
    dateStyle: 'medium',
    timeStyle: 'short',
  }).format(new Date(isoString));
}

// 使用例
formatEventTime('2024-08-15T14:30:00Z', 'Asia/Tokyo', 'ja-JP');
// "2024/08/15 23:30"

サーバー側で「特定のカレンダー日のユーザーの全イベント」を解釈する必要がある場合は、その「今日」をUTC範囲に変換してください：

from datetime import datetime
from zoneinfo import ZoneInfo

def get_day_utc_range(date_str: str, user_timezone: str):
    """ローカル日付をUTC datetime範囲に変換する。"""
    tz = ZoneInfo(user_timezone)
    local_start = datetime.fromisoformat(f"{date_str}T00:00:00").replace(tzinfo=tz)
    local_end = datetime.fromisoformat(f"{date_str}T23:59:59").replace(tzinfo=tz)
    utc_start = local_start.astimezone(ZoneInfo("UTC"))
    utc_end = local_end.astimezone(ZoneInfo("UTC"))
    return utc_start, utc_end

# 東京のユーザーの「今日」は、ニューヨークのユーザーと異なるUTC範囲になる
start, end = get_day_utc_range("2024-08-15", "Asia/Tokyo")
# クエリ: WHERE created_at BETWEEN start AND end

日付ローカライゼーションのテスト

日付ローカライゼーションのバグは、開発者とCIサーバーが同じタイムゾーンにいることが多いため、開発中は目に見えないことがよくあります。テストで明示的にカバーすべき事項：

  1. 複数のロケール：最低限でもen-US、de-DE、ja-JP、ar-SA（RTL + 異なる数字）をテスト
  2. DSTトランジション日：3月とロ月（北半球）　9月とロ月（南半球）
  3. タイムゾーンのエッジケース：UTC-12、UTC+14、インド（UTC+5:30）、ネパール（UTC+5:45）でテスト
  4. 年・月の境界：タイムゾーンをまたいでの12月31日から1月1日
// Jest: 不安定さを防ぐため定の日付でテスト
describe('formatEventTime', () => {
  const testCases = [
    {
      input: '2024-03-31T01:30:00Z', // ヨーロッパのDSTトランジション
      timezone: 'Europe/Berlin',
      locale: 'de-DE',
      expected: '31.03.2024, 03:30', // 03:30に進む
    },
    {
      input: '2024-08-15T14:30:00Z',
      timezone: 'Asia/Kolkata',
      locale: 'hi-IN',
      expected: '15/8/2024, 8:00 pm', // UTC+5:30
    },
  ];

  test.each(testCases)('$localeの$timezoneで正しくフォーマットする', ({ input, timezone, locale, expected }) => {
    expect(formatEventTime(input, timezone, locale)).toBe(expected);
  });
});

CI環境では、テストがサーバーのローカルタイムゾーンに依存しないよう、TZ環境変数を明示的にUTCに設定してください：

TZ=UTC npx jest

日付処理は、グローバル製品を踓つませる他のロケール固有の慣習とも密接に関連しています。複数の市場向けに開発する場合、言語ごとの複数形ルールやhreflangタグを用いた正しいi18n SEO実装は、タイムゾーン処理と並行して見直す価値のある関連分野です。国際化テストに着実に取り組むチームは、日付フォーマットを超えた包括的なi18nテスト戦略も参照することをお勧めします。

Better i18nの役割

手動による日付フォーマットは解決可能です——Intl APIやBabelなどのライブラリはレンダリング層をうまく管理できます。より難しい問題はスケールです。アプリケーションが20ぺージのロケールを提供する場合、日付フォーマットの設定はすべてのコンポーネント、メールテンプレート、エクスポートで一貫している必要があります。その一貫性はチームの成長とともに崩壊したります。

Better i18nは、各コンポーネントにIntlオプションをハードコードする代わりに、アプリケーションコードがロケール対応のフォーマットキーを参照できるようにすることでこの問題を解決します。ロケールのフォーマットを変更する必要が生じた場合——たとえばドイツのユーザーが希望する日付スタイルが少し専なうことがわかった場合——コンポーネントファイルを探し回すことなく、一か所で更新するだけで済みます。

Reactアプリ向けには、機能ページでロケールコンテキストと日付フォーマットを組み合わせた統合を紹介しており、各コンポーネントが個別にIntl.DateTimeFormatインスタンスを管理することなく、常に現在のロケールの形式で日付をレンダリングできます。

機能ページではロケールデータのCDN配信も設記されており、これは日付フォーマットにおいて重要です。すべてのロケールの完全なCLDRデータセットは大きいため、必要なロケールデータをオンデマンドで遅延読み込みすることで——全てをバンドルするのではなく——正確性を先素することなく初期ページの軽量化を実現できます。

まとめ

日時のローカライゼーションは表面上の問題ではありません。生成されるバグは正確性のバグです：間違った日のイベント、DST後にズレるタイムスタンプ、異なる地域のユーザーに異なる意味を持つ日付。

ほとんどの問題を防ぐプラクティス：

  • あらゆる場所でISO 8601 UTCで保存・送信：データベース、API、ログ
  • 生のオフセットではなく、ユーザーレコードにIANAタイムゾーン名（例：America/New_York）を保存
  • 手動のフォーマット文字列ではなくJavaScriptで**Intl.DateTimeFormat**を使用
  • バックエンドコードのロケール対応フォーマットにBabel（Python）またはtwitter_cldr（Ruby）を使用
  • タイムゾーンオフセットをハードコードしない——ランタイムの標準ライブラリ経由でIANAデータベースを使用
  • DSTトランジション日、複数のタイムゾーン、複数のロケールで明示的にテスト

保存層と送信層は大部分が言語非依存です：ISO 8601とUTCはどこででも機能します。表示層こそがロケール固有のロジックが存在する場所であり、ツールやライブラリが最も時間を節約できる部分です。日時処理の堀固たる基盤は、グローバルコンテンツローカライゼーションというより大きな考みの一部です——プロダクトのあらゆる側面を、提供する各市場にとってネイティブなものに感じさせることです。

better-i18nでアプリをグローバル展開

better-i18nはAIパワーの翻訳、gitネイティブなワークフロー、グローバルCDN配信を一つの開発者向けプラットフォームにまとめたソリューションです。スプレッドシート管理をやめて、すべての言語でリリースを始めましょう。

無料で始める → · 機能を見る · ドキュメントを読む

Comments

Loading comments...

関連記事

チュートリアル15m

How to Localize Better Auth: Error Messages, UI, and Emails (Complete Guide)

Ali Osman Delismen
チュートリアル12m

How to Add i18n to Shopify Hydrogen (Complete Guide)

Ali Osman Delismen
チュートリアル14m

How AI Chatbots Are Changing Software Localization

Eray Gündoğmuş
チュートリアル13m

Django i18n と AI翻訳：完全セットアップガイド

Eray Gündoğmuş

もっと見る

開発者向け

Git-firstのローカリゼーションツールとSDK連携

翻訳者向け

コンテキストと用語集を活用したAI翻訳

プロダクトチーム向け

エンジニアリング不要でローカライズ製品をより速く出荷

全機能

Better I18Nの機能を網羅的に紹介