Untuk menyatukan mesej berulang dalam app Mac, berikan setiap maksud yang dikongsi satu kunci penyetempatan dan satu takrifan Swift, kemudian gunakannya di mana-mana mesej itu dipaparkan. Kekalkan argumen, peraturan jamak dan konteks penterjemahnya bersama-sama; teks bahasa Inggeris yang sepadan sahaja tidak mencukupi.

Panduan ini ditujukan kepada pembangun Mac yang menyelenggara ringkasan pilihan dalam SwiftUI dan tetingkap Interface Builder. Tugas khususnya ialah memaparkan mesej seperti 2 item dipilih dalam Batch A. secara konsisten, tanpa menyelenggara templat ayat berasingan dalam XIB dan kod Swift. Semua bilangan dan label di bawah ialah contoh rekaan.

Tentukan mesej berulang yang patut disatukan

Sebelum mengedit katalog, takrifkan kontrak mesej: maksud ayat itu, nilai yang diterimanya dan tempat ia dipaparkan. Untuk contoh ini, kontraknya ialah:

Unsur kontrak Takrifan
Maksud Bilangan item yang sedang dipilih dalam koleksi bernama
Kunci selection.summary
Jadual Localizable
Bundle Bundle app utama
Argumen 1 Bilangan pilihan Int64
Argumen 2 Label koleksi literal, seperti Batch A
Variasi Bentuk jamak ditentukan oleh bilangan pilihan
Konteks Ayat status lengkap yang dipaparkan dalam SwiftUI dan label AppKit

Gunakan kontrak ini sebagai ujian penyatuan. Dua kejadian boleh berkongsi mesej apabila maksud, argumen dan peranan tatabahasanya sepadan. Bilangan item dipilih dan bilangan jumlah item patut kekal berasingan walaupun kedua-duanya pada masa ini memaparkan 2 item. Butang bernama Pilih juga memerlukan mesej tersendiri kerana ia menyatakan tindakan.

Apple menyokong kunci eksplisit dengan nilai lalai berasingan khusus untuk membezakan teks. Ini membolehkan anda menamakan mesej mengikut tujuannya sambil mengekalkan ungkapan sumber yang mudah dibaca. Komen memberikan konteks; kunci mengenal pasti entri tersebut. Pemula kunci eksplisit String.

Anggap jadual dan bundle sebagai sebahagian daripada kontrak carian juga. Kunci dalam jadual lain ialah sasaran carian yang berasingan. Apple mendokumenkan pemilihan jadual melalui parameter table atau tableName dan mengesyorkan agar teks yang boleh dilokalkan dihantar melalui LocalizedStringResource. Untuk contoh ini, kekalkan pembantu dan katalog dalam sasaran app serta gunakan bundle utama. Menyediakan teks app anda untuk terjemahan.

Fahami sempadan antara pengekstrakan dengan pemformatan semasa jalan

Pengekstrakan berlaku semasa Xcode membina app: proses ini menemui ungkapan setempat yang disokong dan menyegerakkan teks sumbernya dengan katalog. Penyetempatan semasa app berjalan berlaku apabila app menyelesaikan mesej dan menggantikan nilai sebenar. Menemui entri dalam katalog membuktikan bahawa pengekstrakan telah menemuinya; hal itu tidak membuktikan bahawa setiap kawalan memaparkannya dengan betul.

Interface Builder mempunyai aliran kerja sumbernya sendiri. Apple mendokumenkan katalog yang dipadankan dengan papan cerita atau XIB, manakala kod Swift lazimnya menyumbang kepada jadual Localizable. Aliran kerja yang didokumenkan itu tidak menerangkan alias merentas sumber yang menggabungkan mesej hanya kerana perkataan yang kelihatan sepadan. Cara praktikal yang disokong ialah menetapkan mesej terlokalisasi yang dikongsi daripada Swift selepas antara muka dimuatkan. Ini ialah pelaksanaan yang berasaskan API yang didokumenkan Apple. Ketahui tentang Katalog Rentetan.

SwiftUI juga membezakan kunci penyetempatan literal daripada nilai rentetan biasa. Contohnya, Text("Summary") meminta penyetempatan, manakala penghantaran pemboleh ubah String memaparkan nilainya tanpa carian itu. Membungkus rentetan masa jalan dalam LocalizedStringKey meminta carian, tetapi jangan samakan perkara itu dengan bukti bahawa pengekstrakan menemui nilai-nilai yang mungkin. LocalizedStringKey.

