Untuk mengaudit setiap kunci pelokalan di app Mac, bangun target yang relevan, periksa setiap tabel string untuk semua bahasa yang didukung, lalu uji varian pesan di app yang berjalan. Kelengkapan katalog dan tampilan yang benar saat runtime perlu diperiksa secara terpisah.

Alur kerja ini ditujukan bagi developer yang memelihara app desktop Mac di Xcode. Tujuan konkretnya adalah menghasilkan catatan yang dapat ditelusuri tentang pesan yang hilang, terjemahan yang belum selesai, argumen yang keliru, dan masalah tampilan. Contohnya menggunakan label dan jumlah sintetis; contoh tersebut menjelaskan metode audit yang dapat Anda terapkan pada proyek sendiri.

Tentukan kriteria pesan yang lengkap

Mulailah dengan lembar kerja audit sederhana. Catat target app, bundel resource, tabel string, kunci, pelokalan yang didukung, varian yang diwajibkan, status terjemahan, dan hasil runtime. Perlakukan setiap kombinasi bundel–tabel–kunci sebagai identitas pesan tersendiri agar teks kunci yang sama di resource berbeda tidak menyamarkan kelalaian.

Apple menjelaskan bahwa API yang dapat dilokalkan bisa menentukan tabel dan bundel, dan bahwa resource di luar bundel utama memerlukan bundel yang sesuai untuk pencarian. Karena itu, memeriksa hanya file Localizable.xcstrings default dapat melewatkan pesan di bagian lain app. Lihat Mempersiapkan teks app untuk diterjemahkan.

Baca daftar pelokalan yang didukung proyek di editor proyek: pilih proyek di bawah Project, buka Info, lalu periksa Localizations. Periksa juga resource mana yang menggunakan pelokalan tersebut. Menambahkan dukungan untuk bahasa dan wilayah dari Apple menjelaskan pengaturan proyek dan pemilihan resource ini.

Untuk lembar kerja, Anda dapat menggunakan alias sintetis seperti Pelokalan A, Pelokalan B, dan Pelokalan C. Simpan pemetaan alias tersebut ke identifier pelokalan proyek yang sebenarnya dalam catatan kerja Anda. Alias ini adalah label lembar kerja, bukan nilai yang dimasukkan ke Xcode.

Gunakan kriteria penyelesaian berikut untuk audit. Ini adalah metode peninjauan yang diusulkan, bukan status penyelesaian yang ditetapkan Apple.

Pemeriksaan Bukti yang dicatat
Inventaris Pesan memiliki target, bundel, tabel, dan kunci yang teridentifikasi.
Penemuan Pesan diekstrak dari kode atau sengaja dikelola secara manual.
Cakupan Setiap pelokalan yang diwajibkan memiliki varian pesan yang diperlukan.
Argumen Setiap argumen mempertahankan makna dan tipe yang sesuai.
Runtime Pesan dan nilai yang benar muncul di antarmuka Mac yang relevan.
Tindak lanjut Setiap temuan diperbaiki, sengaja dikecualikan dengan alasan, atau masih terbuka.

Buat inventaris katalog sebelum meninjau terjemahan

Buka katalog string yang sudah ada di proyek. Jika sebuah target belum memiliki katalog, jalur pembuatan yang didokumentasikan Apple adalah File > New > File from Template, lalu pilih String Catalog. Nama default-nya adalah Localizable; gunakan nama tabel yang diharapkan oleh kode Anda. Pilih Product > Build untuk mengisi dan memperbarui katalog. Lihat Melokalkan dan memvariasikan teks dengan katalog string.

Bangun setiap skema Mac yang relevan, alih-alih menganggap satu build yang berhasil sudah mencakup seluruh inventaris. Apple menjelaskan bahwa ekstraksi menemukan string untuk skema dan platform saat ini. Pesan yang tidak muncul dalam satu build perlu diselidiki sebelum Anda menyimpulkan bahwa pesan itu tidak digunakan. Batasan ini dijelaskan dalam Menemukan Katalog String.

Periksa pengaturan build Use Compiler to Extract Swift Strings. Apple secara eksplisit mensyaratkan pengaturan ini agar semua teks Swift yang dapat dilokalkan tercakup dalam ekspor pelokalan. Jika Anda memerlukan salinan untuk pertukaran dalam pekerjaan penerjemahan, pilih proyek lalu pilih Product > Export Localizations, kemudian pilih pelokalan yang diperlukan. Paket .xcloc yang diekspor adalah Katalog Pelokalan Xcode, berbeda dari tabel string .xcstrings individual. Lihat Mengekspor pelokalan.

