• iOS
  • Swift
  • lịch âm

Vì sao Luminder tự tính lịch âm Việt Nam

iOS 26 đã có lịch Việt trong Foundation nhưng đặt Tết 1985 sai ngày. Luminder tự tính lịch âm Việt Nam như thế nào và kiểm chứng kết quả ra sao.

Luminder là ứng dụng iPhone xem lịch âm và nhắc những ngày tính theo mặt trăng: ngày giỗ, sinh nhật âm lịch, mùng 1 và ngày rằm mỗi tháng. Mọi thứ trong ứng dụng đều dựa vào một hàm duy nhất: đưa vào một ngày dương, trả ra ngày âm. Hàm này lệch một ngày thì lời nhắc ngày giỗ sẽ đến sai buổi sáng.

Bài này kể vì sao hàm đó không phải là một dòng gọi Foundation, dù bây giờ iOS đã có sẵn.

Foundation đã có lịch Việt

iOS 26 và macOS 26 thêm hai mã lịch mới: .vietnamese và .dangi (lịch Hàn). .chinese thì đã có từ lâu. Kế hoạch dễ nhất là dùng cả ba, không phải viết dòng thiên văn nào.

Trước khi chốt, mình chạy thử vài ngày đã biết chắc trên SDK thật, cả trên macOS lẫn simulator iOS 26.1. Hai nơi cho cùng kết quả, và có một kết quả sai.

Tết Ất Sửu năm 1985 rơi vào ngày 21/01/1985, và năm âm đó nhuận tháng 2. Lịch .vietnamese của Foundation lại cho rằng 21/01/1985 là mùng 1 tháng Chạp, còn Tết rơi vào 20/02 — đúng ngày Tết của lịch Trung Quốc. Một ứng dụng lịch âm mà sai ngày Tết thì mình không muốn phát hành, nên Luminder không dùng Foundation cho lịch Việt.

Múi giờ làm lịch khác nhau

Lịch âm Việt Nam và Trung Quốc dùng chung quy tắc: tháng bắt đầu vào ngày có điểm sóc (trăng mới), tháng nhuận được xác định dựa vào các tiết khí. Khác nhau ở chỗ “ngày” được tính theo múi giờ nào: lịch Việt theo UTC+7, lịch Trung theo UTC+8, lịch Hàn theo UTC+9. Khi điểm sóc rơi sát nửa đêm, chênh một tiếng là đủ để tháng bắt đầu vào hai ngày khác nhau, và kéo theo cả năm có thể xê dịch.

Vậy thực chất đây là một thuật toán có tham số múi giờ. Luminder dùng thuật toán thiên văn quen thuộc của Hồ Ngọc Đức: tính điểm sóc và kinh độ mặt trời bằng công thức rút gọn, tìm tháng chứa ngày Đông chí (tháng 11 âm), rồi từ đó suy ra tháng nhuận. Engine nhận độ lệch UTC làm tham số, nên cùng một đoạn code có thể tính cả lịch Trung và lịch Hàn để đem ra so sánh.

Mọi phép tính đều làm trên số ngày Julius (Julian Day Number) — các số nguyên thuần. Bên trong engine không có Date hay TimeZone, nên không có chuyện ngày dương bị lệch một ngày vì cài đặt của máy.

Một lỗi biên trong thuật toán gốc

Khi chuyển thuật toán sang Swift, mình gặp một lỗi trong code tham khảo. Để tìm tháng âm chứa một ngày, code lấy điểm sóc kế tiếp; nếu điểm đó rơi sau ngày cần tìm thì lùi lại một điểm sóc. Gần ranh giới tháng, lùi một lần chưa chắc đã đủ, và kết quả là một ngày âm “mùng 0”. Ví dụ: ngày 26/03/2009 với múi giờ UTC+8.

Cách sửa là cứ lùi cho tới khi tháng thật sự đã bắt đầu:

var k = estimatedNewMoonIndex(for: jdn) + 1
var monthStart = newMoonDay(k, utcOffsetHours: offset)
// Code gốc chỉ lùi một lần bằng `if`; gần ranh giới tháng,
// kết quả vẫn có thể nằm sau `jdn` và sinh ra "mùng 0".
while monthStart > jdn {
    k -= 1
    monthStart = newMoonDay(k, utcOffsetHours: offset)
}

Đối chiếu với hai nguồn độc lập

Một engine như vậy chỉ đáng tin bằng bộ test của nó. Luminder kiểm tra theo hai cách: so với bảng chuẩn ngày Tết và tháng nhuận, và so từng ngày với Foundation, xem Foundation như một “trọng tài” độc lập.

So từng ngày trong khoảng 1900–2100 cho kết quả:

  • UTC+8 so với .chinese: không lệch ngày nào từ 1900 đến 2056. Chỗ lệch ở năm 2057 và 2097 rơi vào những ngày Foundation trả day = 0 — lỗi của Foundation.
  • UTC+7 so với .vietnamese: không lệch ngày nào từ 1986 đến 2053. Trước đó, Foundation sai quanh Tết 1985 (từ 22/12/1984 sang năm 1985); trước năm 1968 hai bên khác nhau vì Foundation theo lịch đã dùng trong lịch sử, còn engine tính thiên văn theo UTC+7. Vài năm từ 2054 trở đi cũng lệch.
  • UTC+9 so với .dangi: sai hai chỗ: ngày 02/12/2005 và tháng nhuận năm 2017 (Hàn Quốc nhuận tháng 5, engine ra nhuận tháng 6). Cả hai đều là lúc điểm sóc hoặc tiết khí rơi sát nửa đêm giờ Hàn Quốc, và công thức rút gọn không đủ chính xác để biết nó rơi về phía nào.

Kết quả cuối cùng đó quyết định thiết kế. Luminder chỉ dùng engine riêng cho lịch Việt, còn lịch Trung và lịch Hàn dùng .chinese và .dangi của Foundation. Mỗi loại lịch dùng đúng nguồn khớp với lịch chính thức.

Phạm vi hỗ trợ là từ 01/01/1901 đến 31/12/2050 — khoảng đã được đối chiếu với cả hai nguồn; ứng dụng không hiển thị ngày ngoài khoảng này. Trước năm 1968, kết quả lịch Việt có thể khác với lịch người ta thực sự dùng ở một số năm, và ghi chú của dự án nói rõ điều đó.

Rút ra được gì

API của hệ thống vẫn là thứ cần kiểm tra, không phải thứ để tin mặc định. Chỉ vài ngày đã biết chắc chạy trên SDK thật là đủ để đổi cả kế hoạch. Bài học thứ hai: một engine tự viết và một lịch của hệ thống là hai “trọng tài” tốt cho nhau. Chỗ nào hai bên lệch nhau thì một trong hai có lỗi, và phép so sánh chỉ ra chính xác những ngày cần xem lại.

Tác giả Duy Pham Lập trình viên độc lập. Mình làm các ứng dụng trên trang này và viết về cách chúng hoạt động.

Xem thêm về mình