Untuk memformat waktu publikasi di zona waktu lain, pertahankan waktu aslinya dan berikan zona tujuan kepada pemformat. Panduan Terminal Mac ini menghasilkan label publikasi yang mudah dibaca tanpa mengurai teks yang ditampilkan atau menambahkan jam secara manual.

Informasi apa yang Anda perlukan sebelum mengonversi?

Misalkan Anda sedang menyiapkan dokumen di Mac dan menerima stempel waktu publikasi sintetis 2025-07-15T00:30:00Z. Anda memerlukan tanggal dan waktu publikasi sebagaimana ditampilkan di America/Los_Angeles. Tugasnya adalah menyatakan momen yang sama menggunakan tanggal kalender dan waktu jam di zona tujuan.

Empat istilah menentukan apakah informasi yang Anda miliki sudah cukup:

Istilah Contoh sintetis Makna untuk tugas ini
Tanggal sipil 2025-07-15 Hari kalender, tanpa waktu atau zona
Waktu absolut Momen yang diwakili oleh 2025-07-15T00:30:00Z Titik waktu yang Anda pertahankan
Offset UTC -07:00 Selisih antara waktu lokal dan UTC pada momen tertentu
Zona waktu bernama America/Los_Angeles Aturan yang digunakan untuk menentukan offset yang berlaku

RFC 3339 mendefinisikan stempel waktu yang memuat tanggal, waktu, dan offset UTC lengkap. RFC 9557 menjelaskan perbedaan lebih lanjut: zona bernama menyediakan aturan yang memetakan suatu waktu absolut ke offset, sedangkan offset numerik pada stempel waktu saja tidak menjelaskan bagaimana offset suatu lokasi berlaku pada waktu lain. RFC 3339, Bagian 5.6, RFC 9557, Bagian 1.2.

Gunakan keputusan masukan ini sebelum melakukan konversi:

  • Anda sudah memiliki Date Foundation: berikan langsung ke pemformat yang dikonfigurasi untuk zona tujuan.
  • Anda memiliki stempel waktu dengan Z atau offset numerik eksplisit: uraikan stempel waktu asli itu satu kali, lalu format waktu absolut yang dihasilkan.
  • Anda hanya memiliki tanggal sipil: pertahankan sebagai tanggal kecuali tugas secara eksplisit memberikan waktu dan zona.
  • Anda memiliki tanggal dan waktu lokal tanpa offset: dapatkan zona sumber dan selesaikan ambiguitas apa pun sebelum menganggapnya sebagai waktu absolut.

Sebagai contoh, 2025-07-15 tidak dapat memberi tahu apakah publikasi terjadi sebelum atau sesudah tengah malam di zona lain. Menetapkan tengah malam akan menambahkan asumsi. Demikian pula, pembacaan jam lokal dapat berkorespondensi dengan nol atau beberapa waktu absolut di sekitar peralihan offset; RFC 9557 mendokumentasikan batas tersebut. Mengonversi waktu absolut yang sudah ditetapkan menghindari masalah pemetaan balik ini. RFC 9557, Bagian 1.2.

Mengapa sebaiknya Anda menghindari penguraian ulang teks tampilan?

Apple mendefinisikan Date milik Foundation sebagai titik waktu tertentu yang tidak bergantung pada kalender atau zona waktu mana pun. Nilainya tidak perlu menjadi Date yang berbeda agar dapat ditampilkan di zona lain. Pemformatan menggunakan kalender dan zona yang diperlukan untuk menghasilkan teks. Date.

Label tampilan dapat menghilangkan informasi. Jika Anda memformat waktu absolut sebagai tanggal tanpa waktunya, lalu mengurai label tersebut, waktu yang hilang tidak dapat dipulihkan dari label. Dokumentasi pemformatan Apple menunjukkan proses bolak-balik khusus tanggal yang merekonstruksi tengah malam. Itu berguna jika tengah malam memang dimaksudkan, tetapi tidak mempertahankan waktu publikasi sembarang. Date.FormatStyle.

Pertahankan urutan operasi berikut:

  1. Baca stempel waktu asli atau dapatkan Date yang sudah ada.
  2. Pertahankan waktu absolut itu sebagai nilai kerja.
  3. Pilih zona tujuan, kalender, dan lokal tampilan.
  4. Format waktu absolut yang dipertahankan menjadi label akhir.