Selanjutnya, telusuri permukaan desktop app yang biasa: jendela utama, menu, toolbar, pengaturan, panel, tampilan kosong, dan label yang bergantung pada jumlah. Untuk setiap pesan milik app yang Anda temukan, cari entri lembar kerjanya. Pemeriksaan balik ini—dari antarmuka yang terlihat ke inventaris—membantu menemukan teks yang tidak pernah masuk ke katalog.

Jangan berasumsi bahwa ekstraksi menemukan semua ekspresi string sembarang. Apple menjelaskan ekstraksi melalui API yang dapat dilokalkan. Jika pesan yang diharapkan tidak ada, periksa cara kode membuat dan meneruskannya sebelum menambahkan entri kedua secara manual. Lihat Mempersiapkan teks app untuk diterjemahkan.

Pisahkan ekstraksi, pencarian, dan pemformatan runtime

Operasi ini menjawab pertanyaan yang berbeda. Ekstraksi menanyakan apakah Xcode dapat menemukan pesan selama pengembangan. Pencarian menentukan resource terlokalkan mana yang diminta app saat berjalan. Pemformatan runtime menyediakan konten variabel yang ditampilkan oleh pesan terpilih.

Untuk SwiftUI, tipe argumen penting. Literal seperti Text("Open collection") menggunakan pencarian terlokalkan. Meneruskan variabel String biasa ke initializer terkait biasanya menampilkan variabel itu tanpa pelokalan. Apple mendokumentasikan perbedaan ini dalam LocalizedStringKey.

Membuat LocalizedStringKey secara eksplisit dari variabel akan meminta pencarian, tetapi itu tidak memastikan bahwa ekstraksi saat build menemukan setiap kemungkinan nilai variabel. Untuk kunci yang dipilih secara dinamis, bandingkan seluruh kumpulan kunci yang diizinkan dengan katalog. Selidiki setiap nilai yang tidak cocok alih-alih hanya mengandalkan nilai yang kebetulan muncul selama pengujian.

Interpolasi juga berperan pada tingkat pesan. SwiftUI dapat mencari pesan terlokalkan yang berisi penentu format lalu mengganti nilai interpolasi sebelum merendernya. Apple merekomendasikan interpolasi untuk menyusun teks yang dapat dilokalkan dalam dokumentasi Text.

Pertimbangkan contoh pesan yang melaporkan jumlah item. Katalog menyimpan struktur pesan yang dapat dilokalkan beserta variannya; jumlah yang berubah merupakan bagian dari perilaku runtime. Menguji jumlah 1 dan 24 tidak seharusnya memerlukan dua kunci yang dikelola terpisah hanya karena angkanya berubah.

Label yang tampak masuk akal bukan bukti kuat bahwa pencarian berhasil. Apple menyatakan bahwa SwiftUI dapat menampilkan kuncinya sendiri jika tidak menemukan nilai terlokalkan. Jika kunci berupa teks yang mudah dibaca, masalah pencarian bisa tampak seperti label biasa. Pastikan pelokalan yang dipilih dan entri katalog sesuai dengan hasil yang ditampilkan. Lihat Mempersiapkan tampilan untuk pelokalan.

Tinjau setiap bahasa dan setiap varian yang diwajibkan

Kerjakan satu tabel dalam satu waktu dan satu pelokalan dalam satu waktu. Untuk setiap pesan, periksa status terjemahan, teks, argumen, dan variasi yang diperluas. Biarkan baris yang belum selesai tetap terbuka meskipun pesan di sekitarnya sudah lengkap.

Alur kerja katalog Apple membedakan entri New, Needs Review, entri yang sudah diterjemahkan, dan string Stale. Entri stale tidak lagi ditemukan dalam kode; entri yang dikelola secara manual tidak diperbarui atau dihapus otomatis selama sinkronisasi. Pastikan kunci stale memang tidak diperlukan sebelum menghapus terjemahannya. Lihat Menemukan Katalog String.

Untuk pesan yang bergantung pada jumlah, Control-klik kunci yang diinterpolasi lalu pilih Vary by Plural. Tinjau setiap bentuk yang disediakan Xcode untuk setiap pelokalan. Bentuk yang diwajibkan bisa berbeda, jadi menyamakan jumlah baris dengan pelokalan sumber bukan pemeriksaan yang memadai. Jika katalog menyertakan variasi perangkat, periksa nilai khusus Mac dan nilai umum. Apple mendokumentasikan kedua kontrol ini dalam Melokalkan dan memvariasikan teks dengan katalog string.

