Untuk menyatukan pesan berulang dalam aplikasi Mac, berikan satu kunci pelokalan dan satu definisi Swift untuk setiap makna yang sama, lalu gunakan definisi itu di setiap tempat pesan tersebut muncul. Pertahankan argumen, aturan bentuk jamak, dan konteks penerjemahnya secara bersamaan; teks bahasa Inggris yang cocok saja tidak cukup.

Panduan ini ditujukan bagi pengembang Mac yang mengelola ringkasan pilihan di SwiftUI dan jendela Interface Builder. Tugas konkretnya adalah menampilkan pesan seperti 2 item dipilih di Batch A. secara konsisten, tanpa mengelola templat kalimat terpisah dalam XIB dan kode Swift. Semua jumlah dan label di bawah ini bersifat sintetis.

Tentukan pesan berulang mana yang termasuk dalam satu kelompok

Sebelum mengedit katalog, tentukan kontrak pesan: makna kalimat, nilai yang diterimanya, dan tempat kemunculannya. Untuk contoh ini, kontraknya adalah:

Elemen kontrak Definisi
Makna Jumlah item yang saat ini dipilih dalam koleksi bernama
Kunci selection.summary
Tabel Localizable
Bundle Bundle utama aplikasi
Argumen 1 Jumlah pilihan bertipe Int64
Argumen 2 Label koleksi literal, seperti Batch A
Variasi Bentuk jamak ditentukan oleh jumlah pilihan
Konteks Kalimat status lengkap yang ditampilkan di SwiftUI dan label AppKit

Gunakan kontrak ini untuk menguji penyatuan. Dua kemunculan dapat menggunakan pesan yang sama jika makna, argumen, dan peran gramatikalnya sesuai. Jumlah item yang dipilih dan jumlah seluruh item harus tetap terpisah meskipun keduanya saat ini menampilkan 2 item. Tombol bernama Pilih juga memerlukan pesan tersendiri karena menyatakan suatu tindakan.

Apple mendukung kunci eksplisit dengan nilai default terpisah secara khusus untuk memperjelas teks. Dengan begitu, Anda dapat menamai pesan berdasarkan tujuannya sambil mempertahankan redaksi sumber yang mudah dibaca. Komentar memberikan konteks; kunci mengidentifikasi entri. Inisialisasi kunci eksplisit String.

Jadikan tabel dan bundle sebagai bagian dari kontrak pencarian juga. Kunci dalam tabel lain adalah sasaran pencarian yang berbeda. Apple mendokumentasikan pemilihan tabel melalui parameter table atau tableName dan menyarankan agar teks yang dapat dilokalkan diteruskan melalui LocalizedStringResource. Untuk contoh ini, letakkan helper dan katalog di target aplikasi, lalu gunakan bundle utama. Menyiapkan teks aplikasi untuk diterjemahkan.

Pahami batas antara ekstraksi dan pemformatan saat runtime

Ekstraksi berlangsung saat Xcode membangun aplikasi: proses ini menemukan ekspresi yang didukung dan dapat dilokalkan, lalu menyinkronkan teks sumbernya dengan katalog. Pelokalan saat runtime terjadi ketika aplikasi mencari pesan dan mengganti nilai aktual. Menemukan entri dalam katalog membuktikan bahwa ekstraksi menemukannya; hal itu tidak membuktikan bahwa setiap kontrol menampilkannya dengan benar.

Interface Builder memiliki alur kerja sumber dayanya sendiri. Apple mendokumentasikan katalog yang dipasangkan dengan storyboard atau XIB, sedangkan kode Swift biasanya berkontribusi ke tabel Localizable. Alur kerja yang didokumentasikan tidak menjelaskan alias lintas sumber daya yang menggabungkan pesan hanya karena redaksi yang terlihat sama. Cara praktis yang didukung adalah menetapkan pesan terlokalisasi bersama dari Swift setelah antarmuka dimuat. Implementasi ini didasarkan pada API yang didokumentasikan Apple. Mengenal String Catalog.

SwiftUI juga membedakan kunci pelokalan literal dari nilai string biasa. Misalnya, Text("Summary") meminta pelokalan, sedangkan meneruskan variabel String akan menampilkan nilainya tanpa pencarian tersebut. Membungkus string runtime dalam LocalizedStringKey meminta pencarian, tetapi jangan menganggapnya sebagai bukti bahwa ekstraksi menemukan semua kemungkinan nilainya. LocalizedStringKey.

Karena itu, rancangan di bawah mempertahankan literal yang dapat diekstrak dalam satu helper. Helper tersebut menyimpan jumlah dan label dalam LocalizedStringResource, lalu menyelesaikan sumber daya itu di tempat string jadi diperlukan. Apple menjelaskan bahwa jenis sumber daya ini menunda pencarian pelokalan. Jenis ini tersedia di macOS 13 dan versi lebih baru, yang menjadi target minimum untuk contoh ini. LocalizedStringResource.

