Untuk label macOS yang dapat digunakan kembali, terima pesan yang dapat dilokalkan sebagai LocalizedStringResource, pertahankan jalur verbatim: terpisah untuk teks literal, dan pertahankan interpolasi hingga lokalisasi. Tutorial ini membangun kontrak tersebut untuk penghitung item desktop dan memeriksa ekstraksi secara terpisah dari tampilan.

Apa yang harus dijanjikan oleh API teks yang dapat digunakan kembali?

Misalkan sebuah aplikasi Mac memerlukan ringkasan ringkas yang menampilkan jumlah item dan label koleksi sintetis seperti Sample Set. Komponen yang dapat digunakan kembali harus membedakan tiga masukan: pesan yang ditulis oleh aplikasi yang memerlukan terjemahan, kunci lokalisasi SwiftUI yang sudah ada, dan teks yang harus muncul persis seperti yang disediakan.

Apple merekomendasikan LocalizedStringResource untuk merepresentasikan dan meneruskan string yang dapat dilokalkan melalui tampilan kustom dan kode Swift lainnya. Panduan saat ini mendemonstrasikan properti tampilan kustom bertipe tersebut yang ditampilkan dengan Text. Gunakan itu sebagai kontrak pesan utama saat mendesain komponen baru. Menyiapkan teks aplikasi Anda untuk terjemahan.

Tabel keputusan berikut adalah desain API yang diturunkan dari perilaku yang terdokumentasikan tersebut. Label argumen yang eksplisit membuat niat pemanggil dapat ditinjau tanpa mengandalkan dua overload string yang bersaing dan tidak berlabel.

Niat Pemanggil Titik Masuk yang Diusulkan Jalur Rendering
Teruskan pesan yang dapat diterjemahkan dengan konteks opsional SummaryLabel(localized:) Text(resource)
Teruskan kunci SwiftUI, termasuk interpolasi SwiftUI SummaryLabel(key:) Text(key, tableName:bundle:)
Tampilkan label pasti SummaryLabel(verbatim:) Text(verbatim:)
Sediakan teks yang sudah disusun oleh pemanggil SummaryLabel(text:) Simpan Text yang disediakan

Pertahankan LocalizedStringKey tersedia ketika komponen secara spesifik memerlukan perilaku berbasis kunci SwiftUI. Apple mendokumentasikan bahwa literal string yang diteruskan langsung ke Text membuat kunci lokalisasi, sedangkan variabel String biasanya mengambil jalur yang melewati lokalisasi. Sebuah wrapper yang hanya menerima String oleh karena itu mengubah arti panggilan yang paripurna serupa. LocalizedStringKey.

Bangun komponen lengkap dengan titik masuk eksplisit

Gunakan proyek aplikasi SwiftUI macOS di Xcode 26 atau lebih baru, dengan target penyebaran disetel ke macOS 26 untuk contoh ini. Ganti deklarasi aplikasi dan tampilan-konten yang dihasilkan dengan program lengkap di bawah ini; pertahankan hanya satu deklarasi @main di target. Semua label dan hitungan bersifat sintetis. Kode telah diperiksa terhadap API yang terdokumentasikan, tetapi tidak dikompilasi di sini karena lingkungan ini tidak memiliki kompiler Swift.

import Foundation
import SwiftUI

struct SummaryLabel: View {
    private let text: Text

    init(localized resource: LocalizedStringResource) {
        text = Text(resource)
    }

    init(
        key: LocalizedStringKey,
        tableName: String? = nil,
        bundle: Bundle? = nil,
        comment: StaticString? = nil
    ) {
        text = Text(
            key,
            tableName: tableName,
            bundle: bundle,
            comment: comment
        )
    }

    init(verbatim value: String) {
        text = Text(verbatim: value)
    }

    init(text: Text) {
        self.text = text
    }

    var body: some View {
        text
            .font(.callout)
            .padding(8)
    }
}

struct ContentView: View {
    @State private var itemCount = 2
    private let collectionLabel = "Sample Set"

