Untuk menghapus kunci lokalisasi yang tidak digunakan di Xcode, perlakukan entri Stale sebagai kandidat untuk ditinjau. Periksa konstruksi kunci saat runtime sebelum menghapusnya, pertahankan pesan dinamis yang diperlukan sebagai entri yang dikelola secara manual, dan uji layar aplikasi Mac yang terdampak setelah pembersihan.

Panduan ini ditujukan bagi pengembang yang memelihara aplikasi Mac SwiftUI dengan String Catalogs. Tugas ini adalah satu pembersihan katalog: mengidentifikasi pesan yang dapat dihapus sambil mempertahankan label dan pesan hitungan yang masih ditampilkan aplikasi. Panduan keputusan di bawah ini memisahkan bukti ekstraksi dari perilaku saat runtime.

Apa sebenarnya arti kunci lokalisasi yang kedaluwarsa?

Xcode menemukan string yang dapat dilokalisasi selama proses build. Apple menjelaskan bahwa ekstraksi mencakup skema dan platform yang sedang digunakan. Ketika string yang sebelumnya diekstrak tidak lagi ada, Xcode dapat menghapus entri yang belum diterjemahkan secara otomatis; entri yang memiliki terjemahan tetap ada dan menerima status Stale. Status itu berarti Xcode tidak lagi menemukan string tersebut di dalam kode. Apple secara eksplisit menyatakan bahwa penghapusan bergantung pada konfirmasi bahwa string tersebut tidak lagi diperlukan. Menemukan String Catalogs

Konsekuensi praktisnya, referensi sumber yang tidak ditemukan menjadi awal penyelidikan. Pencarian persis untuk panel.compact dapat menemukan referensi literal, tetapi tidak dapat memastikan apakah kode menyusun kunci tersebut dengan menggabungkan panel. dan mode yang dipilih. Tinjau kunci kandidat serta kode yang menghasilkan kunci pencarian.

Gunakan tabel tinjauan yang diusulkan ini untuk setiap kandidat. Tabel ini merupakan panduan keputusan yang diturunkan dari batas ekstraksi yang terdokumentasi, bukan fitur Xcode tambahan.

Bukti yang ditemukan saat peninjauan Keputusan Tindakan berikutnya
Layar yang dihapus adalah satu-satunya pengguna; tidak ada lagi pembentuk kunci saat runtime Hapus kandidat Hapus entri, lalu build ulang dan periksa perubahannya
Kode saat runtime masih dapat menghasilkan kunci persis ini Pertahankan Pertahankan melalui pengelolaan manual atau ganti pencarian dengan referensi lokal yang eksplisit
Kunci masih dirujuk di target lain atau kondisi build lain Pertahankan Build dan periksa konfigurasi yang relevan
Kunci dengan nama serupa ada di tabel lain Selidiki secara terpisah Pastikan tabel dan bundel sumber daya yang digunakan setiap pencarian
Tidak ditemukan pengguna, tetapi kode pembentuk kunci belum jelas Tunda Telusuri pembentuk kunci sebelum memutuskan penghapusan

Bagaimana menetapkan kondisi awal yang berguna di Xcode?

Pertama, simpan salinan katalog yang dapat dipulihkan atau commit kondisi saat ini. Lalu buka proyek aplikasi dan pilih skema Mac yang ingin ditinjau. Catat target dan konfigurasi bersyarat yang dapat menyediakan pesan untuk antarmuka terdampak; dengan demikian, peninjauan tetap terikat pada cakupan yang jelas.

Pilih katalog di navigator Project, lalu pilih Product > Build. Apple mendokumentasikan bahwa proses build mengisi dan memperbarui String Catalogs dari teks sumber yang dapat dilokalisasi. Setelah katalog dipilih, pilih Editor > Assistant, lalu pilih kunci untuk memeriksa lokasi sumbernya. Katalog juga menyediakan navigasi kembali ke sumber. Melokalisasi dan memvariasikan teks dengan string catalog

Jika string Swift yang diharapkan tidak muncul, periksa apakah pengaturan build Use Compiler to Extract Swift Strings untuk target tersebut diaktifkan. Apple mendokumentasikan prasyarat ini untuk ekstraksi oleh compiler. Katalog yang diisi dengan hasil ekstraksi tidak lengkap bukan kondisi awal yang baik untuk memutuskan apa yang harus dihapus. Melokalisasi app SwiftUI Anda

Untuk setiap kandidat, catat kunci, katalog, pengguna yang diduga, dan keputusan. Cari kunci persisnya terlebih dahulu, lalu awalan stabilnya dan pembungkus lokalisasi yang relevan. Periksa nilai model serta data pencarian yang disertakan dalam bundel dan menjadi masukan bagi pembungkus tersebut. Ulangi build yang relevan saat target lain atau kondisi kompilasi mengubah sumber yang disertakan.

