Untuk label macOS yang boleh guna semula, terima mesej yang boleh dilokalkan sebagai LocalizedStringResource, sediakan laluan verbatim: yang berasingan untuk teks literal, dan kekalkan interpolasi sehingga proses pelokalan. Tutorial ini membina kontrak tersebut untuk pembilang item desktop dan menyemak pengekstrakan secara berasingan daripada paparan.

Apakah yang patut dijanjikan oleh API teks boleh guna semula?

Andaikan aplikasi Mac memerlukan ringkasan padat yang memaparkan bilangan item dan label koleksi sintetik seperti Sample Set. Komponen boleh guna semula itu mesti membezakan tiga input: mesej yang ditulis oleh aplikasi dan perlu diterjemahkan, kunci pelokalan SwiftUI sedia ada, dan teks yang mesti dipaparkan tepat seperti yang diberikan.

Apple mengesyorkan LocalizedStringResource untuk mewakili dan menghantar rentetan boleh dilokalkan melalui paparan tersuai dan kod Swift yang lain. Panduan semasanya menunjukkan sifat paparan tersuai yang menggunakan jenis tersebut dipaparkan dengan Text. Gunakannya sebagai kontrak mesej utama apabila mereka bentuk komponen baharu. Menyediakan teks aplikasi anda untuk terjemahan.

Jadual keputusan berikut ialah reka bentuk API yang berasaskan tingkah laku yang didokumenkan itu. Label argumen yang jelas menjadikan niat pemanggil mudah disemak tanpa bergantung pada dua overload rentetan tanpa label yang saling bersaing.

Niat pemanggil Titik masuk yang dicadangkan Laluan pemaparan
Hantar mesej yang boleh diterjemahkan dengan konteks pilihan SummaryLabel(localized:) Text(resource)
Hantar kunci SwiftUI, termasuk interpolasi SwiftUI SummaryLabel(key:) Text(key, tableName:bundle:)
Paparkan label yang tepat SummaryLabel(verbatim:) Text(verbatim:)
Berikan teks yang telah digabungkan oleh pemanggil SummaryLabel(text:) Simpan Text yang diberikan

Kekalkan LocalizedStringKey apabila komponen memang memerlukan tingkah laku berasaskan kunci SwiftUI. Apple mendokumenkan bahawa literal rentetan yang dihantar terus kepada Text menghasilkan kunci pelokalan, manakala pemboleh ubah String biasanya menggunakan laluan yang memintas pelokalan. Oleh itu, pembungkus yang hanya menerima String mengubah makna panggilan yang kelihatan serupa. LocalizedStringKey.

Bina komponen lengkap dengan titik masuk yang jelas

Gunakan projek aplikasi macOS SwiftUI dalam Xcode 26 atau lebih baharu, dengan sasaran penggunaan ditetapkan kepada macOS 26 untuk contoh ini. Gantikan pengisytiharan aplikasi dan paparan kandungan yang dijana dengan program lengkap di bawah; kekalkan hanya satu pengisytiharan @main dalam sasaran. Semua label dan bilangan adalah sintetik. Kod ini disemak berdasarkan API yang didokumenkan, tetapi tidak dikompil di sini kerana persekitaran ini tidak mempunyai pengkompil 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()
        }
    }
}

Pemula sumber itu sengaja memisahkan kunci stabil summary.item-count daripada mesej lalainya, \(itemCount) items. Apple mendokumenkan kunci statik, nilai lalai yang boleh dilokalkan, jadual, locale, bundle dan komen untuk penterjemah bagi pemula ini. Nilai lalainya digunakan apabila kunci tiada daripada jadual yang ditentukan. Pemula LocalizedStringResource.

Pemula verbatim: menetapkan janji yang sama jelasnya: paparkan rentetan yang diberikan tanpa pelokalan. Ia berfungsi untuk argumen literal dan juga pemboleh ubah. Gunakan laluan ini untuk label koleksi sintetik apabila ejaan tepatnya ialah kandungan yang hendak dipaparkan. Text.init(verbatim:).

Titik masuk text: membolehkan pemanggil membina teks yang dilokalkan atau digayakan sebelum menyerahkannya. Komponen ini menambah tipografi dan jarak yang dikongsi; pemanggil tetap memilih semantik mesej. Menghantar Text ialah jalan keluar, jadi komponen yang perlu menguatkuasakan kontrak yang lebih terhad boleh menggugurkan pemula itu.

Apakah perbezaan antara pengekstrakan dengan pemformatan semasa jalanan?

Anggap pelokalan sebagai dua semakan berasingan. Semasa binaan, Xcode menemukan ungkapan sumber yang boleh dilokalkan dan mengemas kini String Catalog. Semasa pelaksanaan, aplikasi menyelesaikan mesej dan menggantikan argumennya. Sesi String Catalog Apple menerangkan secara jelas pengecaman literal yang digunakan untuk memulakan LocalizedStringResource pada tapak panggilan paparan tersuai. Sesi itu juga mengenal pasti tetapan binaan Use Compiler to Extract Swift Strings. Temukan String Catalog.

Interpolasi mesti sampai kepada jenis yang peka terhadap pelokalan sebelum menjadi rentetan biasa yang telah lengkap. Apple menjelaskan bahawa pembina interpolasi SwiftUI mengekalkan kunci format dan nilai argumen secara berasingan, lalu membolehkan pelokalan berlaku sebelum penggantian. Menukar String yang telah diinterpolasi menjadi kunci tidak dapat membina semula argumen bertip asal tersebut. Perkara Baharu dalam Swift.

Fragmen diagnostik ini menunjukkan perbezaannya; ini bukan aplikasi kedua. Semua nilai yang digunakan dalam fragmen ini ditakrifkan secara setempat.

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)

