Untuk menyelesaikan kunci penyetempatan framework, berikan kedua-dua himpunan sumber dan jadual rentetannya. Panduan ini menunjukkan cara memaparkan label milik framework dengan betul dalam aplikasi Mac, kemudian menyemak bahawa hasilnya datang daripada jadual dan bukannya teks sandaran.

Tugas ini sengaja ringkas: paparkan label sintetik Open panel daripada katalog Panel.xcstrings milik framework. Anda memerlukan projek aplikasi Mac dalam Xcode dan sasaran framework yang anda kawal. Contoh utama menggunakan Xcode 26 atau lebih baharu dan menyasarkan macOS 12 atau lebih baharu; Apple mendokumenkan bahawa pemula rentetan setempat tersedia mulai macOS 12. Dokumentasi pemula Swift.

Kenal pasti himpunan, jadual dan kunci sebelum mengubah kod

Anggap mesej setempat sebagai carian dengan tiga koordinat yang jelas. Himpunan mengenal pasti pemilik sumber, jadual mengenal pasti kumpulan rentetan dalam himpunan itu, dan kunci mengenal pasti entri dalam jadual tersebut. API penyetempatan Apple mendedahkan himpunan dan jadual secara berasingan kerana sasaran framework dan aplikasi masing-masing boleh mengandungi sumber rentetan. Menyediakan teks aplikasi anda untuk diterjemahkan.

Untuk contoh ini, catat kontrak berikut sebelum membuka katalog. Ini ialah nama contoh, bukannya nama yang diwajibkan oleh Apple.

Bahagian Nilai contoh Tujuan
Pemilik sumber Sasaran framework anda Mengandungi katalog
Fail katalog Panel.xcstrings Menyimpan teks sumber dan terjemahan jadual
Argumen jadual Panel Memilih katalog itu tanpa sambungannya
Kunci PANEL_OPEN_ACTION Mengenal pasti mesej
Nilai sumber bahasa Inggeris Open panel Membekalkan teks antara muka yang mudah dibaca
Komen Label for the action that opens the panel. Menerangkan penggunaan mesej

Memberikan table: "Panel" memilih jadual yang diwakili oleh Panel.xcstrings. Jika jadual tidak ditetapkan, Localizable akan dipilih. Begitu juga, jika himpunan tidak ditetapkan, pemula rentetan akan mencari dalam himpunan utama aplikasi. Oleh itu, kunci yang sepadan dalam katalog framework memerlukan himpunan framework serta jadual yang betul. Parameter rentetan setempat Swift.

Ini memberikan urutan diagnosis yang berguna: sahkan pemilik dahulu, jadual kedua dan entri ketiga. Mencari ejaan alternatif bagi kunci tidak dapat membetulkan carian yang ditujukan kepada sumber aplikasi sedangkan mesej itu milik framework.

Tambahkan katalog rentetan pada sasaran framework

Dalam Xcode, pilih File > New > File from Template, pilih platform, tapis untuk string, kemudian pilih String Catalog. Namakan fail itu Panel. Pastikan katalog itu tergolong dalam sasaran framework, bersama-sama sumber framework yang akan merujuknya. Aliran kerja katalog Apple membenarkan nama katalog tersuai, dan demonstrasi frameworknya mencipta katalog dalam sasaran framework. Menyetempatkan dan mempelbagaikan teks dengan katalog rentetan, Demonstrasi penyetempatan framework Apple.

Contoh ini menggunakan kunci semantik dan bukannya menjadikan perkataan yang dipaparkan sebagai kunci. Dengan PANEL_OPEN_ACTION sebagai pengecam dan Open panel sebagai nilai lalai, kod menyatakan kedua-dua bahagian secara jelas. Apple menyokong susunan ini melalui pemula yang menerima kunci statik dan nilai penyetempatan lalai yang berasingan. Pemula kunci statik Swift.

Selepas menambahkan sumber di bawah, bina sasaran framework. Xcode mengesan panggilan API yang boleh disetempatkan semasa binaan dan mengemas kini katalog yang berkaitan. Buka Panel.xcstrings dan sahkan bahawa ia mengandungi PANEL_OPEN_ACTION, nilai sumber bahasa Inggeris Open panel dan komen penerangan. Jika entri tiada, semak keahlian sasaran sumber dan sama ada sasaran yang mengandungi sumber itu telah dibina. Apple turut menyediakan Editor > Assistant untuk memeriksa kod yang dikaitkan dengan entri katalog. Isi dan periksa katalog rentetan.

