Dalam Xcode 26 dan versi lebih baharu, Katalog Rentetan boleh menjana pengakses Swift untuk menggantikan kunci penyetempatan yang ditaip secara manual. Panduan ini memindahkan ringkasan pilihan aplikasi Mac kecil kepada sifat dan fungsi bertip, kemudian menyemak perkara yang benar-benar dilindungi oleh pengkompil.

Skop tugas ini sengaja dihadkan: paparkan tajuk tetingkap dan ringkasan yang mengandungi dua kiraan integer. Semua label dan nilai adalah sintetik. Anda akan mencipta kontrak katalog, menyambungkannya kepada SwiftUI, dan mengesahkan diagnostik pengkompil serta output yang kelihatan.

Apakah yang menjadikan pengakses penyetempatan disemak pada masa kompilasi?

Apple memperkenalkan penjanaan simbol Katalog Rentetan natif dalam Xcode 26. Entri tanpa pemegang tempat menghasilkan sifat statik; entri dengan pemegang tempat menghasilkan fungsi dengan parameter bertip. Kedua-duanya memulangkan LocalizedStringResource. Projek Xcode 26 baharu mendayakan penjanaan secara lalai; projek sedia ada mungkin perlu mendayakan tetapan binaan tersebut. Ikuti bersama: Terokai penyetempatan dengan Xcode

Perubahan yang berguna berlaku pada tempat panggilan. Literal rentetan boleh menulis kunci carian tanpa merujuk kepada pengisytiharan Swift. Pengakses yang dijana merujuk kepada ahli yang mesti wujud, dan fungsi yang dijana memerlukan argumen yang sepadan dengan tandatangannya. Berdasarkan mekanik yang didokumenkan itu, kesan praktikalnya ialah ahli yang tersalah eja atau argumen yang tidak serasi akan menjadi ralat pengkompil.

Perlindungan itu mempunyai skop tertentu. Swift boleh menyemak bahawa pengakses wujud dan argumennya sepadan. Swift tidak dapat menentukan sama ada perkataan itu menggambarkan antara muka yang dimaksudkan, atau sama ada dua argumen integer yang sah mewakili kiraan yang betul. Anggap pengakses sebagai antara muka pengaturcaraan yang disemak untuk mesej anda.

Sediakan aplikasi Mac kecil dan kontrak mesejnya

Gunakan Xcode 26 atau versi lebih baharu dan sasaran aplikasi SwiftUI macOS. Untuk contoh ini, tetapkan sasaran penggunaan kepada macOS 15 atau versi lebih baharu. Jenis asas LocalizedStringResource tersedia mulai macOS 13; sasaran lebih tinggi dalam contoh ini ialah pilihan prasyarat, bukannya versi minimum untuk jenis tersebut. Sumber mewakili teks boleh setempat yang pencariannya boleh ditangguhkan sehingga diperlukan. LocalizedStringResource

Tambah katalog melalui File > New > File from Template. Pilih String Catalog di bawah Resource, namakannya Workbench, dan sertakannya dalam sasaran aplikasi. Apple mendokumenkan bahawa setiap katalog mewakili satu jadual; penggunaan jadual berasingan di sini menghimpunkan dua mesej contoh. Menyetempatkan dan mempelbagaikan teks dengan katalog rentetan

Dalam editor projek, buka Build Settings, tapis untuk Generate String, dan tetapkan Generate String Catalog Symbols kepada Yes untuk konfigurasi berkesan sasaran. Inilah suis yang didokumenkan untuk projek lama. Menggunakan simbol setempat yang dijana dalam kod anda

Pilih penyetempatan sumber bahasa Inggeris dalam Workbench.xcstrings. Tambahkan dua entri ini menggunakan butang + pada bar alat editor katalog. Komen mentakrifkan maksud mesej, termasuk peranan argumennya.

Kunci Nilai sumber bahasa Inggeris Komen
TITLE Selection overview Heading above the selection summary.
SUBTITLE %1$(selectedCount)lld selected; %2$(availableCount)lld available Selection summary. selectedCount is the number selected; availableCount is the total number available, including selected items.

Untuk SUBTITLE, anda boleh memasukkan setiap pemegang tempat melalui menu pelengkapan Xcode: taip %, pilih pemegang tempat integer, dan namakannya selectedCount atau availableCount. Apple mendokumenkan pemboleh ubah bernama dan parameter yang dijana untuk penentu format ini. Pilih setiap entri dan periksa Generate Swift Symbol serta Example Usages dalam pemeriksa Attributes. Menggunakan simbol setempat yang dijana dalam kod anda

