Bagi app Mac yang mempunyai panel milik framework, tentukan sandaran pada dua peringkat: bahasa yang dipilih oleh setiap bundle dan perkara yang dipulangkan oleh setiap mesej apabila carian gagal. Gunakan penyetempatan pembangunan bahasa Inggeris dan nilai lalai bahasa Inggeris yang jelas untuk mesej yang anda miliki.

Panduan ini melaksanakan kontrak tersebut untuk tetingkap desktop ringkas yang mengandungi label milik app Workspace dan label milik framework Panel ready. Label ini bersifat sintetik. Tugasnya adalah memastikan mesej tersebut kekal mudah dibaca apabila bahasa atau terjemahan tiada, sambil mengekalkan penyetempatan biasa apabila terjemahan tersedia.

Apakah yang patut dijanjikan oleh kontrak sandaran?

Gunakan kontrak ini untuk mesej milik app dan framework: gunakan penyetempatan tersedia yang dipilih melalui padanan bahasa sistem; gunakan bahasa Inggeris sebagai penyetempatan pembangunan apabila tiada bahasa pilihan yang sepadan; dan pulangkan nilai lalai bahasa Inggeris yang jelas bagi sesuatu mesej jika carian rentetannya gagal. Setiap mesej mesti mengenal pasti bundle pemiliknya dan jadual rentetannya.

Pemilihan bahasa mengambil kira bahasa pilihan pengguna dan penyetempatan yang tersedia. Jika bahasa pilihan pertama tiada, bahasa Inggeris tidak semestinya terus dipaparkan: bahasa pilihan lain mungkin sepadan terlebih dahulu. Panduan bundle arkib Apple menerangkan urutan pemilihan tersebut, diikuti penyetempatan pembangunan apabila tiada bahasa pilihan yang sepadan. Dokumentasi semasa mentakrifkan CFBundleDevelopmentRegion sebagai pengecam bahasa sandaran bundle. Mengakses Kandungan Bundle, CFBundleDevelopmentRegion.

Gunakan jadual keputusan berikut untuk menentukan hasil yang dijangka. Jadual ini memisahkan pemilihan sumber daripada carian mesej, dan tidak menganggap setiap terjemahan yang tiada sebagai keadaan yang sama.

Keadaan Kontrak untuk mesej yang anda miliki Perkara yang perlu diperiksa
Bahasa pilihan mempunyai terjemahan yang tersedia Paparkan terjemahan itu Bundle, jadual dan kunci
Bahasa pilihan pertama tiada, tetapi bahasa pilihan lain sepadan Benarkan padanan bahasa sistem memilih penyetempatan yang tersedia Susunan keutamaan dan sumber yang disertakan
Tiada penyetempatan pilihan yang sepadan Gunakan sumber pembangunan bahasa Inggeris bundle Bahasa pembangunan dan sumber bahasa Inggeris
Carian yang dipilih tidak dapat menemukan mesej Pulangkan nilai lalai bahasa Inggerisnya yang jelas defaultValue bagi mesej itu
Carian framework tersasar ke bundle app secara tidak sengaja Betulkan argumen bundle Pemilikan sumber
Terjemahan tersedia tetapi teksnya tidak sesuai Betulkan terjemahan Kandungan katalog dan semakan

Jadual ini menggabungkan peraturan pemilihan sumber Apple dengan tingkah laku nilai lalai yang didokumenkan untuk pemula Swift. Ini ialah dasar pelaksanaan yang diterbitkan daripada API tersebut, bukannya ciri sandaran berasingan dalam String Catalogs. Carian yang berjaya tetapi menghasilkan teks tidak sesuai tidak memenuhi syarat yang didokumenkan bagi pemula untuk menggunakan nilai lalainya: carian mesti gagal. String.init(localized:defaultValue:table:bundle:locale:comment:).

Konfigurasikan sumber bahasa Inggeris dalam setiap sasaran pemilik