Menambahkan offset secara manual juga mengubah tugas. Apple mendokumentasikan addingTimeInterval(_:) sebagai cara membuat tanggal baru dengan menambahkan waktu yang telah berlalu. Jadi, menambahkan tujuh jam menghasilkan waktu absolut lain; memilih zona pada pemformat mengubah cara waktu absolut asli direpresentasikan. Date.

Jalankan contoh waktu publikasi lengkap di Mac Anda

Contoh ini memerlukan macOS 12 atau lebih baru, yang menyediakan API Date.FormatStyle dari Apple, serta toolchain Swift yang berfungsi. Contoh ini menggunakan Foundation tanpa paket tambahan. Date.FormatStyle.

Buka Terminal dan periksa toolchain:

swift --version

Jika Anda memerlukan command-line tools Apple, jalankan perintah berikut dan selesaikan dialog instalasi. Apple mendokumentasikan cara instalasi ini dan menyebutkan bahwa instalasi Xcode lengkap sudah menyertakan command-line tools. Setelah itu, ulangi pemeriksaan versi. Menginstal command-line tools.

xcode-select --install

Di TextEdit, buat dokumen baru dan pilih Format > Make Plain Text. Tempelkan program Swift lengkap di bawah ini dan simpan di Desktop sebagai publication-time.swift. Pastikan nama file yang dihasilkan berakhiran .swift, tanpa ekstensi .txt tambahan. Panduan TextEdit Apple menjelaskan cara membuat, mengonversi, dan menyimpan dokumen teks biasa. Membuat, membuka, dan mengonversi dokumen di TextEdit pada Mac.

Program ini menerima stempel waktu detik penuh yang diberikan, mengurainya satu kali, lalu membuat tiga representasi dari instant yang sama. Apple mendokumentasikan ISO8601DateFormatter untuk mengurai dan menghasilkan representasi ISO 8601, serta opsi withInternetDateTime untuk format RFC 3339. ISO8601DateFormatter, withInternetDateTime.

import Foundation

// Synthetic publication data. Change these two values as needed.
let sourceTimestamp = "2025-07-15T00:30:00Z"
let destinationIdentifier = "America/Los_Angeles"

enum ConversionError: Error {
    case invalidTimestamp(String)
    case unknownTimeZone(String)
}

let inputFormatter = ISO8601DateFormatter()
inputFormatter.formatOptions = [.withInternetDateTime]
inputFormatter.timeZone = TimeZone(secondsFromGMT: 0)

guard let instant = inputFormatter.date(from: sourceTimestamp) else {
    throw ConversionError.invalidTimestamp(sourceTimestamp)
}

guard let destination = TimeZone(identifier: destinationIdentifier) else {
    throw ConversionError.unknownTimeZone(destinationIdentifier)
}

let destinationFormatter = ISO8601DateFormatter()
destinationFormatter.formatOptions = [.withInternetDateTime]
destinationFormatter.timeZone = destination

let publicationLabelStyle = Date.FormatStyle(
    date: .long,
    time: .complete,
    locale: Locale(identifier: "en_GB"),
    calendar: Calendar(identifier: .gregorian),
    timeZone: destination
)

let publicationDateStyle = Date.FormatStyle(
    date: .long,
    time: .omitted,
    locale: Locale(identifier: "en_GB"),
    calendar: Calendar(identifier: .gregorian),
    timeZone: destination
)

print("Source instant: \(inputFormatter.string(from: instant))")
print("Destination zone: \(destination.identifier)")
print("Destination timestamp: \(destinationFormatter.string(from: instant))")
print("Publication label: \(instant.formatted(publicationLabelStyle))")
print("Publication date: \(instant.formatted(publicationDateStyle))")

Jalankan program yang telah disimpan:

swift "$HOME/Desktop/publication-time.swift"

Untuk nilai yang diberikan, stempel waktu tujuan seharusnya 2025-07-14T17:30:00-07:00, dan tanggal publikasi seharusnya menunjukkan 14 Juli 2025. Label yang mudah dibaca juga menyertakan informasi waktu dan zona; kata-kata serta tanda baca tepatnya berasal dari sistem pemformatan.

Program Swift ini telah ditinjau berdasarkan dokumentasi API yang diperoleh, tetapi tidak dijalankan di lingkungan riset karena Swift tidak tersedia. Contoh konversi numeriknya diperiksa secara terpisah menggunakan API tanggal/waktu dan zona di Python.

Pengaturan apa yang mengendalikan hasilnya?