Kontrak yang dimaksudkan ialah sifat tajuk dan fungsi sari kata yang menerima dua nilai Int. Semak ejaan sebenar yang dijana dalam pemeriksa sebelum meneruskan: Apple menyatakan bahawa nama simbol menggunakan kedua-dua kunci dan nilainya. Contoh di bawah menggunakan .Workbench.title dan .Workbench.subtitle(selectedCount:availableCount:), mengikut corak kunci huruf besar yang didokumenkan Apple. Ikuti bersama: Terokai penyetempatan dengan Xcode

Kontrak ini menjelaskan satu perbezaan penting: availableCount merangkumi item yang dipilih. Tanpa komen itu, pemanggil mungkin mentafsirkannya secara munasabah sebagai bilangan item yang masih ada. Kedua-dua tafsiran akan lulus semakan jenis, jadi mendokumenkan maksudnya ialah sebahagian daripada usaha menjadikan pengakses berguna.

Gunakan pengakses yang dijana dalam tetingkap lengkap

Selepas mencipta katalog, pilih Product > Build. Gantikan pengisytiharan aplikasi templat dan paparan kandungan dengan program berikut, sambil memastikan hanya terdapat satu pengisytiharan @main dalam sasaran. Katalog ialah sumber wajib untuk program ini; menampal Swift ke dalam fail kendiri tidak akan menjana pengaksesnya.

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 penyetempatan sumber bahasa Inggeris aktif, input ilustrasi sepatutnya memaparkan Selection overview diikuti 3 selected; 12 available. Kiraan ini ditetapkan supaya anda boleh menyemak kedudukan argumen tanpa memperkenalkan kod pengurusan pilihan.

Apple mendokumenkan bahawa sumber yang dijana boleh digunakan dalam SwiftUI, termasuk Text, dan melalui pemula String(localized:) milik Foundation. Jika antara muka Mac sedia ada memerlukan String yang telah diselesaikan, tukarkan sumber yang dijana pada sempadan tersebut. Ikuti bersama: Terokai penyetempatan dengan Xcode

Sebagai contoh, berikut ialah fungsi pembantu lengkap untuk ditambah kepada sasaran aplikasi yang sama selepas katalog tersedia:

import Foundation

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

Memulangkan LocalizedStringResource daripada antara muka anda sendiri mengekalkan sumber untuk carian kemudian; memulangkan String menyelesaikannya apabila pemula dijalankan. Pilih berdasarkan keperluan antara muka penerima. Apple menerangkan perbezaan antara carian tertangguh dengan serta-merta ini dalam dokumentasi Foundation. LocalizedStringResource

Contoh ini diperiksa berdasarkan dokumentasi yang diperoleh. Contoh tersebut tidak dikompil di sini kerana persekitaran yang tersedia tiada boleh laku Swift atau Xcode.

Sebab titik di hadapan dan label argumen penting

Titik di hadapan ialah sintaks ahli tersirat Swift. Sintaks ini meringkaskan akses kepada ahli jenis apabila konteks sekeliling membolehkan Swift membuat inferens tentang jenisnya. Ini sintaks Swift biasa, bukannya operator kunci rentetan khas. Ungkapan — Ungkapan Ahli Tersirat

Bagi simbol penyetempatan yang dijana, jadual lalai Localizable mendedahkan ahli secara langsung, manakala jadual bernama memperkenalkan ruang nama jadual. Itulah sebabnya contoh ini menyertakan .Workbench sebelum nama ahli. Apple mendokumenkan kedua-dua bentuk. Menggunakan simbol setempat yang dijana dalam kod anda

Label selectedCount: dan availableCount: ialah sebahagian daripada panggilan fungsi. Swift membezakan label argumen yang muncul pada tempat panggilan daripada nama parameter yang digunakan di dalam fungsi. Apabila parameter memerlukan label, pemanggil mesti membekalkannya. Fungsi — Label Argumen dan Nama Parameter Fungsi

Label yang jelas membantu mencegah kesilapan, tetapi kedua-dua argumen di sini mempunyai jenis yang sama. Menukar kedudukan kedua-dua nilai integer tetap sah dalam Swift. Oleh itu, kontrak mesej dan semakan output yang kelihatan melengkapi pengkompil.

Pindahkan kunci sedia ada tanpa menghilangkan maksudnya

