Di Xcode 26 dan versi lebih baru, String Catalogs dapat membuat accessor Swift yang menggantikan kunci lokalisasi yang diketik manual. Panduan ini memigrasikan ringkasan pilihan aplikasi Mac kecil ke properti dan fungsi bertipe, lalu memeriksa hal-hal yang benar-benar dilindungi oleh compiler.

Tugas ini sengaja dibatasi: menampilkan judul jendela dan ringkasan yang berisi dua hitungan bilangan bulat. Semua label dan nilainya sintetis. Anda akan membuat kontrak katalog, menghubungkannya ke SwiftUI, lalu memverifikasi diagnostik compiler dan keluaran yang terlihat.

Apa yang membuat accessor lokalisasi diperiksa pada waktu kompilasi?

Apple memperkenalkan pembuatan simbol String Catalog bawaan di Xcode 26. Entri tanpa placeholder menghasilkan properti statis; entri dengan placeholder menghasilkan fungsi dengan parameter bertipe. Keduanya mengembalikan LocalizedStringResource. Proyek Xcode 26 baru mengaktifkan pembuatan ini secara default; proyek yang sudah ada mungkin perlu mengaktifkan setelan build tersebut. Praktik langsung: Jelajahi lokalisasi dengan Xcode

Perubahan yang berguna terjadi di titik pemanggilan. Literal string dapat menuliskan kunci pencarian tanpa merujuk ke deklarasi Swift. Accessor yang dibuat merujuk ke anggota yang harus ada, dan fungsi yang dibuat memerlukan argumen yang sesuai dengan signaturnya. Berdasarkan mekanisme yang didokumentasikan tersebut, konsekuensi praktisnya adalah anggota yang salah eja atau argumen yang tidak kompatibel akan menjadi galat compiler.

Perlindungan ini memiliki cakupan tertentu. Swift dapat memeriksa bahwa accessor tersedia dan argumennya sesuai. Swift tidak dapat menentukan apakah susunan katanya menggambarkan antarmuka yang dimaksud atau apakah dua argumen bilangan bulat yang valid mewakili hitungan yang benar. Perlakukan accessor sebagai antarmuka terperiksa untuk pesan Anda.

Siapkan aplikasi Mac kecil dan kontrak pesannya

Gunakan Xcode 26 atau versi lebih baru dan target aplikasi SwiftUI macOS. Untuk contoh ini, tetapkan target deployment ke macOS 15 atau versi lebih baru. Tipe LocalizedStringResource yang mendasarinya tersedia mulai macOS 13; target yang lebih tinggi pada contoh ini adalah pilihan prasyarat, bukan versi minimum untuk tipe tersebut. Resource merepresentasikan teks yang dapat dilokalkan dan pencariannya dapat ditangguhkan hingga diperlukan. LocalizedStringResource

Tambahkan katalog melalui File > New > File from Template. Pilih String Catalog di bawah Resource, beri nama Workbench, dan sertakan dalam target aplikasi. Apple mendokumentasikan bahwa setiap katalog merepresentasikan sebuah tabel; penggunaan tabel terpisah di sini menyatukan kedua pesan contoh. Melokalkan dan memvariasikan teks dengan katalog string

Di editor proyek, buka Build Settings, filter dengan Generate String, lalu setel Generate String Catalog Symbols ke Yes untuk konfigurasi efektif target. Inilah sakelar yang didokumentasikan untuk proyek lama. Menggunakan simbol lokal yang dibuat di kode Anda

Pilih lokalisasi sumber bahasa Inggris di Workbench.xcstrings. Tambahkan dua entri berikut menggunakan tombol + pada bilah alat editor katalog. Komentar menjelaskan makna pesan, termasuk fungsi argumennya.

Kunci Nilai sumber bahasa Inggris Komentar
TITLE Selection overview Judul di atas ringkasan pilihan.
SUBTITLE %1$(selectedCount)lld selected; %2$(availableCount)lld available Ringkasan pilihan. selectedCount adalah jumlah yang dipilih; availableCount adalah jumlah total yang tersedia, termasuk item yang dipilih.

Untuk SUBTITLE, Anda dapat memasukkan setiap placeholder melalui menu pelengkapan Xcode: ketik %, pilih placeholder bilangan bulat, lalu beri nama selectedCount atau availableCount. Apple mendokumentasikan variabel bernama dan parameter yang dibuat untuk penentu format ini. Pilih setiap entri dan periksa Generate Swift Symbol serta Example Usages di inspector Attributes. Menggunakan simbol lokal yang dibuat di kode Anda

