Tính âm lịch Việt Nam bằng code: năm điều không thể đơn giản hóa
Gần như dự án nào phục vụ người dùng Việt cũng có lúc gặp yêu cầu "hiển thị thêm ngày âm". Ứng dụng nhắc lịch giỗ, hệ thống HR muốn tặng quà Rằm, trang thương mại điện tử chạy khuyến mãi theo mùng Một. Phản xạ đầu tiên của nhiều dev là tìm một bảng tra sẵn hoặc một công thức "trừ khoảng 30 ngày". Cả hai cách đều sẽ sai, và thường sai vào đúng những ngày người dùng quan tâm nhất.
Bài viết này tóm tắt những điểm mấu chốt khi cài đặt bộ chuyển đổi âm dương, dựa trên thuật toán thiên văn theo múi giờ UTC+7 và được nhiều thư viện mã nguồn mở dùng lại.
1. Tháng âm bắt đầu từ ngày sóc, không phải từ một con số cố định
Âm lịch Việt Nam là âm dương lịch. Mỗi tháng bắt đầu vào ngày có điểm sóc, tức thời điểm Mặt Trăng nằm giữa Trái Đất và Mặt Trời. Khoảng cách giữa hai lần sóc trung bình khoảng 29,53 ngày nhưng dao động thực tế, nên tháng âm có 29 hoặc 30 ngày và không theo quy luật xen kẽ đều đặn.
Hệ quả cho code: bạn phải tính thời điểm sóc bằng công thức thiên văn (thường là các chuỗi lượng giác xấp xỉ quỹ đạo), rồi làm tròn ra ngày. Không có vòng lặp "tháng chẵn 30, tháng lẻ 29" nào đúng cả.
2. Múi giờ quyết định ngày
Điểm sóc là một thời điểm tuyệt đối. Nếu nó rơi vào 23 giờ 30 theo giờ một nơi, thì ở nơi chậm hơn một tiếng nó vẫn thuộc ngày hôm trước, còn ở nơi nhanh hơn một tiếng đã sang ngày hôm sau. Lịch âm Việt Nam hiện nay tính theo kinh tuyến 105° Đông, tức UTC+7, trong khi lịch Trung Quốc dùng UTC+8. Phần lớn các năm hai lịch trùng nhau, nhưng thỉnh thoảng lệch một ngày đầu tháng; ví dụ điển hình là điểm sóc rơi vào khoảng 23 giờ giờ Hà Nội, khi đó lịch Việt Nam và lịch Trung Quốc có thể ghi khác ngày.
Vì vậy, đừng dùng thẳng một thư viện âm lịch Trung Quốc rồi gắn nhãn "âm lịch Việt Nam". Hãy kiểm tra xem hàm của bạn có nhận tham số timezone hay không và cố định nó ở 7.
# Ý tưởng chính (rút gọn)
def new_moon_day(k, tz=7):
jd = new_moon_julian(k) # thời điểm sóc thứ k, theo giờ UT
return int(jd + 0.5 + tz / 24) # quy ra số ngày Julius theo múi giờ Việt Nam
3. Tháng 11 âm lịch là mỏ neo
Quy tắc nền tảng: tháng chứa điểm Đông chí luôn là tháng 11 âm lịch. Thuật toán thường bắt đầu bằng việc tìm ngày bắt đầu tháng 11 của năm trước và năm hiện tại, rồi đếm số tháng âm nằm giữa hai mốc ấy. Mọi tháng khác được đánh số tương đối từ mỏ neo này.
4. Tháng nhuận được xác định bằng trung khí
Nếu giữa hai tháng 11 liên tiếp có 13 tháng âm, năm đó có tháng nhuận. Tháng nhuận là tháng đầu tiên (tính từ sau tháng 11) không chứa trung khí nào, tức không chứa thời điểm Mặt Trời đi qua các kinh độ 0°, 30°, 60°... trên hoàng đạo. Đây là lúc bạn cần thêm hàm tính kinh độ Mặt Trời. Cài đặt sai bước này là lỗi phổ biến nhất: kết quả vẫn "trông hợp lý" cho phần lớn ngày, chỉ sai ở năm nhuận.
5. Kiểm thử bằng những ngày người dùng thực sự quan tâm
Unit test với vài ngày ngẫu nhiên là không đủ. Nên có bộ test cố định cho mùng Một Tết, Rằm tháng Giêng, 23 tháng Chạp và các tháng nhuận trong khoảng 20 năm quanh hiện tại. Ví dụ, với UTC+7, mùng Một Tết Đinh Mùi rơi vào 6/2/2027 và tháng Chạp năm Bính Ngọ trước đó chỉ có 29 ngày, nên giao thừa là đêm 5/2/2027. Đây là loại test bắt lỗi rất tốt, vì người dùng sẽ báo ngay nếu ứng dụng hiển thị "30 Tết" không tồn tại.
Khi cần đối chiếu nhanh trong lúc viết test, mình hay dùng một công cụ đổi lịch âm dương đã chạy ổn định để so kết quả, rồi mới chốt giá trị kỳ vọng. Với người mới tiếp cận chủ đề, phần giải thích nền tảng về âm lịch và dương lịch giúp hiểu vì sao hai hệ lịch lệch nhau trước khi đọc code.
Vài lời khuyên khi đưa vào production
Tính toán thiên văn khá rẻ, nhưng nếu ứng dụng hiển thị cả lưới lịch nhiều tháng, hãy tính trước và cache theo năm. Đừng tính âm lịch ở client với giờ máy người dùng nếu họ đang ở nước ngoài: kết quả sẽ phụ thuộc vào cách bạn truyền ngày, dễ lệch một ngày quanh nửa đêm. Lưu ngày dương dạng YYYY-MM-DD không kèm giờ khi chuyển đổi, và chỉ quy đổi sang âm lịch ở một chỗ duy nhất trong hệ thống.
Cuối cùng, ghi rõ nguồn thuật toán trong README. Lịch là thứ người dùng tin tuyệt đối; khi có báo lỗi, bạn sẽ cần biết chính xác mình đang dùng quy ước nào để đối chiếu.
Nguồn tham khảo: Cách tính sóc và tiết khí theo múi giờ UTC+7 (kinh tuyến 105° Đông), dùng công thức xấp xỉ của Jean Meeus — cùng quy ước nhiều thư viện âm lịch Việt đang dùng.
All rights reserved