Definisikan pesan bersama sekali di Swift

Buat proyek aplikasi macOS menggunakan SwiftUI, tetapkan target penerapan ke macOS 13 atau versi lebih baru, lalu tambahkan Localizable.xcstrings ke target aplikasi. Dalam dokumentasi Xcode saat ini, jalur pembuatannya adalah File > New > File from Template; cari string dan pilih String Catalog. Melokalkan dan memvariasikan teks dengan string catalog.

Ganti titik masuk aplikasi yang dihasilkan dengan program lengkap di bawah ini. Hapus titik masuk aplikasi yang asli agar target hanya berisi satu deklarasi @main. Jendela SwiftUI berjalan secara terpisah dari XIB; subclass AppKit yang disertakan digunakan saat mengadaptasi label Interface Builder yang sudah ada di bagian berikutnya.

import AppKit
import Foundation
import SwiftUI

enum SelectionMessages {
    static func summary(
        count: Int64,
        collectionLabel: String
    ) -> LocalizedStringResource {
        LocalizedStringResource(
            "selection.summary",
            defaultValue: "\(count) items selected in \(collectionLabel).",
            table: "Localizable",
            comment: "Complete selection-status sentence used in SwiftUI and an AppKit label. Argument 1 is the selected-item count; argument 2 is a literal collection label. Pluralize by argument 1."
        )
    }
}

struct SelectionDemoView: View {
    private let counts: [Int64] = [0, 1, 2]
    private let collectionLabel = "Batch A"

    var body: some View {
        VStack(alignment: .leading, spacing: 12) {
            ForEach(counts, id: \.self) { count in
                Text(String(localized: SelectionMessages.summary(
                    count: count,
                    collectionLabel: collectionLabel
                )))
            }
        }
        .padding(24)
        .frame(minWidth: 360, minHeight: 160)
    }
}

final class SelectionSummaryField: NSTextField {
    override func awakeFromNib() {
        super.awakeFromNib()
        // Synthetic initial state for the Interface Builder example.
        updateSelection(count: 2, collectionLabel: "Batch A")
    }

    func updateSelection(count: Int64, collectionLabel: String) {
        stringValue = String(localized: SelectionMessages.summary(
            count: count,
            collectionLabel: collectionLabel
        ))
    }
}

@main
struct SelectionDemoApp: App {
    var body: some Scene {
        WindowGroup {
            SelectionDemoView()
        }
    }
}

Kunci statis mengidentifikasi pesan; nilai default yang diinterpolasi menyediakan kalimat sumber dan argumen runtime. Inisialisasi ini juga menerima tabel, bundle, dan komentar untuk penerjemah. Bundle default-nya adalah bundle utama. Inisialisasi kunci eksplisit LocalizedStringResource.

Label Batch A adalah konten contoh yang disisipkan ke dalam kalimat. Label ini bukan kunci pesan lain. Pembedaan ini menjaga agar label koleksi tetap terpisah dari redaksi antarmuka di sekitarnya. Jika aplikasi nyata Anda menggunakan nama koleksi yang sudah ditentukan dan diterjemahkan, lokalkan nama-nama tersebut melalui definisinya sendiri sebelum memberikannya di sini.

Jangan menyusun kalimat ini dari bagian-bagian yang dilokalkan secara terpisah, seperti jumlah, item dipilih di, dan label. Dengan mempertahankan kalimat lengkap dalam kontrak, pelokalisasi dapat menyesuaikan redaksi dan urutan argumennya secara bersamaan.

Arahkan label Interface Builder melalui definisi yang sama

Untuk XIB atau storyboard yang sudah ada, gunakan label NSTextField statis untuk ringkasan. Tetapkan kelas khususnya ke SelectionSummaryField dan modulnya ke target aplikasi. Hapus kalimat lama dari nilai string saat desain, karena label ini kini menerima teksnya dari definisi Swift bersama.

Saat antarmuka dimuat, subclass memanggil super.awakeFromNib() dan menetapkan ringkasan awal sintetis. Apple mendokumentasikan awakeFromNib() sebagai hook setelah pemuatan, saat koneksi outlet dan aksi sudah dibuat, serta mewajibkan pemanggilan implementasi superclass. awakeFromNib().

Di jendela nyata, panggil updateSelection(count:collectionLabel:) pada label yang terhubung setiap kali pilihan berubah, menggunakan nilai model yang sama dengan yang diberikan ke SwiftUI. Ganti penetapan awal sintetis dengan jalur inisialisasi jendela yang sebenarnya. Penetapan satu kali saat pemuatan tidak dapat mengikuti perubahan pilihan berikutnya.

Adaptor AppKit menetapkan stringValue, cara yang didokumentasikan untuk menetapkan teks NSTextField. Dengan demikian, tata letak tetap di Interface Builder sementara kepemilikan pesan berpindah ke Swift. Sediakan lebar yang cukup atau aktifkan pembungkusan teks agar kalimat lengkap dapat ditampilkan. NSTextField.

