الـ Timezones والـ Internationalization: UTC و DST والـ locales والـ plurals والفلوس

أهلًا بيك. النهارده الوقت واللغة. حاجتين شكلهم سهل قوي، ومليانين bugs بتبان مرتين في السنة بس، أو لما أول user من بلد تاني يدخل. بص على reminders dot naive dot js. route بيعمل reminder كل يوم، و route لتقرير النهارده، و route للـ cart بيكتب عدد المنتجات والـ total، و route للـ search في الأسماء. الـ reminder: الـ user كتب الساعة تسعة، و new Date فهمها بالـ timezone بتاع الـ server، والـ server في Frankfurt أو في UTC، مش في القاهرة. وكل مرة بنزوّد أربعة وعشرين ساعة. يوم ما الساعة تتغيّر، الـ reminder يبقى الساعة عشرة أو تمانية. التقرير: setHours صفر يعني نص الليل عند الـ server، والعميل في طوكيو يومه مختلف. ومش كل يوم أربعة وعشرين ساعة. الـ cart: إنجليزي بس، والـ plural بحرف s، و toFixed بتاع اتنين، والين مالوش كسور، والدينار الكويتي ليه تلاتة. والـ search: أحمد بالهمزة و احمد من غيرها مش بيلاقوا بعض، والـ sort بيحط Zeina قبل adam و file10 قبل file9.

أول قاعدة في الوقت. فيه حاجتين مختلفين خالص. instant: حاجة حصلت في حتة واحدة في الزمن، زي الـ order اتعمل، أو الـ payment نجح. دي ليها قيمة واحدة في الدنيا كلها، والـ user في القاهرة والـ user في طوكيو شايفينها نفس اللـ instant، بس كل واحد بيقراها على ساعته. وساعة على الحيطة: زي فكّرني الساعة تسعة الصبح، أو المحل بيفتح الساعة عشرة. دي مش instant، دي ساعة في مكان معيّن، ومعناها بيتغيّر حسب المكان والتاريخ. اللـ instant بتتخزّن UTC. والساعة على الحيطة بتتخزّن هي نفسها، ومعاها الـ timezone.

التخزين في Postgres. استخدم timestamptz، مش timestamp. الاسم بيلخبط: timestamptz ما بيخزّنش timezone، هو بيخزّن instant بـ UTC، وبيحوّل اللي داخل واللي خارج حسب الـ timezone بتاع الـ session. أما timestamp من غير tz فهو ساعة على الحيطة من غير مكان، ولو حطيت فيه instants، كل server بيفهمها بطريقة. خلّي الـ session timezone بتاع الـ app بـ UTC، والـ Node process كمان بـ TZ بـ UTC، فالـ logs والحسابات تبقى واحدة على كل الـ servers. وفي الـ API رجّع ISO strings بـ Z في الآخر، أو بـ offset. أبدًا ما ترجّعش string زي ألفين وستة وعشرين، شهر تلاتة، تسعة الصبح، من غير ما تقول فين.

طب الـ timezone نفسه إيه؟ ناس كتير بتفتكر إن القاهرة يعني زائد اتنين. غلط. القاهرة رجعت للتوقيت الصيفي من ألفين وتلاتة وعشرين، فهي زائد تلاتة في الصيف. ومصر غيّرت قرارها ده أكتر من مرة، وأحيانًا بقرار قبلها بأسابيع. الـ offset رقم في instant معيّنة. والـ timezone زي Africa slash Cairo هو تاريخ كامل من القواعد: الـ offset كان كام، وبيتغيّر إمتى. والتاريخ ده موجود في IANA tz database، اللي Node والـ browsers و Postgres بيستخدموها. فخزّن للـ user الـ IANA name، مش زائد اتنين. وفيه zones الـ offset بتاعها بنص ساعة، زي الهند زائد خمسة ونص، ونيبال زائد خمسة وخمستاشر دقيقة. وخلّي الـ Node و Postgres updated، لأن الـ tz data بتتغيّر كل كام شهر. في JavaScript، إزاي تعرف الساعة كام في zone معيّن؟ الـ Date في JavaScript هو instant بس، رقم milliseconds من سنة ألف وتسعمية وسبعين UTC. و getHours بيدّيك الساعة بالـ timezone بتاع الـ process، وده اللي مش عايزه أبدًا على server. الحل Intl dot DateTimeFormat، وتدّيله timeZone. و formatToParts بيرجّعلك الأجزاء منفصلة: السنة، والشهر، واليوم، والساعة. ومنهم تقدر تحسب الـ offset: خد الأجزاء دي كأنها UTC بـ Date dot UTC، واطرح منها اللـ instant الأصلية، والفرق هو الـ offset. وده اللي هتعمله في zonedParts و offsetMinutes. وخلي بالك، إنشاء الـ formatter غالي، فخزّنه في Map لكل zone.