Oleh itu, reka bentuk di bawah mengekalkan literal yang boleh diekstrak dalam satu pembantu. Pembantu itu membawa bilangan dan label dalam LocalizedStringResource, kemudian menyelesaikan sumber tersebut di tempat rentetan siap diperlukan. Apple menerangkan jenis sumber ini sebagai cara untuk menangguhkan carian penyetempatan. Jenis ini tersedia pada macOS 13 dan versi lebih baharu, iaitu sasaran minimum untuk contoh ini. LocalizedStringResource.

Takrifkan mesej yang dikongsi sekali sahaja dalam Swift

Cipta projek app macOS menggunakan SwiftUI, tetapkan sasaran penggunaan kepada macOS 13 atau versi lebih baharu, dan tambahkan Localizable.xcstrings pada sasaran app. Dalam dokumentasi Xcode semasa, laluan penciptaannya ialah File > New > File from Template; cari string dan pilih String Catalog. Melokalkan dan mempelbagaikan teks dengan katalog rentetan.

Gantikan titik masuk app yang dijana dengan program lengkap di bawah. Buang titik masuk app asal supaya sasaran hanya mengandungi satu pengisytiharan @main. Tetingkap SwiftUI berjalan secara berasingan daripada XIB; subkelas AppKit yang disertakan digunakan apabila menyesuaikan label Interface Builder sedia ada dalam bahagian seterusnya.

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 statik mengenal pasti mesej; nilai lalai interpolasi membekalkan ayat sumber dan argumen masa jalan. Pemula itu juga menerima jadual, bundle dan komen penterjemah. Bundle utamanya ialah bundle utama. Pemula kunci eksplisit LocalizedStringResource.

Label Batch A ialah kandungan contoh yang disisipkan ke dalam ayat. Label itu bukan kunci mesej lain. Perbezaan ini memastikan label koleksi terpisah daripada perkataan antara muka yang mengelilinginya. Jika aplikasi sebenar anda menggunakan nama koleksi yang telah ditentukan dan diterjemahkan, lokalkan nama tersebut melalui takrifannya sendiri sebelum membekalkannya di sini.

Jangan bina ayat ini daripada cebisan yang dilokalkan secara berasingan seperti bilangan, item dipilih dalam dan label. Mengekalkan ayat lengkap dalam kontrak memberi penterjemah satu unit yang perkataan dan susunan argumennya boleh dilaraskan bersama-sama.

Halakan label Interface Builder melalui takrifan yang sama

Untuk XIB atau papan cerita sedia ada, gunakan label NSTextField statik bagi ringkasan. Tetapkan kelas tersuainya kepada SelectionSummaryField dan modulnya kepada sasaran app. Kosongkan ayat lama daripada nilai rentetan reka bentuknya, kerana label khusus ini kini menerima teks daripada takrifan Swift yang dikongsi.

Apabila antara muka dimuatkan, subkelas itu memanggil super.awakeFromNib() dan menetapkan ringkasan awal rekaan. Apple mendokumenkan awakeFromNib() sebagai cangkuk selepas pemuatan, apabila sambungan outlet dan tindakan telah diwujudkan, serta menghendaki pelaksanaan kelas induk dipanggil. awakeFromNib().

Dalam tetingkap sebenar, panggil updateSelection(count:collectionLabel:) pada label yang disambungkan setiap kali pilihan berubah, menggunakan nilai model yang sama seperti yang dibekalkan kepada SwiftUI. Gantikan tetapan awal rekaan dengan laluan pemulaan sebenar tetingkap. Tetapan sekali sahaja semasa pemuatan tidak dapat menjejaki perubahan pilihan yang berlaku kemudian.

Penyesuai AppKit menetapkan stringValue, iaitu cara yang didokumenkan untuk menetapkan teks NSTextField. Ini mengekalkan susun atur dalam Interface Builder sambil memindahkan pemilikan mesej kepada Swift. Sediakan lebar yang mencukupi atau pembalutan teks untuk ayat lengkap. NSTextField.

Kekalkan teks antara muka statik yang tidak berkaitan dalam aliran kerja sumber sedia ada. Penghijrahan ini melibatkan satu mesej yang dikongsi; memindahkan setiap label ke dalam Swift tidak perlu. Pastikan juga bahawa ikatan atau penetapan oleh pengawal lain tidak menggantikan ringkasan itu kemudian dengan perkataan lama.

Konfigurasikan variasi jamak tanpa mengubah argumen