    var body: some View {
        VStack(alignment: .leading, spacing: 12) {
            Stepper(value: $itemCount, in: 0...12) {
                Text("Item count")
            }

            SummaryLabel(
                localized: LocalizedStringResource(
                    "summary.item-count",
                    defaultValue: "\(itemCount) items",
                    comment: "Summary below the item-count control. The integer is the number of items."
                )
            )

            SummaryLabel(
                key: "Collection: \(collectionLabel)"
            )

            SummaryLabel(verbatim: collectionLabel)

            SummaryLabel(
                text: Text(
                    "Preview",
                    comment: "Heading for a preview of the current item selection."
                ).bold()
            )
        }
        .padding(20)
        .frame(minWidth: 320)
    }
}

@main
struct TextContractDemoApp: App {
    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
}

Inisialisasi resource sengaja memisahkan kunci stabil summary.item-count dari pesan default-nya, \(itemCount) items. Apple mendokumentasikan kunci statis, nilai default yang dapat dilokalkan, tabel, locale, bundle, dan komentar penerjemah untuk inisialisasi ini. Nilai default-nya digunakan ketika kunci tidak ada di tabel yang ditentukan. Inisialisasi LocalizedStringResource.

Inisialisasi verbatim: menjanjikan janji yang sama jelasnya: tampilkan string yang disediakan tanpa lokalisasi. Ini berfungsi untuk argumen literal maupun variabel. Gunakan jalur ini untuk label koleksi sintetis ketika ejaan pastinya adalah konten yang akan ditampilkan. Text.init(verbatim:).

Titik masuk text: memungkinkan pemanggil membangun teks yang dilokalkan atau diberi gaya sebelum menyerahkannya. Komponen ini menambahkan tipografi dan spasi bersama; pemanggil tetap memilih semantik pesan. Meneruskan Text adalah jalan keluar, sehingga komponen yang harus memberlakukan kontrak yang lebih sempit dapat menghilangkan inisialisasi tersebut.

Bagaimana perbedaan ekstraksi dan pemformatan runtime?

Anggap lokalisasi sebagai dua pemeriksaan terpisah. Saat build, Xcode menemukan ekspresi sumber yang dapat dilokalkan dan memperbarui Katalog String. Saat eksekusi, aplikasi menyelesaikan pesan dan menggantikan argumennya. Sesi Katalog String Apple secara eksplisit mendeskripsikan pengenalan literal yang digunakan untuk menginisialisasi LocalizedStringResource di situs pemanggilan tampilan-kustom. Ia juga mengidentifikasi pengaturan build Use Compiler to Extract Swift Strings. Temukan Katalog String.

Interpolasi harus mencapai tipe yang sadar-lokalisasi sebelum menjadi string lengkap biasa. Apple menjelaskan bahwa pembangun interpolasi SwiftUI menjaga kunci format dan nilai argumen terpisah, memungkinkan lokalisasi sebelum substitusi. Mengonversi String yang sudah diinterpolasi menjadi kunci tidak dapat merekonstruksi argumen bertipe asli tersebut. Apa yang Baru di Swift.

Fragmen diagnostik ini menunjukkan perbedaan; ini bukan aplikasi kedua. Semua nilai yang digunakan dalam fragmen didefinisikan secara lokal.

import SwiftUI

let count = 2

// Ordinary String interpolation has already produced "2 items".
let completed: String = "\(count) items"
let exactDisplay = Text(completed)

// Looks up the completed value as a key.
// This does not restore a count placeholder.
let completedValueLookup = Text(LocalizedStringKey(completed))

// Preserves localization-aware interpolation from the beginning.
let messageKey: LocalizedStringKey = "\(count) items"
let interpolatedDisplay = Text(messageKey)

Membuat LocalizedStringKey dari variabel adalah cara yang terdokumentasi untuk meminta pencarian runtime. Ini berguna ketika variabel sengaja berisi kunci yang diketahui. Ini tidak membuktikan bahwa Xcode mengekstrak setiap nilai mungkin dari variavel tersebut ke dalam katalog. Pertahankan kunci dinamis yang sengaja secara eksplisit, atau gunakan deklarasi resource literal untuk pesan terbatas yang dimiliki aplikasi Anda. Perilaku pencarian dan fallback terdokumentasi di Text.init(_:tableName:bundle:comment:).

Pertahankan seluruh pesan, termasuk tanda baca dan posisi placeholder, dalam satu ekspresi yang dapat dilokalkan. Untuk contoh ini, pertahankan Collection: \(collectionLabel) bersama. Membangun pesan lengkap dari fragmen yang diselesaikan secara terpisah akan membuat pemanggil bertanggung jawab atas urutan dan spasi mereka.