دلوقتي أصعب حتة: الـ daylight saving. في نيويورك، يوم تمانية مارس ألفين وستة وعشرين، الساعة اتنين الصبح بتنط على طول لتلاتة. يعني الساعة اتنين ونص في اليوم ده مش موجودة. ده اسمه gap. ويوم واحد نوفمبر، الساعة اتنين بترجع لواحدة. فالساعة واحدة ونص بتحصل مرتين، مرة بالتوقيت الصيفي ومرة بالشتوي. ده اسمه overlap. فلو user كتب واحدة ونص في اليوم ده، أنهي واحدة يقصد؟ ولو كتب اتنين ونص، تعمل إيه؟ الإجابة اسمها disambiguation، وفيه أربع اختيارات، وهي نفسها اللي في Temporal. compatible، وده الـ default: في الـ overlap خد الأبدري، وفي الـ gap ازق لقدّام بطول الـ gap، فاتنين ونص تبقى تلاتة ونص. ده نفس اللي بيعمله Temporal والـ calendars. earlier: دايمًا الأبدري. later: دايمًا المتأخر. reject: ارمي error، وده كويس لو الـ user بيدخّل ميعاد بنفسه في form، فتقوله الساعة دي مش موجودة اختار تانية. والطريقة في الـ code: احسب الساعة كأنها UTC، وجرّب الـ offset قبلها بيوم والـ offset بعدها بيوم. ده بيدّيك مرشّحين. ارجع بكل مرشّح للـ zone، واللي بيرجّعلك نفس الساعة هو الصح. اتنين صح يبقى overlap. ولا واحد يبقى gap.

ده بيخلّينا لحاجة بتكسر تقارير كتير: اليوم مش دايمًا أربعة وعشرين ساعة. يوم تغيير الساعة في نيويورك في مارس، اليوم تلاتة وعشرين ساعة، وفي نوفمبر خمسة وعشرين. وفي القاهرة يوم أربعة وعشرين أبريل تلاتة وعشرين ساعة. فتقرير مبيعات النهارده لـ merchant في القاهرة: ما تعملش start زائد أربعة وعشرين ساعة. احسب نص الليل النهارده بتوقيته، ونص الليل بكرة بتوقيته، وكل واحد فيهم instant UTC. وبعدين في Postgres: created_at أكبر من أو قد الـ start، وأصغر من الـ end. نص مفتوح من آخره، عشان ما تحسبش نفس الـ order في يومين. وخلي بالك، اليوم بتاع مين؟ تقرير الـ merchant بتوقيت الـ merchant، والـ dashboard الداخلي ممكن يبقى UTC. قرّر واكتبه. والـ group by باليوم؟ في Postgres تقدر تقول date_trunc بـ day على created_at at time zone Africa slash Cairo، و Postgres بيحسب الـ DST صح، لأن عنده نفس الـ IANA data. والأفضل تدّيله الـ timezone كـ parameter من الـ user، مش تكتبه في الـ query. ولو بتعمل cache أو materialized view لتقارير يومية، الـ key لازم يبقى التاريخ والـ timezone مع بعض، لأن يوم خمستاشر في القاهرة غير يوم خمستاشر في طوكيو.

الجدولة. فكّرني كل يوم الساعة تسعة. غلط: تخزّن instant، وكل مرة تزوّد أربعة وعشرين ساعة. بعد تغيير الساعة، تسعة تبقى عشرة. صح: تخزّن القاعدة نفسها: الساعة تسعة، والـ timezone بتاع الـ user. وكل مرة تحسب الـ occurrence الجاية من الأول: النهارده الساعة تسعة بتوقيته، ولو عدّت خد بكرة، وحوّلها لـ UTC، وحطّها في الـ queue. ولو الساعة اللي اختارها في gap، زي اتنين ونص، compatible بيزقها لتلاتة ونص، أحسن من إنها تضيع. ولو في overlap، earlier عشان ما يتبعتش مرتين. ولو الـ user سافر وغيّر الـ timezone بتاعه، تعيد حساب الـ occurrence الجاية، والـ reminders اللي عدّت ما تتلمسش. و Temporal. الـ Date في JavaScript قديم وفيه مشاكل كتير: الشهور من صفر، ومفيش timezones غير UTC والـ local، والـ parsing بتاعه مختلف. و Temporal هو الـ API الجديد، فيه Instant للـ instant، و ZonedDateTime للـ instant في zone، و PlainDate و PlainTime للساعة على الحيطة من غير zone، والـ disambiguation اللي شرحناه. بدأ ينزل في الـ browsers و Node، وفيه polyfills. النهارده هنكتب الحسابات دي بنفسنا بـ Intl، عشان تفهم إيه اللي بيحصل تحت. بس في الـ production، أول ما Temporal يبقى متاح عندك، استخدمه، أو library معروفة زي date-fns-tz أو Luxon. ما تكتبش date library بنفسك في مشروع حقيقي.