Kontrak yang dimaksud adalah properti judul dan fungsi subjudul yang menerima dua nilai Int. Periksa ejaan aktual yang dibuat di inspector sebelum melanjutkan: Apple menyatakan bahwa nama simbol menggunakan kunci dan nilainya. Contoh di bawah menggunakan .Workbench.title dan .Workbench.subtitle(selectedCount:availableCount:), mengikuti pola kunci huruf besar yang didokumentasikan Apple. Praktik langsung: Jelajahi lokalisasi dengan Xcode

Kontrak ini memperjelas pembedaan yang berguna: availableCount mencakup item yang dipilih. Tanpa komentar itu, pemanggil mungkin menafsirkannya sebagai jumlah yang tersisa. Kedua penafsiran akan lolos pemeriksaan tipe, jadi mendokumentasikan maknanya merupakan bagian dari membuat accessor ini berguna.

Gunakan accessor yang dibuat di jendela lengkap

Setelah membuat katalog, pilih Product > Build. Ganti deklarasi aplikasi template dan tampilan konten dengan program berikut, dan pastikan hanya ada satu deklarasi @main di target. Katalog ini merupakan resource wajib bagi program tersebut; menempelkan Swift ke berkas mandiri tidak akan membuat accessornya.

import Foundation
import SwiftUI

@main
struct SelectionOverviewApp: App {
    var body: some Scene {
        WindowGroup {
            SelectionOverviewView(
                selectedCount: 3,
                availableCount: 12
            )
        }
    }
}

struct SelectionOverviewView: View {
    let selectedCount: Int
    let availableCount: Int

    var body: some View {
        VStack(alignment: .leading, spacing: 12) {
            Text(.Workbench.title)
                .font(.title2)

            Text(
                .Workbench.subtitle(
                    selectedCount: selectedCount,
                    availableCount: availableCount
                )
            )
        }
        .padding(24)
        .frame(minWidth: 360, minHeight: 140)
    }
}

Dengan lokalisasi sumber bahasa Inggris aktif, masukan ilustratif akan menampilkan Selection overview, lalu 3 selected; 12 available. Hitungannya tetap agar Anda dapat memeriksa penempatan argumen tanpa menambahkan kode pengelolaan pilihan.

Apple mendokumentasikan bahwa resource yang dibuat dapat digunakan di SwiftUI, termasuk Text, dan melalui inisialisator Foundation String(localized:). Jika antarmuka Mac yang sudah ada memerlukan String yang sudah diresolusikan, konversikan resource yang dibuat pada batas tersebut. Praktik langsung: Jelajahi lokalisasi dengan Xcode

Sebagai contoh, berikut fungsi helper lengkap yang dapat ditambahkan ke target aplikasi yang sama setelah katalog tersedia:

import Foundation

func selectionSummary(
    selectedCount: Int,
    availableCount: Int
) -> String {
    String(
        localized: .Workbench.subtitle(
            selectedCount: selectedCount,
            availableCount: availableCount
        )
    )
}

Mengembalikan LocalizedStringResource dari antarmuka Anda sendiri mempertahankan resource untuk pencarian nanti; mengembalikan String melakukan resolusi saat inisialisator dijalankan. Pilih sesuai kebutuhan antarmuka penerima. Apple menjelaskan perbedaan pencarian yang ditangguhkan dan langsung ini dalam dokumentasi Foundation. LocalizedStringResource

Contoh-contoh ini diperiksa berdasarkan dokumentasi yang diperoleh. Contoh-contoh tersebut tidak dikompilasi di sini karena lingkungan yang tersedia tidak memiliki executable Swift atau Xcode.

Mengapa titik di awal dan label argumen penting

Titik di awal adalah sintaks anggota implisit Swift. Sintaks ini menyingkat akses ke anggota tipe saat konteks di sekitarnya memungkinkan Swift menyimpulkan tipenya. Ini adalah sintaks Swift biasa, bukan operator khusus untuk kunci string. Ekspresi — Ekspresi Anggota Implisit

Untuk simbol lokalisasi yang dibuat, tabel default Localizable mengekspos anggota secara langsung, sedangkan tabel bernama memperkenalkan namespace tabel. Itulah sebabnya contoh ini menyertakan .Workbench sebelum nama anggota. Apple mendokumentasikan kedua bentuk tersebut. Menggunakan simbol lokal yang dibuat di kode Anda

Label selectedCount: dan availableCount: merupakan bagian dari pemanggilan fungsi. Swift membedakan label argumen yang muncul di titik pemanggilan dari nama parameter yang digunakan di dalam fungsi. Jika parameter memerlukan label, pemanggil harus menyertakannya. Fungsi — Label Argumen dan Nama Parameter Fungsi