Mencipta LocalizedStringKey daripada pemboleh ubah ialah cara yang didokumenkan untuk meminta carian semasa jalanan. Ia berguna apabila pemboleh ubah itu memang mengandungi kunci yang diketahui. Namun, ini tidak memastikan Xcode mengekstrak setiap nilai yang mungkin bagi pemboleh ubah tersebut ke dalam katalog. Urus kunci dinamik yang disengajakan secara jelas, atau gunakan pengisytiharan sumber literal untuk mesej terhad yang dimiliki oleh aplikasi anda. Tingkah laku carian dan sandaran didokumenkan dalam Text.init(_:tableName:bundle:comment:).

Kekalkan keseluruhan mesej, termasuk tanda baca dan kedudukan pemegang tempatnya, dalam satu ungkapan yang boleh dilokalkan. Untuk contoh ini, kekalkan Collection: \(collectionLabel) secara utuh. Membina mesej lengkap daripada cebisan yang diselesaikan secara berasingan akan menyebabkan pemanggil bertanggungjawab menentukan susunan dan jarak antaranya.

Tambahkan katalog dan konfigurasikan tingkah laku jamak

Mula-mula, tambahkan String Catalog melalui File > New > File from Template, pilih String Catalog, dan namakannya Localizable. Kemudian pilih Product > Build. Apple mendokumenkan bahawa binaan mengisi katalog daripada API boleh dilokalkan dan mengemas kininya apabila mesej sumber berubah. Melokalkan dan mempelbagaikan teks dengan katalog rentetan.

Untuk sampel ini, periksa entri summary.item-count dan integer yang diinterpolasi. Klik kanan entri itu sambil menekan Control dan pilih Vary by Plural. Dalam pelokalan sumber bahasa Inggeris, tetapkan One kepada %lld item dan Other kepada %lld items, sambil mengekalkan pemegang tempat integer yang disediakan oleh Xcode. Tambahkan bentuk yang diperlukan apabila menambah pelokalan lain; kategori jamak bergantung pada bahasa. Melokalkan dan mempelbagaikan teks dengan katalog rentetan.

Interpolasi membekalkan bilangan, tetapi dengan sendirinya tidak menghasilkan perkataan tunggal. Panduan kod berperingkat Apple menunjukkan penambahan varian jamak dalam katalog dan cara sistem memilih varian yang sepadan semasa jalanan. Sebab itulah binaan yang berjaya dan mesej yang diekstrak hanyalah sebahagian daripada pengesahan. Panduan kod: Terokai pelokalan dengan Xcode.

Gunakan matriks penerimaan ringkas ini selepas mengkonfigurasikan bentuk jamak sumber. Ini ialah hasil yang dijangka untuk program ilustrasi tersebut, bukan hasil pelaksanaan yang dilaporkan.

Semakan Hasil yang dijangka
Bina dan periksa summary.item-count Satu entri mesej dengan penggantian integer
Tetapkan bilangan kepada 0 0 items
Tetapkan bilangan kepada 1 1 item
Tetapkan bilangan kepada 2 2 items
Periksa baris label tepat Sample Set kekal sebagai literal
Periksa mesej koleksi Label ialah argumen dalam mesej lengkap

Diagnosis entri yang hilang secara berasingan daripada paparan yang salah

Jika mesej tiada daripada katalog, periksa jenis sumbernya dahulu. Parameter String mungkin telah memadamkan ungkapan boleh dilokalkan sebelum ungkapan itu sampai kepada komponen. Semak sasaran katalog, bina skema yang mengandungi tapak panggilan itu, dan sahkan tetapan Use Compiler to Extract Swift Strings. Apple menerangkan bahawa pengekstrakan beroperasi pada skema dan platform semasa, jadi periksa konfigurasi yang benar-benar mengkompil mesej tersebut. Temukan String Catalog.

Jika entri wujud tetapi aplikasi memaparkan kunci atau teks sandaran, periksa konfigurasi carian. Pemula Text berasaskan kunci mencari dalam jadual dan bundle yang ditentukan; nilai yang digugurkan memilih jadual lalai dan bundle utama. Kunci atau jadual yang tiada akan menghasilkan perwakilan rentetan bagi kunci itu. Sandaran yang boleh dibaca boleh menyembunyikan carian yang tidak lengkap. Text.init(_:tableName:bundle:comment:).

Apabila memindahkan komponen ke dalam rangka kerja atau pakej, tentukan lokasi mesej. Mesej milik komponen memerlukan bundle sumber komponen itu; sumber milik pemanggil harus mengekalkan maklumat carian yang diberikan. Panduan semasa Apple menyokong penghantaran #bundle kepada API pelokalan untuk mengenal pasti bundle sasaran yang mengandungi kod tersebut. Jadual bernama juga memerlukan katalog yang sepadan. Menyediakan teks aplikasi anda untuk terjemahan.

Akhir sekali, jangan anggap setiap interpolasi yang diterima oleh SwiftUI juga sesuai digunakan dalam sumber Foundation. LocalizedStringKey mempunyai kaedah interpolasinya sendiri, termasuk varian berasaskan format dan pemformat. Pilih jenis mesej sebelum membina ungkapan, dan rujuk operasi interpolasi yang disokongnya apabila argumen gagal dikompil. LocalizedStringKey.StringInterpolation.

Komponen teks boleh guna semula sedia apabila pemanggil boleh menyatakan niat mereka dengan jelas dan mengesahkannya pada kedua-dua peringkat: binaan menghasilkan mesej katalog yang dimaksudkan, dan aplikasi Mac yang sedang berjalan memaparkan penggantian, bentuk jamak atau label tepat yang betul. Kekalkan semakan tersebut bersama kontrak API setiap kali komponen berubah.

Sumber