ننتقل للغة. الـ browser بيبعت header اسمه Accept-Language، زي ar-SA، وبعده ar بـ q صفر وتسعة، وبعده en بـ q صفر وتمانية. الـ q هو الأولوية. أنت عندك لغات محدّدة، زي en و ar-EG. الـ negotiation: رتّب اللي الـ user عايزه بالأولوية، ولكل واحد دوّر عندك: نفس الـ tag بالضبط، وبعدين نفس اللغة الأساسية. فـ ar-SA يلاقي ar-EG، لأن الاتنين عربي، أحسن من إنه ياخد إنجليزي. q صفر يعني لا. ولو مفيش حاجة، الـ fallback. وبعد كده: لو الـ user اختار لغة بنفسه من الـ settings، دي تكسب على الـ header دايمًا. خزّنها في الـ profile، وما تخمّنش اللغة من الـ IP، لأن فيه مصريين في ألمانيا.

الترجمات. أول حاجة: ما تلزقش strings. You have، وبعدين الرقم، وبعدين item، وبعدين s. ده مستحيل يتترجم، لأن ترتيب الكلام بيختلف من لغة للتانية. الصح: رسالة واحدة كاملة بـ key، فيها placeholders بأسماء، زي عندك count منتج. والمترجم بيحرّك الـ placeholder في المكان اللي يناسب لغته. تاني حاجة: الجمع. الإنجليزي ليه شكلين: one و other. العربي ليه ستة: zero للصفر، و one للواحد، و two للاتنين، و few من تلاتة لعشرة، و many من حداشر لتسعة وتسعين، و other للمِيّة وما بعدها. منتج واحد، منتجين، تلات منتجات، حداشر منتج. وما تكتبش الـ rules دي بإيدك. Intl dot PluralRules بيعرفها لكل لغة. والـ format ده اسمه ICU MessageFormat، وفيه libraries بتعمله كامل. الـ fallback chain: لو الـ user لغته ar-EG، دوّر في ar-EG، وبعدين ar، وبعدين en. فممكن تحط الحاجات المصرية بس في ar-EG، والباقي ييجي من ar. الـ keys الناقصة: لو ترجمة مش موجودة، ما تكسرش الصفحة، اعرض الـ fallback، بس سجّلها. في الـ production دي metric أو log، وفي الـ CI test بيقارن الـ catalogs ببعض، ويفشل لو فيه key في en مش في ar. والـ workflow: المطوّر بيضيف الـ key بالإنجليزي بس، وفيه tool بتطلّع الـ keys الجديدة وتبعتها للمترجمين، زي Crowdin أو Lokalise، وترجع ملفات. وادّي المترجم context: الكلمة دي زرار ولا عنوان، وفيه حد أقصى للطول ولا لأ.