Pertahankan teks antarmuka statis lain yang tidak terkait dalam alur kerja sumber daya yang sudah ada. Migrasi ini mencakup satu pesan bersama; memindahkan setiap label ke Swift tidak diperlukan. Pastikan juga bahwa binding atau penetapan oleh pengontrol lain tidak mengganti ringkasan dengan redaksi lama setelahnya.

Konfigurasikan variasi bentuk jamak tanpa mengubah argumennya

Pilih Product > Build, buka Localizable.xcstrings, lalu cari selection.summary. Klik entri sambil menekan Control, pilih Vary by Plural, lalu pilih argumen jumlah numerik jika Xcode menanyakan argumen mana yang akan divariasikan. Apple mendokumentasikan alur kerja ini untuk pesan yang diinterpolasi. Melokalkan dan memvariasikan teks dengan string catalog.

Untuk pelokalan sumber bahasa Inggris, buat varian tunggal menghasilkan 1 item dipilih di Batch A. dan varian lainnya menghasilkan kalimat seperti 2 item dipilih di Batch A. Pertahankan kedua placeholder argumen yang disediakan Xcode. Edit redaksi di sekitarnya alih-alih mengganti placeholder dengan jumlah atau label contoh.

Masukan sintetis Hasil bahasa Inggris yang diharapkan setelah konfigurasi bentuk jamak
Jumlah 0, label Batch A 0 item dipilih di Batch A.
Jumlah 1, label Batch A 1 item dipilih di Batch A.
Jumlah 2, label Batch A 2 item dipilih di Batch A.
Jumlah 2, label Batch B 2 item dipilih di Batch B.

Ini adalah kasus penerimaan ilustratif, bukan hasil pengukuran. Sebelum konfigurasi bentuk jamak, kalimat sumber default tetap memuat items untuk setiap jumlah. Ekstraksi mempertahankan pesan yang diinterpolasi; proses ini tidak memperbaiki tata bahasanya secara otomatis.

Perubahan label pada baris terakhir berguna untuk diagnosis: jika tampilan tetap menunjukkan Batch A, nilai contoh mungkin di-hardcode dalam sebuah varian atau pemanggil mungkin memberikan status usang. Jika label hilang, periksa placeholder varian sebelum mengubah tanda tangan helper.

Verifikasi setiap jalur tampilan sebelum menghapus entri lama

Uji jendela SwiftUI dan jendela Interface Builder yang sebenarnya secara terpisah. Gunakan jumlah dan label yang sama pada keduanya. Periksa pemuatan awal, perubahan pilihan berikutnya, dan label sintetis yang lebih panjang seperti Batch A Extended. Pastikan redaksinya sama dan kalimatnya tetap mudah dibaca.

Untuk setiap pelokalan yang didukung, pilih Product > Scheme > Edit Scheme, pilih Run, buka Options, lalu atur App Language. Jalankan aplikasi lagi dan periksa kedua jalur tampilan. Apple mendokumentasikan pengaturan skema ini untuk menguji pelokalan tanpa mengubah bahasa seluruh sistem. Menguji pelokalan saat menjalankan aplikasi.

Gunakan urutan berikut jika hasilnya keliru:

  1. Entri tidak ada: Pastikan katalog termasuk dalam target aplikasi, lalu bangun skema yang relevan. Periksa apakah Use Compiler to Extract Swift Strings diaktifkan.
  2. Redaksi sumber muncul secara tak terduga: Periksa kunci, tabel, bundle, dan terjemahan sebelum menganggap teks fallback yang mudah dibaca sebagai tanda berhasil.
  3. Hanya label Interface Builder yang berbeda: Periksa kelas khusus, modul, jalur pemuatan, dan penetapan berikutnya.
  4. Hanya nilai berikutnya yang berbeda: Pastikan kedua antarmuka menerima nilai model yang diperbarui.
  5. Redaksi bentuk jamak keliru: Periksa argumen numerik yang dipilih untuk variasi dan setiap varian yang berlaku.

Apple mendokumentasikan pengaturan ekstraksi compiler dan menjelaskan bahwa entri terjemahan yang tidak lagi ditemukan dalam sumber dapat tetap berstatus Stale. Status tersebut adalah sinyal untuk pembersihan, bukan bukti bahwa sumber daya itu tidak digunakan. Periksa penetapan antarmuka lama dan pemanggil Swift sebelum menghapus entri beserta terjemahannya. Mengenal String Catalog.

Penyatuan selesai ketika kedua antarmuka memperoleh pesan kontekstual yang sama dari satu definisi, argumennya tetap utuh, dan templat kalimat lama tidak lagi memiliki pemanggil. Simpan kontrak dan kasus penerimaan di samping helper agar perubahan redaksi mendatang tetap mempertahankan makna yang digunakan bersama oleh kedua jendela.

Sumber