Inisialisasi pemformat menerima pengaturan terpisah untuk lokal, kalender, dan zona waktu. Di sini, en_GB meminta konvensi pemformatan bahasa Inggris Britania, kalender Gregorian menyediakan sistem tanggal, dan destination menentukan tanggal lokal dan waktu jam. Ubah pengenal zona jika Anda memerlukan tujuan lain; ubah lokal jika Anda memerlukan konvensi penyajian lain. init(date:time:locale:calendar:timeZone:capitalizationContext:).

Hasil khusus tanggal tetap berasal langsung dari instant. Mengatur time: .omitted menghapus waktu dari label keluaran. Ini tidak mengharuskan pembuatan waktu absolut baru pada tengah malam.

Periksa perlintasan tengah malam dan offset musiman

Gunakan contoh sintetis berikut untuk memeriksa apakah hasil Anda mempertahankan operasi yang dimaksud. Ini adalah contoh stempel waktu publikasi, beserta representasi tujuan yang telah dihitung.

Waktu absolut asli Zona tujuan Representasi tujuan
2025-01-15T00:30:00Z America/Los_Angeles 2025-01-14T16:30:00-08:00
2025-07-15T00:30:00Z America/Los_Angeles 2025-07-14T17:30:00-07:00
2025-07-15T00:30:00Z Asia/Tokyo 2025-07-15T09:30:00+09:00
2025-07-15T23:30:00Z Asia/Tokyo 2025-07-16T08:30:00+09:00

Dua baris pertama menunjukkan mengapa penyesuaian tetap tidak memadai untuk tujuan bernama: offset yang berlaku dapat bergantung pada waktunya. Dua baris terakhir menunjukkan mengapa Anda harus menentukan tanggal kalender lengkap tujuan beserta waktunya. Publikasi dapat muncul pada hari sebelumnya, hari yang sama, atau hari berikutnya.

Zona bernama menggunakan aturan dari basis data zona waktu. IANA mendokumentasikan bahwa macOS menggunakan basis datanya dan pembaruan biasanya diterima klien melalui pembaruan sistem operasi. Jika hasil berbeda antar-mesin, periksa pengenal zona dan pembaruan yang tersedia sebelum mengubah stempel waktu sumber. Data zona waktu dan waktu musim panas.

Apa yang sebaiknya Anda lakukan jika masukan atau keluarannya tidak sesuai harapan?

Lakukan pemeriksaan berikut secara berurutan:

  1. Pastikan sumber mengidentifikasi suatu waktu absolut. Pertahankan Z atau offset numeriknya. Nilai khusus tanggal atau pembacaan jam lokal memerlukan informasi tambahan.
  2. Pastikan pengenal tujuan. Gunakan pengenal seperti America/Los_Angeles. Inisialisasi Apple mengembalikan nil untuk pengenal yang tidak dikenal; program ini berhenti dengan kesalahan alih-alih mengganti zona lain.
  3. Periksa bentuk stempel waktu yang didukung. Contoh ini dikonfigurasi untuk stempel waktu internet dengan detik penuh. Detik pecahan atau representasi masukan lain memerlukan konfigurasi pengurai yang sesuai. Pertahankan masukan asli saat melakukan perubahan itu.
  4. Bandingkan stempel waktu tujuan numerik. Gunakan tanggal, waktu, dan offsetnya untuk menilai konversi sebelum menyelidiki tanda baca tampilan.
  5. Pastikan setiap keluaran menggunakan instant asli. Hapus langkah perantara apa pun yang memformat label lalu mengurai label tersebut untuk konversi berikutnya. init(identifier:), ISO8601DateFormatter.

Zona bernama dan offset juga dapat disertakan bersama dalam stempel waktu yang diperluas berdasarkan RFC 9557. Keberadaan standar tersebut tidak membuktikan dukungan untuk anotasi zona dalam tanda kurung siku di pengurai contoh ini. Pertahankan pengenal tujuan di nilai destinationIdentifier terpisah yang digunakan di atas, kecuali Anda memang mengimplementasikan dan memverifikasi jalur masukan format diperluas. RFC 9557.

Untuk label publikasi, pertahankan waktu absolut asli sebagai nilai yang dapat digunakan kembali dan buat teks setiap tujuan darinya. Dengan begitu, Anda dapat mengubah zona tujuan, bahasa tampilan, atau detail yang terlihat sambil memastikan setiap label tetap merujuk pada momen publikasi yang sama.

Sumber