Untuk contoh ini, gunakan pemasangan Xcode semasa, app SwiftUI macOS yang menyasarkan macOS 13 atau lebih baharu, serta sasaran framework Swift dinamik terbenam bernama PanelKit. Pautkan dan benamkan framework itu dalam app. Ini ialah prasyarat projek contoh; nama framework tersebut tidak merujuk kepada produk sedia ada.

Tetapkan bahasa Inggeris sebagai bahasa pembangunan untuk kedua-dua sasaran, dan sahkan bahawa CFBundleDevelopmentRegion bagi setiap bundle yang dibina menghasilkan en. Sediakan sumber asal bahasa Inggeris yang sepadan dalam kedua-dua sasaran. Pengecam bahasa pembangunan menerangkan bahasa sandaran; ia tidak membekalkan kandungan mesej yang tiada. Apple mendokumenkan en sebagai pengecam bahasa Inggeris. CFBundleDevelopmentRegion.

Cipta katalog Localizable.xcstrings berasingan untuk setiap sasaran. Dalam Xcode, pilih File > New > File from Template, pilih String Catalog, kemudian namakannya Localizable. Tetapkan satu katalog kepada sasaran app dan satu lagi kepada sasaran framework. Pengasingan pemilikan sumber membolehkan setiap carian disahkan secara berasingan. Apple mendokumenkan aliran kerja penciptaan katalog dan menyokong berbilang katalog. Menyetempatkan dan mempelbagaikan teks dengan katalog rentetan.

Selepas menambah kod di bawah, pilih Product > Build. Xcode mengekstrak panggilan yang boleh disetempatkan ke dalam katalog. Pastikan workspace.title muncul dalam katalog app dan panel.ready muncul dalam katalog framework, dengan nilai sumber bahasa Inggeris yang dimaksudkan. Tambahkan bahasa yang disokong menggunakan butang tambah pada bar sisi katalog, kemudian masukkan terjemahan untuk mesej yang berkaitan. Menyetempatkan dan mempelbagaikan teks dengan katalog rentetan.

Kelengkapan katalog dan ketepatan carian semasa jalanan memerlukan pemeriksaan yang berasingan. Entri terjemahan dalam katalog framework tidak membantu panggilan yang mencari dalam bundle app. Apple secara jelas mengarahkan kod yang memuatkan rentetan di luar bundle utama supaya menghantar bundle yang dikaitkan dengan sasaran itu. Menyediakan teks app anda untuk terjemahan.

Berikan setiap mesej bundle, kunci, jadual dan nilai lalai

Gunakan kunci sintetik yang stabil dan nilai lalai bahasa Inggeris yang mudah dibaca. Pemula Swift yang menerima defaultValue menyokong kunci yang berbeza daripada teks sumber yang dipaparkan. Nilai lalainya dipulangkan apabila carian rentetan setempat daripada bundle gagal. Parameter table memilih jadual rentetan; jika ditinggalkan, Localizable akan dipilih. String.init(localized:defaultValue:table:bundle:locale:comment:).

Letakkan mesej framework dalam framework

Tambahkan fail sumber Swift lengkap ini pada sasaran framework dinamik PanelKit. Kelas penanda ditakrifkan dalam sasaran itu supaya Bundle(for:) mengenal pasti bundlenya. Apple mendokumenkan pendekatan berasaskan kelas ini sebagai alternatif kepada makro #bundle semasa. Menyediakan teks app anda untuk terjemahan.

import Foundation

private final class PanelBundleAnchor: NSObject {}

public enum PanelText {
    public static var resourceBundle: Bundle {
        Bundle(for: PanelBundleAnchor.self)
    }

    public static var ready: String {
        String(
            localized: "panel.ready",
            defaultValue: "Panel ready",
            table: "Localizable",
            bundle: resourceBundle,
            comment: "Status label above the framework panel."
        )
    }
}

Framework menyelesaikan mesejnya sebelum memulangkan String kepada app. Ini menetapkan sempadan pemilikan yang jelas: framework mengawal kunci, teks sumber, jadual dan bundle sumber. App menerima teks paparan yang terhasil.

Paparkan mesej app dan framework bersama-sama