Jangan gabungkan keputusan hanya karena dua entri menampilkan teks yang sama. API lokalisasi Apple menerima nama tabel, dan sumber daya di luar app utama mungkin memerlukan bundel yang berbeda. Telusuri tabel dan bundel yang digunakan pencarian sebelum menganggap entri lain sebagai pengganti. Menyiapkan teks app Anda untuk diterjemahkan

Bagaimana mempertahankan pesan yang dirujuk secara dinamis?

Apple secara khusus mendokumentasikan pengelolaan manual untuk string yang kuncinya dibuat secara dinamis. Pilih entri yang diperlukan dan gunakan inspektornya untuk menjadikannya dikelola secara manual. Entri semacam itu tidak diperbarui atau dihapus oleh sinkronisasi lokalisasi pascabuild Xcode. Untuk entri dinamis yang belum ada, Apple juga menunjukkan cara menambahkan string manual dengan tombol plus pada katalog. Menemukan String Catalogs

Pengelolaan manual memerlukan aturan pemeliharaan yang eksplisit. Catat kunci yang valid di samping kode atau data yang memilihnya, dan jelaskan penggunaannya dalam komentar katalog. Jika suatu mode yang didukung dihapus nanti, tinjau juga entri manualnya; ekstraksi otomatis tidak akan membersihkannya untuk Anda.

Periksa apakah SwiftUI benar-benar melakukan pencarian

Variabel String yang diteruskan ke Text ditampilkan tanpa lokalisasi. Untuk menggunakan variabel sebagai kunci pencarian, Apple mendokumentasikan pembuatan LocalizedStringKey darinya. Literal yang diteruskan langsung ke Text otomatis mengikuti jalur yang dapat dilokalisasi. Overload ini dapat menghasilkan keluaran bahasa sumber yang sama, tetapi perilakunya berbeda. LocalizedStringKey

Aplikasi demonstrasi lengkap berikut memisahkan kunci yang dipilih saat runtime dari hitungan yang diinterpolasi. Dalam proyek app Mac SwiftUI sementara yang menggunakan Xcode 15 atau lebih baru dan target deployment macOS 13, ganti deklarasi app yang dibuat otomatis dengan kode ini. Pastikan hanya ada satu deklarasi @main. Kode ini diperiksa berdasarkan API yang terdokumentasi; kode ini tidak dikompilasi di sini karena toolchain Swift tidak tersedia.

import SwiftUI

@main
struct CatalogReviewDemoApp: App {
    var body: some Scene {
        WindowGroup {
            CatalogReviewView()
        }
    }
}

struct CatalogReviewView: View {
    @State private var compact = true
    @State private var itemCount = 2

    private var selectedKey: String {
        "panel." + (compact ? "compact" : "expanded")
    }

    var body: some View {
        VStack(alignment: .leading, spacing: 12) {
            Toggle("Compact layout", isOn: $compact)

            Text(LocalizedStringKey(selectedKey))

            Text("\(itemCount) items",
                 comment: "Number of items in the sample panel.")

            Button("Add item") {
                itemCount += 1
            }
        }
        .padding()
        .frame(minWidth: 320)
    }
}

Tambahkan Localizable.xcstrings ke target app. Tambahkan entri yang dikelola secara manual untuk panel.compact dan panel.expanded, dengan nilai sumber Compact panel dan Expanded panel. Build proyek untuk mengekstrak pesan literal. Konversi LocalizedStringKey yang eksplisit meminta pencarian saat runtime; konversi itu tidak memberi ekstraktor deklarasi literal untuk setiap kemungkinan kunci yang dibuat.

Untuk sekumpulan pilihan yang kecil dan terbatas, pertimbangkan mengganti penyusunan kunci dengan literal yang dapat dilokalisasi dan eksplisit di setiap cabang. Untuk antarmuka khusus yang meneruskan pesan antarkomponen, Apple merekomendasikan LocalizedStringResource, yang membawa informasi lokalisasi seperti tabel, komentar, dan nilai default. Pilih representasi yang memudahkan pemeriksaan seluruh kumpulan pesan yang didukung. Menyiapkan teks app Anda untuk diterjemahkan

Mengapa hitungan yang berubah berbeda dari kunci yang berubah?

Dalam demonstrasi tersebut, pemilihan tata letak mengubah kunci pesan yang dicari aplikasi. Mengubah itemCount memberikan argumen berbeda kepada satu pesan yang dapat dilokalisasi. Interpolasi SwiftUI mengubah nilai yang disisipkan menjadi placeholder format untuk lokalisasi; rendering saat runtime mengisi nilainya. Melokalisasi app SwiftUI Anda