والـ formatting. الأرقام: ألف وتسعمية وتسعة وتسعين ونص، بالإنجليزي فيه comma بين الآلاف و dot للكسور، وفي ألمانيا بالعكس، وفي العربي ممكن تبقى أرقام هندية. Intl dot NumberFormat بيعمل ده. التواريخ: Intl dot DateTimeFormat بالـ locale والـ timeZone مع بعض. والـ API يرجّع ISO، والـ format يحصل عند العرض بس. والفلوس: خزّنها integer بأصغر وحدة، زي ما اتكلمنا في درس الـ payments. بس أصغر وحدة مش دايمًا قرش من مِيّة: الين الياباني مالوش كسور خالص، والدينار الكويتي ليه تلات كسور. فلو قسمت على مِيّة دايمًا، هتعرض ألف وخمسمية ين على إنهم خمستاشر. NumberFormat بـ style currency بيقولك عدد الكسور لكل currency. الـ RTL. العربي من اليمين للشمال، فالـ HTML يبقى فيه dir بـ rtl و lang بـ ar. وفي الـ CSS استخدم margin-inline-start بدل margin-left، فالـ layout يقلب لوحده. والـ backend ليه دور: رجّع اللغة والاتجاه مع الـ response، أو خلّي الـ frontend يعرفهم من الـ locale. وخلي بالك من الكلام المخلوط: اسم منتج إنجليزي جُوّه جملة عربية، أو رقم تليفون. الـ Unicode بيرتّبهم بخوارزمية اسمها bidi، وأحيانًا بيتلخبطوا، فيه characters مخصوص اسمها isolates بتحمي الحتة دي. ده كمان سبب إنك تشوف characters مش باينة في الـ output بتاع NumberFormat بالعربي، زي right-to-left mark.

آخر حاجة: النصوص نفسها. أحمد بالهمزة و احمد من غيرها، أو أحمد بالتشكيل، أو بالتطويل. للإنسان دي نفس الكلمة، للـ computer لأ. وكمان é ممكن تتكتب character واحد، أو e وبعدها accent لوحده، وشكلهم واحد على الشاشة بس الـ bytes مختلفة. الحل الـ Unicode normalization. NFC بيجمعهم في شكل واحد، و NFKD بيفكّهم، فتقدر تشيل الـ marks، يعني التشكيل والهمزة والـ accents. ده للـ search والمقارنة بس، مش للتخزين، خزّن اللي الـ user كتبه زي ما هو، وخزّن جنبه نسخة normalized تعمل عليها index. والترتيب: sort العادي بيرتّب بالـ code points، فالحروف الكبيرة قبل الصغيرة، و file10 قبل file9. Intl dot Collator بيرتّب زي ما الإنسان يتوقع حسب اللغة. وفي Postgres، الـ collations بتعمل نفس الحكاية، وفيه ICU collations. التحدي. عندك lab dot js بيحكي قصة تطبيق reminders عنده users في القاهرة ونيويورك وطوكيو، و test dot js. والمطلوب intl dot js، بـ Intl بس، من غير أي library. كل التفاصيل في الكومنت: zonedParts و offsetMinutes، و zonedToUtc بالأربع disambiguations، و dayRange و startOfDay و addCalendarDays و nextOccurrence، و negotiateLocale، و createTranslator بالـ plurals والـ fallback والـ missing، والفلوس، والـ normalize والـ sort. اقرا الكومنت كويس، ونشغّل test dot js لحد ما تبقى أربعتاشر من أربعتاشر.

الحل. zonedParts: formatter واحد لكل zone، بـ hourCycle h23 عشان نص الليل يبقى صفر مش أربعة وعشرين. offsetMinutes: الأجزاء كأنها UTC ناقص اللـ instant. zonedToUtc: مرشّحين من الـ offset قبل وبعد بيوم، ونختبر كل واحد. اتنين صح overlap، ولا واحد gap. وكل الحسابات التانية مبنية عليه: نص الليل لليوم ده ولليوم اللي بعده، ونفس الساعة بعد n أيام، والساعة الجاية. ومفيش ولا مرة أربعة وعشرين ساعة متكتوبة. والترجمة: chain من الـ locale والـ base والـ fallback، و PluralRules بالـ locale اللي لقينا فيه الرسالة، مش اللي الـ user طلبه. نشغّل lab dot js.

// intl.js: الوقت بالـ timezones والـ DST، واللغة بالـ Accept-Language والترجمات والـ plurals، والفلوس والنصوص بلغة كل user
// lab.js و test.js بيعملوا import من هنا: zonedParts و offsetMinutes و zonedToUtc و dayRange و startOfDay و addCalendarDays و nextOccurrence و negotiateLocale و createTranslator و minorUnits و formatMoney و normalizeText و sortByLocale
const DAY = 86400000;
const fmtCache = new Map();

function partsFormatter(timeZone) {
  if (!fmtCache.has(timeZone)) {
    fmtCache.set(timeZone, new Intl.DateTimeFormat("en-US", {
      timeZone, hourCycle: "h23", year: "numeric", month: "2-digit", day: "2-digit",
      hour: "2-digit", minute: "2-digit", second: "2-digit", weekday: "short",
    }));
  }
  return fmtCache.get(timeZone);
}