Periksa argumen berdasarkan maknanya sekaligus tampilannya. Untuk pesan sintetis yang melaporkan item di beberapa grup, tentukan argumen mana yang mewakili jumlah item dan mana yang mewakili jumlah grup. Terjemahan boleh mengubah posisi keduanya, tetapi maknanya harus tetap terjaga. Sesi katalog Apple menjelaskan posisi argumen, penentu tipe, dan substitusi bentuk jamak dalam Menemukan Katalog String.

Tambahkan konteks jika label pendek bermakna ganda. Komentar untuk Open, misalnya, dapat menjelaskan bahwa label itu adalah tindakan pada baris koleksi. Parameter SwiftUI comment membawa konteks tersebut ke keluaran pelokalan; Apple menjelaskannya dalam Mempersiapkan tampilan untuk pelokalan.

Gunakan matriks cakupan yang menampilkan pekerjaan yang belum selesai

Persentase tunggal berguna untuk melacak kemajuan katalog, tetapi audit memerlukan kolom terpisah untuk cakupan dan perilaku. Contoh berikut menunjukkan alasannya. Angkanya sintetis dan mewakili pasangan pesan–pelokalan, bukan pengukuran dari suatu app.

Misalkan inventaris berisi 48 pesan yang diwajibkan dan tiga pelokalan yang didukung. Jumlahnya menjadi 144 pasangan yang diwajibkan: 48 dikalikan 3. Setiap pasangan dapat memiliki cabang tambahan untuk bentuk jamak atau perangkat, yang perlu diperiksa tersendiri.

Pelokalan Pasangan yang diwajibkan Pemeriksaan katalog selesai Pemeriksaan runtime selesai
Pelokalan A 48 48 48
Pelokalan B 48 46 44
Pelokalan C 48 48 45
Total 144 142 137

Dalam contoh ini, dua pasangan masih memerlukan pekerjaan katalog dan tujuh belum menjalani pemeriksaan runtime. Kedua kelompok itu mungkin bertumpang tindih, jadi menjumlahkannya tidak akan menghasilkan hitungan akurat untuk pesan berbeda yang belum selesai. Simpan kedua temuan pada barisnya masing-masing.

Untuk setiap baris yang belum selesai, catat tindakan berikutnya secara spesifik: temukan pesan sumber yang hilang, lengkapi cabang bentuk jamak, verifikasi argumen, selidiki pemilihan bundel, atau periksa kembali antarmuka pada lebar yang lebih sempit. Dengan begitu, matriks menjadi antrean perbaikan, bukan laporan kemajuan semata.

Jalankan app Mac dalam setiap pelokalan yang didukung

Gunakan pengaturan skema Xcode untuk pemeriksaan app yang dapat diulang. Pilih Product > Scheme > Edit Scheme, pilih Run, buka Options, lalu pilih App Language dan App Region. Tutup dialog, pilih tujuan eksekusi Mac, lalu jalankan app. Ulangi untuk kombinasi yang didukung dalam audit Anda. Apple mendokumentasikan urutan ini dalam Menguji pelokalan saat menjalankan app.

Ikuti alur yang sama melalui antarmuka pada setiap eksekusi. Uji setiap pesan dengan keadaan yang relevan: koleksi kosong, satu item, beberapa item, dan label sintetis yang lebih panjang. Untuk pesan bentuk jamak, pilih nilai tambahan yang diperlukan guna menguji cabang yang ada dalam pelokalan tersebut; kumpulan angka kecil yang tetap tidak membuktikan cakupan semua cabang.

Periksa kalimat lengkap, nilai yang disisipkan, pembungkusan teks, pemotongan, serta lebar menu atau kontrol. Jika sebuah pesan memiliki dua jumlah, ubah keduanya secara terpisah. Misalnya, mengubah jumlah item sambil mempertahankan jumlah grup membantu mengungkap kesalahan pemetaan argumen.

Pratinjau SwiftUI dapat mempercepat siklus perbaikan. Apple mendukung pengaturan nilai lingkungan locale pada pratinjau dan pembuatan beberapa pratinjau terlokalkan setelah menambahkan atau mengimpor pelokalan tersebut. Gunakan pratinjau untuk memeriksa kembali tampilan yang bermasalah, lalu verifikasi jalur app yang sebenarnya. Lihat Mempratinjau pelokalan.

Tutup audit saat setiap pasangan pesan–pelokalan yang diwajibkan memiliki tindak lanjut terdokumentasi dan cabang yang diperlukan sudah diperiksa. Simpan inventaris, alur pengujian, dan temuan yang belum terselesaikan secara bersamaan. Catatan itu membuat audit berikutnya dapat ditindaklanjuti: lokasi pesan yang berubah diketahui, argumen yang diharapkan tercatat, varian yang diwajibkan teridentifikasi, dan tersedia cara berulang untuk memeriksa tampilannya.

Sumber