Pilih Product > Build, buka Localizable.xcstrings, dan cari selection.summary. Klik kawalan pada entri itu, pilih Vary by Plural, dan pilih argumen bilangan jika Xcode bertanya argumen mana yang hendak divariasikan. Apple mendokumenkan aliran kerja ini untuk mesej terinterpolasi. Melokalkan dan mempelbagaikan teks dengan katalog rentetan.

Untuk penyetempatan sumber bahasa Inggeris, pastikan variasi tunggal menghasilkan 1 item dipilih dalam Batch A. dan variasi yang lain menghasilkan ayat seperti 2 item dipilih dalam Batch A. Kekalkan kedua-dua pemegang tempat argumen yang dibekalkan oleh Xcode. Edit perkataan di sekelilingnya dan bukannya menggantikan pemegang tempat dengan bilangan atau label contoh.

Input rekaan Hasil bahasa Inggeris yang dijangka selepas konfigurasi jamak
Bilangan 0, label Batch A 0 item dipilih dalam Batch A.
Bilangan 1, label Batch A 1 item dipilih dalam Batch A.
Bilangan 2, label Batch A 2 item dipilih dalam Batch A.
Bilangan 2, label Batch B 2 item dipilih dalam Batch B.

Ini ialah kes penerimaan ilustrasi, bukannya hasil yang diukur. Sebelum konfigurasi jamak, ayat sumber lalai masih mengandungi items untuk setiap bilangan. Pengekstrakan mengekalkan mesej terinterpolasi itu; proses tersebut tidak membetulkan tatabahasanya secara automatik.

Label yang berubah dalam baris terakhir berguna untuk diagnosis: jika paparan kekal Batch A, nilai contoh mungkin telah ditetapkan secara keras dalam variasi atau pemanggil mungkin membekalkan keadaan lama. Jika label itu hilang, periksa pemegang tempat variasi sebelum mengubah tandatangan pembantu.

Sahkan setiap laluan paparan sebelum membuang entri lama

Uji tetingkap SwiftUI dan tetingkap Interface Builder sebenar secara berasingan. Gunakan bilangan dan label yang sama dalam kedua-duanya. Periksa pemuatan awal, perubahan pilihan yang berlaku kemudian dan label contoh yang lebih panjang seperti Batch A Extended. Pastikan perkataannya sepadan dan ayatnya kekal mudah dibaca.

Untuk setiap penyetempatan yang disokong, pilih Product > Scheme > Edit Scheme, pilih Run, buka Options, dan tetapkan App Language. Jalankan app sekali lagi dan periksa kedua-dua laluan paparan. Apple mendokumenkan tetapan skema ini untuk menguji penyetempatan tanpa mengubah bahasa seluruh sistem. Menguji penyetempatan semasa menjalankan app anda.

Gunakan urutan berikut apabila hasilnya salah:

  1. Entri tiada: Pastikan katalog tergolong dalam sasaran app dan bina skema yang berkaitan. Periksa bahawa Use Compiler to Extract Swift Strings diaktifkan.
  2. Perkataan sumber muncul tanpa diduga: Periksa kunci, jadual, bundle dan terjemahan sebelum menganggap teks sandaran yang mudah dibaca sebagai tanda berjaya.
  3. Hanya label Interface Builder yang berbeza: Periksa kelas tersuai, modul, laluan pemuatan dan penetapan seterusnya.
  4. Hanya nilai yang berubah kemudian berbeza: Pastikan kedua-dua antara muka menerima nilai model yang dikemas kini.
  5. Perkataan jamak salah: Periksa argumen angka yang dipilih untuk variasi dan setiap variasi yang berkenaan.

Apple mendokumenkan tetapan pengekstrakan pengkompil dan menjelaskan bahawa entri terjemahan yang tidak lagi ditemui dalam sumber mungkin kekal ditandai sebagai Stale. Keadaan itu ialah isyarat untuk pembersihan, bukannya bukti bahawa sumber tidak digunakan. Semak penetapan antara muka lama dan pemanggil Swift sebelum memadam entri serta terjemahannya. Ketahui tentang Katalog Rentetan.

Penyatuan selesai apabila kedua-dua antara muka mendapatkan mesej kontekstual yang sama daripada satu takrifan, argumennya kekal utuh dan tiada lagi pemanggil bagi templat ayat lama. Simpan kontrak dan kes penerimaan bersebelahan dengan pembantu supaya perubahan perkataan pada masa hadapan mengekalkan maksud yang dikongsi oleh kedua-dua tetingkap.

Sumber