Gantikan fail titik masuk app yang dijana dengan contoh lengkap ini. Contoh ini mengandaikan modul framework yang dipautkan bernama PanelKit dan mengandungi fail sebelumnya. Kekalkan hanya satu titik masuk app dalam sasaran app.

import Foundation
import SwiftUI
import PanelKit

@main
struct FallbackDemoApp: App {
    var body: some Scene {
        WindowGroup {
            VStack(alignment: .leading, spacing: 12) {
                Text(verbatim: String(
                    localized: "workspace.title",
                    defaultValue: "Workspace",
                    table: "Localizable",
                    bundle: .main,
                    comment: "Heading for the main workspace."
                ))

                Text(verbatim: PanelText.ready)
            }
            .padding(24)
        }
    }
}

Carian app menggunakan .main secara jelas; carian framework menggunakan bundlenya sendiri. Kedua-duanya menyediakan nilai lalai bahasa Inggeris. Ini mematuhi pemilihan bundle dan parameter nilai lalai yang didokumenkan Apple. Bina dan jalankan projek dalam Xcode untuk mengesahkan konfigurasi sasaran yang lengkap; contoh ini belum dijalankan di sini. String.init(localized:defaultValue:table:bundle:locale:comment:).

Untuk pelaksanaan sedia ada yang menggunakan Bundle.localizedString(forKey:value:table:), sediakan value yang tidak kosong dan mudah dibaca apabila anda memerlukan hasil yang boleh dibaca bagi kunci yang tiada. Apple mendokumenkan bahawa kunci yang tiada akan memulangkan kunci itu sendiri apabila value tiada atau kosong, dan memulangkan value apabila nilainya tidak kosong. Oleh itu, kunci seperti panel.ready memerlukan sandaran yang jelas jika memaparkan pengecam itu melanggar kontrak mesej. localizedString(forKey:value:table:).

Tentukan sama ada framework boleh memilih bahasa yang berbeza

Menghantar bundle yang betul menentukan tempat carian dibuat. Konfigurasi penyetempatan campuran mempengaruhi kaitan pemilihan penyetempatan dengan app yang menempatkan framework tersebut. Apple menyediakan Boolean CFBundleAllowMixedLocalizations, yang dipaparkan sebagai Localized resources can be mixed, untuk mendapatkan rentetan setempat daripada framework. CFBundleAllowMixedLocalizations.

Penjelasan dalam Swift Forums tentang tingkah laku ini menyatakan bahawa mengaktifkan kunci itu dalam Info.plist app membolehkan bundle lain memilih penyetempatan di luar penyetempatan yang disokong oleh app utama. Tanpa pilihan itu, bundle utama mengehadkan pemilihannya. Ini ialah perbincangan penjelasan yang lebih lama dan berguna apabila dibaca bersama rujukan kunci Apple semasa. Penyetempatan Swift package manager.

Untuk tetingkap contoh ini, utamakan liputan bahasa yang disokong dan sepadan antara app dan framework, dengan sumber pembangunan bahasa Inggeris dalam kedua-duanya. Jangan masukkan pemilihan bahasa framework secara berasingan dalam kontrak awal. Jika tingkah laku yang anda inginkan ialah membenarkan framework menggunakan terjemahan tambahan, tetapkan Boolean CFBundleAllowMixedLocalizations app kepada YES dan uji konfigurasi itu secara khusus. Penyetempatan Swift package manager.

Mengaktifkan kunci ini tidak menyediakan terjemahan atau nilai lalai untuk mesej yang tiada. Tanggungjawab itu masih terletak pada fail sumber dan panggilan carian. Begitu juga, nilai lalai yang diberikan kepada panggilan anda menentukan hasil bagi carian panggilan itu yang gagal; ia tidak menetapkan sandaran bahasa Inggeris sejagat untuk setiap kawalan sistem atau mesej framework.

Jangan gunakan argumen locale bagi pemula String ini sebagai suis bahasa terjemahan. Apple secara jelas mendokumenkan bahawa argumen itu mengawal penyetempatan nilai interpolasi, seperti nombor, dan tidak mengubah lokal yang digunakan untuk mencari rentetan setempat. Gunakan konfigurasi bahasa dan kawalan ujian yang disokong untuk tugas ini. String.init(localized:defaultValue:table:bundle:locale:comment:).