Selesaikan mesej dalam framework

Letakkan fail sumber lengkap ini dalam sasaran framework. Fail ini mentakrifkan rentetan setempat dan label SwiftUI ringkas yang boleh dipaparkan oleh aplikasi Mac yang mengandunginya. Fail ini juga menyertakan kaedah diagnostik yang digunakan dalam bahagian seterusnya. Kod ini disemak berdasarkan tandatangan yang didokumenkan oleh Apple; kod ini tidak dijalankan di sini kerana pengkompil Swift tidak tersedia.

import Foundation
import SwiftUI

public enum PanelMessages {
    public static var openPanel: String {
        String(
            localized: "PANEL_OPEN_ACTION",
            defaultValue: "Open panel",
            table: "Panel",
            bundle: #bundle,
            comment: "Label for the action that opens the panel."
        )
    }

    public static func lookupReport() -> String {
        let missingMarker = "__PANEL_LOOKUP_MISSING__"
        let result = #bundle.localizedString(
            forKey: "PANEL_OPEN_ACTION",
            value: missingMarker,
            table: "Panel"
        )

        if result == missingMarker {
            return "No entry resolved from the selected bundle and table."
        }

        return "Resolved table value: \(result)"
    }
}

public struct PanelActionLabel: View {
    public init() {}

    public var body: some View {
        Text(verbatim: PanelMessages.openPanel)
    }
}

Ungkapan #bundle dinilai di tempat anda menulisnya. Dalam sumber framework ini, ungkapan itu membekalkan himpunan yang dikaitkan dengan sasaran framework. Jika anda memindahkan ungkapan yang sama ke sumber sasaran aplikasi, ungkapan itu akan membekalkan himpunan aplikasi. Bagi sasaran pakej Swift, Apple mendokumenkan bahawa makro itu membekalkan himpunan sumber sasaran tersebut. Letakkan carian berdekatan dengan sumber yang dimilikinya. Makro himpunan Foundation.

Pengisytiharan itu mengembalikan String biasa yang penyetempatannya telah pun diselesaikan. Paparan itu menggunakan Text(verbatim:) untuk memaparkan hasil tersebut secara jelas. Paparan awam itu hanyalah label; tambahkan pada paparan aplikasi sedia ada di tempat teks itu perlu dipaparkan.

Gunakan kelas framework apabila makro himpunan tidak tersedia

Apple turut menyokong pencarian himpunan framework melalui kelas yang ditakrifkan dalam framework itu. Bagi framework konvensional yang mengandungi sumbernya sendiri, berikut ialah penyedia mesej alternatif yang lengkap. Gunakannya sebagai ganti pengisytiharan PanelMessages yang terdahulu, dan kekalkan katalog serta keperluan sasaran yang dihuraikan di atas.

import Foundation

private final class PanelBundleAnchor: NSObject {}

public enum PanelMessages {
    public static var openPanel: String {
        String(
            localized: "PANEL_OPEN_ACTION",
            defaultValue: "Open panel",
            table: "Panel",
            bundle: Bundle(for: PanelBundleAnchor.self),
            comment: "Label for the action that opens the panel."
        )
    }
}

Kelas sauh mesti dikompil dalam framework yang sumbernya ingin anda gunakan. Apple mendokumenkan bahawa Bundle(for:) mengembalikan himpunan yang dikaitkan dengan kelas yang dibekalkan, termasuk himpunan framework jika berkenaan. Sauh yang dikompil dalam aplikasi akan mengenal pasti aplikasi itu. Bagi sumber pakej atau sumber yang diletakkan dalam himpunan berasingan, pilih himpunan sumber sebenar; lokasi kelas semata-mata tidak menentukan pemilikan sumber tersebut. Pemula berasaskan kelas untuk himpunan, Pemilihan himpunan sumber dengan makro.

Buktikan bahawa teks yang boleh dibaca datang daripada carian yang berjaya

Melihat Open panel pada skrin bukan bukti yang mencukupi bahawa carian katalog berjaya. defaultValue bagi pemula itu dikembalikan apabila carian gagal, jadi teks yang sama pada paparan boleh menandakan sama ada carian berjaya atau sandaran. Tingkah laku ini berguna untuk teks antara muka yang mudah dibaca, tetapi boleh menyembunyikan himpunan atau jadual yang salah semasa pembangunan. Tingkah laku nilai lalai Swift.