Label yang mudah dibaca membantu mencegah kesalahan, tetapi kedua argumen di sini memiliki tipe yang sama. Menukar dua nilai bilangan bulat tetap merupakan Swift yang valid. Karena itu, kontrak pesan dan pemeriksaan keluaran yang terlihat melengkapi pemeriksaan compiler.

Migrasikan kunci yang sudah ada tanpa mengubah maknanya

Untuk string yang sudah dapat dilokalkan, Apple menyediakan alur kerja refaktorisasi. Pilih entri di String Catalog, Control-click, lalu pilih Refactor > Convert Strings to Symbols. Periksa pratinjau, sesuaikan nama simbol atau parameter yang diusulkan jika perlu, lalu pilih Convert. Menggunakan simbol lokal yang dibuat di kode Anda

Migrasikan satu kelompok yang selaras terlebih dahulu, seperti judul dan ringkasan untuk jendela ini. Sebelum menerima pratinjau, bandingkan pesan lama dengan kontrak baru: apakah keduanya menggunakan tabel yang sama, menggambarkan elemen antarmuka yang sama, dan memberikan makna yang sama pada setiap placeholder? Tinjau nilai terlokalisasi yang sudah ada dan terdampak oleh perubahan kunci, alih-alih menganggap refaktorisasi membuktikan kebenarannya.

Untuk titik pemanggilan yang tidak diperbarui oleh refaktorisasi, gunakan penggunaan yang dibuat di inspector katalog dan ganti referensi itu secara eksplisit. Kemudian build dan periksa teks yang dihasilkan. Hindari menghapus entri lama sebelum memastikan semua pemanggilnya telah ditangani.

Jika Xcode yang Anda pasang tidak memiliki pembuatan bawaan, alur kerja ini memerlukan toolchain yang lebih baru. Apple juga mendukung ekstraksi string dari API yang dapat dilokalkan ke dalam katalog, dan merekomendasikan ekstraksi sebagai alur kerja awal. Cara ini tetap didukung untuk mengelola lokalisasi, tetapi tidak dengan sendirinya menyediakan kontrak accessor yang dibuat dan dijelaskan di sini. Praktik langsung: Jelajahi lokalisasi dengan Xcode

Verifikasi migrasi dengan rangkaian diagnosis singkat

Gunakan pemeriksaan berikut pada jendela contoh. Pemeriksaan ini memisahkan perlindungan compiler dari kebenaran pesan dan integrasi resource.

  1. Build contoh tanpa perubahan untuk memastikan dasar yang berfungsi.
  2. Untuk sementara, salah eja anggota judul lalu build. Anggota yang tidak ada seharusnya menghasilkan diagnostik compiler. Pulihkan ejaannya.
  3. Untuk sementara, teruskan nilai String saat subjudul memerlukan Int. Build untuk memeriksa ketidakcocokan tipe, lalu pulihkan bilangan bulatnya.
  4. Jalankan dengan selectedCount disetel ke 3 dan availableCount disetel ke 12. Pastikan angka menempati posisi yang dimaksud.
  5. Ubah hanya nilai judul katalog menjadi Current selection, build ulang, lalu pastikan judul yang ditampilkan. Periksa bahwa tanda tangan yang dibuat tetap sama dengan yang digunakan kode Anda.

Jika anggota ternyata tidak ada, periksa terlebih dahulu penggunaan yang dibuat untuk entri katalog. Lalu periksa setelan pembuatan, keanggotaan target katalog, dan nama tabel. Diagnostik compiler menunjukkan referensi yang gagal; pemeriksaan ini membantu membedakan kesalahan ejaan dari deklarasi yang belum tersedia.

Terakhir, uji antarmuka yang sebenarnya. Jalur yang didokumentasikan Apple adalah Product > Scheme > Edit Scheme, lalu Run > Options, tempat Anda dapat memilih App Language sebelum menjalankan aplikasi. Ulangi untuk lokalisasi yang didukung proyek Anda. Menguji lokalisasi saat menjalankan aplikasi

Untuk pemeriksaan tata letak awal, Xcode juga menyediakan Double-Length Pseudolanguage, yang memperpanjang teks yang dapat dilokalkan untuk mengungkap masalah ukuran. Periksa ringkasan pada lebar jendela yang sempit; kompilasi yang berhasil tidak memastikan bahwa teks muat. Menguji lokalisasi

Migrasi yang selesai memberi setiap titik pemanggilan anggota Swift yang nyata, memberi setiap variabel peran yang terdokumentasi, dan mempertahankan jalur terperiksa menuju entri katalog yang dimaksud. Lakukan pemeriksaan compiler dan jendela secara bersamaan: pemeriksaan pertama memvalidasi kontrak accessor, sedangkan pemeriksaan kedua memastikan pembaca melihat pesan yang dimaksud.

Sumber