Untuk rentetan setempat sedia ada, Apple menyediakan aliran kerja pemfaktoran semula. Pilih entri dalam Katalog Rentetan, klik sambil menekan Control, dan pilih Refactor > Convert Strings to Symbols. Periksa pratonton, laraskan simbol atau nama parameter yang dicadangkan jika perlu, kemudian pilih Convert. Menggunakan simbol setempat yang dijana dalam kod anda

Pindahkan satu kumpulan yang padu dahulu, seperti tajuk dan ringkasan untuk tetingkap ini. Sebelum menerima pratonton, bandingkan mesej lama dengan kontrak baharu: adakah kedua-duanya menggunakan jadual yang sama, menggambarkan elemen antara muka yang sama, dan memberikan maksud yang sama kepada setiap pemegang tempat? Semak sebarang nilai setempat sedia ada yang terjejas oleh perubahan kunci, dan jangan menganggap pemfaktoran semula membuktikan ketepatannya.

Bagi tempat panggilan yang tidak dikemas kini oleh pemfaktoran semula, gunakan penggunaan yang dijana dalam pemeriksa katalog dan gantikan rujukan itu secara jelas. Kemudian bina dan periksa teks yang terhasil. Elakkan memadam entri lama sehingga anda mengambil kira semua pemanggilnya.

Jika Xcode yang dipasang tidak mempunyai penjanaan natif, aliran kerja ini memerlukan rantaian alat yang lebih baharu. Apple juga menyokong pengekstrakan rentetan daripada API boleh setempat ke dalam katalog, dan mengesyorkan pengekstrakan sebagai aliran kerja permulaan. Kaedah itu kekal sebagai cara yang disokong untuk mengurus penyetempatan, tetapi kaedah itu sendiri tidak membekalkan kontrak pengakses yang dijana seperti yang diterangkan di sini. Ikuti bersama: Terokai penyetempatan dengan Xcode

Sahkan pemindahan dengan urutan diagnostik ringkas

Gunakan semakan berikut pada tetingkap contoh. Semakan ini membezakan perlindungan pengkompil daripada ketepatan mesej dan penyepaduan sumber.

  1. Bina contoh tanpa perubahan untuk menetapkan garis dasar yang berfungsi.
  2. Buat sementara waktu, salah eja ahli tajuk dan bina. Ahli yang tidak wujud sepatutnya menghasilkan diagnostik pengkompil. Pulihkannya.
  3. Buat sementara waktu, berikan nilai String apabila sari kata memerlukan Int. Bina untuk menyemak ketidakpadanan jenis, kemudian pulihkan nilai integer.
  4. Jalankan dengan selectedCount ditetapkan kepada 3 dan availableCount ditetapkan kepada 12. Pastikan nombor berada pada kedudukan yang dimaksudkan.
  5. Ubah hanya nilai tajuk katalog kepada Current selection, bina semula, dan pastikan tajuk yang dipaparkan berubah. Semak bahawa tandatangan yang dijana kekal sama seperti yang digunakan oleh kod anda.

Jika ahli hilang secara tidak dijangka, periksa dahulu penggunaan yang dijana bagi entri katalog. Kemudian semak tetapan penjanaan, keahlian katalog dalam sasaran, dan nama jadual. Diagnostik pengkompil mengenal pasti rujukan yang gagal; semakan ini membantu membezakan kesilapan ejaan daripada pengisytiharan yang dijana tetapi tidak tersedia.

Akhir sekali, uji antara muka sebenar. Laluan yang didokumenkan Apple ialah Product > Scheme > Edit Scheme, kemudian Run > Options, tempat anda boleh memilih App Language sebelum menjalankan aplikasi. Ulangi untuk penyetempatan yang disokong oleh projek anda. Menguji penyetempatan semasa menjalankan aplikasi anda

Untuk semakan susun atur awal, Xcode juga menawarkan Double-Length Pseudolanguage, yang memanjangkan teks boleh setempat untuk mendedahkan masalah saiz. Periksa ringkasan pada lebar tetingkap yang sempit; kompilasi yang berjaya tidak dapat memastikan teks muat. Uji penyetempatan

Pemindahan yang selesai memberikan setiap tempat panggilan ahli Swift sebenar, memberikan setiap pemboleh ubah peranan yang didokumenkan, dan mengekalkan laluan yang disemak ke entri katalog yang dimaksudkan. Kekalkan semakan pengkompil dan semakan tetingkap bersama-sama: semakan pertama mengesahkan kontrak pengakses, manakala semakan kedua memastikan pembaca melihat mesej yang dimaksudkan.

Sumber