Tambahkan katalog dan konfigurasikan perilaku jamak

Pertama, tambahkan Katalog String melalui File > New > File from Template, pilih String Catalog, dan beri nama Localizable. Lalu pilih Product > Build. Apple mendokumentasikan bahwa build mengisi katalog dari API yang dapat dilokalkan dan memperbaruinya saat pesan sumber berubah. Melokalkan dan memvariasikan teks dengan katalog string.

Untuk contoh, periksa entri summary.item-count dan integer terinterpolasinya. Control-klik entri dan pilih Vary by Plural. Di lokalisasi sumber Bahasa Inggris, setel One ke %lld item dan Other ke %lld items, mempertahankan placeholder integer yang disediakan Xcode. Tambahkan formulir yang diperlukan saat menambahkan lokalisasi lain; kategori jamak bergantung pada bahasa. Melokalkan dan memvariasikan teks dengan katalog string.

Interpolasi menyediakan hitungan, tetapi itu sendiri tidak menulis kata tunggal. Code-along Apple mendemonstrasikan penambahan varian jamak di katalog dan sistem memilih varian yang cocok pada runtime. Inilah mengapa build yang berhasil dan pesan yang diekstrak hanyalah bagian dari verifikasi. Code-along: Jelajahi lokalisasi dengan Xcode.

Gunakan matriks penerimaan kecil ini setelah mengonfigurasi bentuk jamak sumber. Ini adalah hasil yang diharapkan untuk program ilustratif, bukan hasil eksekusi yang dilaporkan.

Pemeriksaan Hasil yang Diharapkan
Build dan periksa summary.item-count Satu entri pesan dengan substitusi integer
Setel hitungan ke 0 0 items
Setel hitungan ke 1 1 item
Setel hitungan ke 2 2 items
Periksa baris label pasti Sample Set tetap literal
Periksa pesan koleksi Label adalah argumen di dalam pesan lengkap

Diagnosis entri yang hilang secara terpisah dari tampilan yang salah

Jika pesan hilang dari katalog, periksa tipe sumbernya terlebih dahulu. Parameter String mungkin telah menghapus ekspresi yang dapat dilokalkan sebelum mencapai komponen. Periksa target katalog, build skema yang berisi situs pemanggilan tersebut, dan verifikasi Use Compiler to Extract Swift Strings. Apple mendeskripsikan ekstraksi beroperasi pada skema dan platform saat ini, jadi periksa konfigurasi yang benar-benar mengompilasi pesan. Temukan Katalog String.

Jika entri ada tetapi aplikasi menampilkan kunci atau teks fallback, periksa konfigurasi pencarian. Inisialisasi Text berbasis kunci mencari tabel dan bundle yang ditentukan; nilai yang dihilangkan memilih tabel default dan bundle utama. Kunci atau tabel yang tidak ada menghasilkan representasi string kunci. Fallback yang readable oleh karena itu dapat menyembunyikan pencarian yang tidak lengkap. Text.init(_:tableName:bundle:comment:).

Saat memindahkan komponen ke dalam framework atau paket, tentukan di mana pesan-pesan tersebut berada. Pesan yang dimiliki komponen memerlukan resource bundle komponen; resource yang dimiliki pemanggil harus mempertahankan informasi pencarian yang mereka sediakan. Panduan Apple saat ini mendukung penerusan #bundle ke API lokalisasi untuk mengidentifikasi bundle target yang berisi. Tabel bernama juga memerlukan katalog yang cocok. Menyiapkan teks aplikasi Anda untuk terjemahan.

Akhirnya, jangan asumsikan setiap interpolasi yang diterima SwiftUI juga berada di resource Foundation. LocalizedStringKey memiliki metode interpolasi sendiri, termasuk varian format-style dan formatter. Pilih tipe pesan sebelum menyusun ekspresi, dan konsultasikan operasi interpolasi yang didukungnya ketika argumen gagal dikompilasi. LocalizedStringKey.StringInterpolation.

Komponen teks yang dapat digunakan kembali siap ketika pemanggil dapat mengekspresikan niat mereka dengan jelas dan memverifikasinya pada kedua tahap: build menghasilkan pesan katalog yang diinginkan, dan aplikasi Mac yang berjalan menampilkan substitusi, bentuk jamak, atau label pasti yang benar. Pertahankan pemeriksaan tersebut di samping kontrak API setiap kali komponen berubah.

Sumber