Karena itu, Anda tidak memerlukan kunci terpisah untuk label yang dirender seperti 2 items, 3 items, dan 4 items. Build contoh tersebut, temukan pesan hitungan yang diekstrak, Control-klik kuncinya, lalu pilih Vary by Plural. Untuk lokalisasi sumber bahasa Inggris, masukkan %lld item untuk One dan %lld items untuk Other, dengan menggunakan placeholder bilangan bulat yang ditampilkan Xcode. Apple mendokumentasikan alur kerja pesan hitungan ini serta penambahan varian jamak yang sesuai untuk lokalisasi lain yang didukung. Melokalisasi dan memvariasikan teks dengan string catalog

Saat melakukan pembersihan, periksa pesan hitungan sebagai sumber daya lengkap, termasuk variasinya. Tidak ditemukannya frasa yang dirender seperti 4 items dalam kode sumber tidak menunjukkan apakah pesan interpolasi yang mendasarinya digunakan. Demikian pula, mempertahankan templat hitungan tidak mempertahankan kunci dinamis yang tidak terkait hanya karena kedua pesan muncul di panel yang sama.

Entri mana yang sebenarnya harus dihapus dalam pembersihan?

Pertimbangkan peninjauan ilustratif terhadap 24 kandidat. Jumlah ini menggambarkan contoh sintetis, bukan hasil terukur dari suatu proyek.

Hasil peninjauan Entri Tindakan
Satu-satunya pengguna berasal dari panel yang dihapus 9 Hapus setelah memastikan panel dan data pencariannya sudah tidak ada
Kunci masih dapat dijangkau melalui pemilihan saat runtime 8 Pertahankan dan dokumentasikan pengelolaan manual
Referensi berada di target lain atau build bersyarat 5 Pertahankan dan verifikasi cakupan build tersebut
Asal kunci belum diketahui 2 Pertahankan sambil menunggu penyelidikan
Total yang ditinjau 24 9 kandidat untuk dihapus

Perhitungan ini membuat keputusan pembersihan dapat diaudit: meninjau 24 entri tidak berarti menghapus 24 entri. Untuk masing-masing dari sembilan kandidat penghapusan, simpan alasan singkat yang mengidentifikasi pengguna yang dihapus dan jalur pencarian saat runtime yang telah diperiksa. Untuk delapan entri dinamis, catat kumpulan kunci yang diizinkan agar peninjauan berikutnya dapat mengulangi keputusan tersebut.

Hapus hanya kandidat yang telah dikonfirmasi, lalu periksa diff katalog. Pastikan perubahan mencakup kunci yang dimaksud beserta terjemahan terkait, tanpa menghilangkan varian jamak atau perangkat yang tidak terkait. Build ulang konfigurasi yang relevan. Jika kunci yang dihapus muncul kembali melalui ekstraksi, tinjau kembali penggunanya sebelum menghapusnya lagi.

Bagaimana memverifikasi pesan yang dipertahankan di Mac Anda?

Gunakan Product > Scheme > Edit Scheme, pilih Run, lalu buka Options. Pilih lokalisasi yang didukung dan sudah tersedia dari App Language, tutup editor, lalu jalankan destinasi Mac. Apple mendokumentasikan kontrol skema ini untuk menguji build yang dilokalisasi. Ulangi untuk lokalisasi yang didukung app Anda. Menguji lokalisasi saat menjalankan app

Uji setiap pilihan dinamis yang diizinkan, termasuk kedua tata letak dalam demonstrasi. Pastikan app menampilkan nilai katalog yang diharapkan, bukan pengidentifikasi. Untuk pesan hitungan, periksa nilai sintetis seperti 0, 1, 2, dan 12, serta verifikasi kategori jamak tambahan bila diperlukan oleh lokalisasi yang didukung. Mengubah hitungan awal contoh sudah cukup untuk mencapai nilai pengujian tersebut.

Jika pesan yang dipertahankan ditampilkan secara keliru, periksa kunci, tabel, bundel, dan inisialisator Text yang tepat sebelum mengubah katalog. Alur kerja simbol hasil pembuatan yang lebih baru dari Apple juga dapat memudahkan referensi sumber daya manual: Xcode 26 memperkenalkan pembuatan simbol String Catalog, yang dapat diaktifkan untuk proyek yang sudah ada melalui Generate String Catalog Symbols. Ini merupakan jalur pemfaktoran ulang opsional, bukan bukti bahwa sumber daya manual yang tidak dirujuk tidak digunakan. Code-along: Jelajahi lokalisasi dengan Xcode

Akhiri dengan kumpulan kecil penghapusan yang alasannya jelas serta daftar pesan dinamis yang dipertahankan dan terdokumentasi. Hasil yang berguna adalah katalog yang setiap entri tersisanya memiliki pengguna yang dapat diidentifikasi, sementara kunci yang dipilih saat runtime dan pesan hitungan berformat tetap berfungsi di antarmuka Mac.

Sumber