export function zonedParts(instant, timeZone) {
  const out = {};
  for (const p of partsFormatter(timeZone).formatToParts(new Date(instant))) {
    if (p.type === "weekday") out.weekday = p.value;
    else if (p.type !== "literal") out[p.type] = Number(p.value);
  }
  return { year: out.year, month: out.month, day: out.day, hour: out.hour, minute: out.minute, second: out.second, weekday: out.weekday };
}

const wallMs = ({ year, month, day, hour = 0, minute = 0, second = 0 }) => Date.UTC(year, month - 1, day, hour, minute, second);

export function offsetMinutes(instant, timeZone) {
  const t = Math.floor(new Date(instant).getTime() / 1000) * 1000;
  return Math.round((wallMs(zonedParts(t, timeZone)) - t) / 60000);
}

export function zonedToUtc(fields, timeZone, { disambiguation = "compatible" } = {}) {
  const local = wallMs(fields);
  const before = offsetMinutes(local - DAY, timeZone) * 60000;
  const after = offsetMinutes(local + DAY, timeZone) * 60000;
  const candidates = [...new Set([local - before, local - after])].sort((a, b) => a - b);
  const valid = candidates.filter((c) => c + offsetMinutes(c, timeZone) * 60000 === local);
  if (valid.length === 2) {
    if (disambiguation === "reject") throw Object.assign(new Error("AMBIGUOUS_TIME"), { code: "AMBIGUOUS_TIME" });
    return new Date(disambiguation === "later" ? valid[1] : valid[0]);
  }
  if (valid.length === 1) return new Date(valid[0]);
  if (disambiguation === "reject") throw Object.assign(new Error("NONEXISTENT_TIME"), { code: "NONEXISTENT_TIME" });
  return new Date(disambiguation === "earlier" ? local - after : local - before);
}

const nextDate = ({ year, month, day }, n = 1) => {
  const d = new Date(Date.UTC(year, month - 1, day + n));
  return { year: d.getUTCFullYear(), month: d.getUTCMonth() + 1, day: d.getUTCDate() };
};

export function dayRange(dateStr, timeZone) {
  const [year, month, day] = dateStr.split("-").map(Number);
  const start = zonedToUtc({ year, month, day }, timeZone);
  const end = zonedToUtc(nextDate({ year, month, day }), timeZone);
  return { start, end, hours: (end - start) / 3600000 };
}

export function startOfDay(instant, timeZone) {
  const { year, month, day } = zonedParts(instant, timeZone);
  return 
…

$ node lab.js
① لحظة واحدة، تلات ساعات حيطة:
  Africa/Cairo: Mon 10:00 (offset 180 دقيقة)
  America/New_York: Mon 3:00 (offset -240 دقيقة)
  Asia/Tokyo: Mon 16:00 (offset 540 دقيقة)
  القاهرة صيف وشتا: 180 / 120

② الساعة اللي مش موجودة والساعة اللي بتتكرر في نيويورك:
  02:30 يوم ما الساعة بتتقدّم ← compatible: 2026-03-08T07:30:00.000Z
  reject ← NONEXISTENT_TIME
  01:30 يوم ما الساعة بترجع ← earlier: 2026-11-01T05:30:00.000Z later: 2026-11-01T06:30:00.000Z

③ اليوم مش دايمًا 24 ساعة:
  2026-03-08 America/New_York: 23 ساعة، من 2026-03-08T05:00:00.000Z لـ 2026-03-09T04:00:00.000Z
  2026-11-01 America/New_York: 25 ساعة، من 2026-11-01T04:00:00.000Z لـ 2026-11-02T05:00:00.000Z
  2026-04-24 Africa/Cairo: 23 ساعة، من 2026-04-23T22:00:00.000Z لـ 2026-04-24T21:00:00.000Z
  2026-06-15 Asia/Tokyo: 24 ساعة، من 2026-06-14T15:00:00.000Z لـ 2026-06-15T15:00:00.000Z
  نفس اللحظة، بداية اليوم في طوكيو: 2026-01-15T15:00:00.000Z وفي نيويورك: 2026-01-15T05:00:00.000Z

④ reminder الساعة تسعة الصبح كل يوم:
  +24h ← 10:00 في نيويورك   |   addCalendarDays ← 9:00
  +24h ← 10:00 في نيويورك   |   addCalendarDays ← 9:00
  الجاي بعد 05:59Z في القاهرة: 2026-06-01T06:00:00.000Z وبعد 06:00Z: 2026-06-02T06:00:00.
…