Uji bahasa yang tiada secara berasingan daripada mesej yang tiada

Jalankan pemeriksaan penyetempatan melalui Product > Scheme > Edit Scheme. Pilih Run, buka Options, pilih App Language, tutup dialog, kemudian jalankan semula app Mac. Apple mendokumenkan aliran kerja ini untuk menguji penyetempatan tanpa mengubah tetapan seluruh sistem. Kekalkan pilihan rantau apabila menyiasat isu bahasa sahaja. Menguji penyetempatan semasa menjalankan app anda.

Gunakan matriks ujian berikut sebagai panduan diagnostik khusus projek. Untuk pemeriksaan penghalaan bundle, gunakan penanda ujian bahasa Inggeris yang berbeza buat sementara waktu seperti App translation sample dan Framework translation sample dalam penyetempatan sumber bukan bahasa Inggeris yang disokong. Ini ialah kandungan diagnostik, bukannya terjemahan atau pengecam bahasa.

  1. Sahkan tingkah laku sumber. Jalankan dengan bahasa Inggeris dipilih. Jangkakan Workspace dan Panel ready.
  2. Sahkan penghalaan sumber terjemahan. Pilih penyetempatan ujian yang disokong. Jangkakan penanda yang berbeza daripada dua katalog pemilik.
  3. Sahkan nilai lalai bagi mesej yang tiada. Dalam suntingan ujian sementara, tukar kunci carian framework kepada panel.ready.probe, biarkan defaultValue tidak berubah, dan pastikan entri cubaan itu tidak disertakan dalam katalog ujian. Jangkakan Panel ready apabila carian gagal. Pulihkan kunci asal selepas itu.
  4. Sahkan pemilihan bahasa yang tidak disokong. Uji senarai keutamaan yang tiada padanan bahasa yang disokong. Pastikan kedua-dua bundle milik anda menggunakan sumber pembangunan bahasa Inggerisnya. Uji juga keadaan apabila pilihan pertama tidak disokong tetapi diikuti pilihan yang disokong, kerana hasil yang dijangka berbeza.
  5. Sahkan penyetempatan campuran jika diaktifkan. Uji bahasa yang hanya tersedia dalam framework. Catat tingkah laku yang dimaksudkan dan uji tetapan penyetempatan campuran app berbanding tingkah laku itu.

Pemeriksaan ketiga mengasingkan carian yang gagal; pemeriksaan keempat mengasingkan padanan bahasa. Menguji baris katalog yang belum diterjemahkan sahaja boleh mengaburkan keadaan tersebut kerana konfigurasi sumber yang terhasil turut mempengaruhi carian. Hasil kunci yang tiada seperti yang dijangka berpunca daripada pemula Swift, manakala pemilihan bahasa pilihan mengikuti peraturan bundle. String.init(localized:defaultValue:table:bundle:locale:comment:), Mengakses Kandungan Bundle.

Apabila hasilnya berbeza, periksa bundle pemilik sebenar. developmentLocalization melaporkan nilai yang sepadan dengan CFBundleDevelopmentRegion; preferredLocalizations melaporkan penyetempatan yang tersedia mengikut susunan keutamaan bahasa. Bandingkan sifat ini pada Bundle.main dan PanelText.resourceBundle. Sifat ini membantu mendiagnosis konfigurasi, tetapi mesej yang dipaparkan tetap menjadi pemeriksaan akhir bagi setiap carian. developmentLocalization, preferredLocalizations.

Kontrak sandaran yang berguna menjadikan setiap hasil mudah dijelaskan: bahasa yang dipilih datang daripada padanan bundle, mesej datang daripada jadual pemiliknya, dan carian yang gagal memulangkan nilai lalai yang jelas serta mudah dibaca. Gunakan peraturan ini pada setiap mesej milik app dan framework, kemudian sahkannya bersama-sama dalam tetingkap desktop tempat pengguna melihatnya.

Sumber