Kaedah lookupReport() dalam fail sumber pertama menangani kekaburan itu. Kaedah tersebut menjalankan carian dengan penanda sandaran tersendiri yang tidak boleh digunakan sebagai nilai katalog sebenar. Periksa nilai pulangannya daripada aplikasi yang sedang berjalan atau konteks nyahpepijat sedia ada. Jika kaedah itu melaporkan bahawa tiada entri diselesaikan, siasat sumber yang dipilih sebelum mengedit terjemahan.

Diagnosis ini berpunca terus daripada tingkah laku Bundle.localizedString(forKey:value:table:) yang didokumenkan: apabila kunci tiada dan sandaran yang dibekalkan tidak kosong, kaedah itu mengembalikan sandaran tersebut. Jika kunci tiada dan sandaran bernilai nil atau kosong, kaedah itu mengembalikan kunci. Penanda itu memudahkan kegagalan dibezakan daripada teks sumber yang sah. Nilai pulangan rentetan setempat bagi himpunan).

Pemerhatian Semakan seterusnya
Diagnosis mengembalikan mesej entri tiada Pastikan katalog dibina ke dalam himpunan yang dipilih, kemudian semak Panel dan PANEL_OPEN_ACTION
Diagnosis menyelesaikan nilai yang tidak dijangka Periksa entri tepat itu dalam jadual yang dipilih dan bahasa yang digunakan oleh sesi berjalan semasa
Diagnosis menyelesaikan nilai dengan betul tetapi antara muka berbeza Jejaki nilai yang benar-benar dipaparkan oleh antara muka
Nilai sumber bahasa Inggeris muncul semasa sesi berjalan dalam bahasa terjemahan Periksa terjemahan entri dan konfigurasi sesi berjalan; carian yang berjaya sahaja tidak membuktikan terjemahan yang diminta tersedia

Jadual ini ialah urutan penyelesaian masalah yang berpandukan kontrak carian. Ujian penanda yang berjaya mengesahkan bahawa carian mengembalikan entri, tetapi tidak mengesahkan bahawa setiap bahasa yang disokong mempunyai terjemahan yang lengkap. Semak penyelesaian sumber dan kelengkapan terjemahan secara berasingan.

Uji label dalam bahasa yang dipilih untuk aplikasi Mac

Bagi aplikasi yang menyokong bahasa tambahan, pilih bahasa yang berkaitan dalam bar sisi katalog dan masukkan terjemahan dalam medan teks entri itu. Kemudian uji melalui aplikasi Mac yang mengandunginya. Apple mendokumenkan kemasukan terjemahan secara langsung dalam editor katalog, dan status terjemahan setiap entri dikemas kini semasa anda bekerja. Tambahkan terjemahan pada katalog rentetan.

Untuk mengawal sesi nyahpepijat, pilih Product > Scheme > Edit Scheme, pilih Run dan buka Options. Tetapkan App Language kepada bahasa yang disokong oleh projek, tutup editor dan jalankan semula aplikasi Mac. Pilih System Language apabila anda mahu sesi berjalan mengikut tetapan bahasa sistem. Menguji penyetempatan semasa menjalankan aplikasi.

Jangan gunakan argumen locale: pemula rentetan sebagai ganti ujian bahasa ini. Apple mendokumenkan bahawa argumen ini mengawal penyetempatan nilai tersisip seperti nombor, dan tidak mengubah lokal yang digunakan untuk mencari rentetan setempat. Contoh ini mengabaikannya kerana label tersebut tiada nilai tersisip. Parameter lokal rentetan setempat Swift.

Pastikan kontrak akhir ringkas dan jelas: framework memiliki Panel.xcstrings, carian memilih Panel, dan PANEL_OPEN_ACTION mengenal pasti label tersebut. Sahkan entri menggunakan diagnostik, kemudian sahkan terjemahan yang dipaparkan dalam bahasa sesi berjalan yang dipilih untuk aplikasi. Urutan ini membolehkan anda membetulkan carian sumber sebelum meluangkan masa mengolah perkataan yang mungkin tidak pernah dibaca oleh aplikasi.

Sumber