Untuk menamakan semula kunci Katalog Rentetan dalam Xcode, simpan mesej sumber secara berasingan, kemas kini rujukan kodnya dan sahkan setiap terjemahan serta varian sedia ada. Untuk rentetan yang diekstrak, Xcode 26 menawarkan pemfaktoran semula penukaran; menukar kunci carian sahaja tidak mencukupi.

Panduan ini ditujukan kepada sesiapa yang menyelenggara app Mac SwiftUI dengan katalog .xcstrings sedia ada. Tugasnya ialah menggantikan kunci berbentuk mesej dengan pengecam yang bermakna sambil mengekalkan perkataan yang dipaparkan dan terjemahannya. Apple mendokumenkan API dan aliran kerja penukaran di bawah, tetapi tidak menjamin bahawa suntingan kunci sewenang-wenangnya akan memindahkan setiap terjemahan secara automatik.

Apakah yang mesti kekal apabila kunci ditukar?

Mesej yang boleh disetempatkan mempunyai lebih daripada sekadar pengecam. Apple menerangkan kunci, nilai lalai, komen dan jadualnya sebagai komponen yang berasingan. Kunci mengenal pasti mesej semasa masa jalan; nilai lalai membekalkan perkataan sumber. Katalog menyimpan terjemahan dan metadata sesuatu jadual. Anggap penamaan semula sebagai perubahan terselaras pada kontrak mesej itu. Temui Katalog Rentetan

Sebelum menyunting, catatkan perkara berikut bagi setiap entri yang terjejas. Contoh rekaan ini menggambarkan penamaan semula; ia bukan hasil pengukuran.

Komponen Sebelum Hasil yang dimaksudkan
Kunci carian Open collection collection.open
Mesej sumber Open collection Tidak berubah
Jadual Localizable Tidak berubah
Bundle Bundle app utama Tidak berubah
Konteks penterjemah Butang yang membuka koleksi terpilih Dikekalkan
Terjemahan sedia ada Nilai semasa dalam setiap penyetempatan Dikekalkan
Argumen kiraan, jika ada Kiraan integer Jenis dan makna yang sama
Varian jamak atau peranti Cabang sedia ada Dikekalkan

Gunakan rekod ini sebagai bantuan perbandingan. Binaan yang berjaya sahaja tidak dapat memastikan terjemahan kekal: app mungkin masih memaparkan mesej lalai apabila carian tidak menemui padanan. SwiftUI mendokumenkan bahawa kunci setempat boleh dipaparkan secara langsung apabila tiada padanan dalam katalog. Dengan kunci semantik, ini boleh menyebabkan pengecam seperti collection.open muncul dalam antara muka. Menyediakan paparan untuk penyetempatan

Cari sumber sebelum menyunting katalog

Buka katalog sedia ada dalam Project navigator Xcode. Pilih Editor > Assistant, kemudian pilih entri untuk memeriksa sumbernya. Apple turut mendokumenkan anak panah di sebelah kunci dan contoh penggunaan dalam Attributes inspector sebagai cara mencari rujukan. Bagi rentetan yang diekstrak, pilih Product > Build selepas perubahan sumber untuk menyegerakkan katalog. Menyetempatkan dan mempelbagaikan teks dengan katalog rentetan

Periksa sama ada entri itu diekstrak daripada kod atau diurus secara manual. Apple menjelaskan bahawa kod sumber mengawal mesej yang diekstrak: binaan menyegerakkan nilai sumbernya. Entri terjemahan yang tidak lagi diekstrak akan kekal sebagai Stale; entri yang belum diterjemahkan boleh dialih keluar. Entri yang diurus secara manual tidak dikemas kini atau dialih keluar melalui pengekstrakan. Oleh itu, jangan padam entri lama yang telah diterjemahkan hanya kerana entri pengganti sudah muncul. Temui Katalog Rentetan

Cipta titik semakan yang boleh dipulihkan sebelum meneruskan, kemudian bandingkan entri yang terjejas dengannya. Kekalkan jadual dan bundle tanpa perubahan sepanjang tugas ini supaya punca terjemahan yang hilang lebih mudah dikenal pasti. API penyetempatan Apple menerima maklumat jadual dan bundle kerana kedua-duanya menentukan tempat mesej ditemui. Menyediakan teks app anda untuk terjemahan

Gunakan pemfaktoran semula penukaran Xcode untuk rentetan yang diekstrak

Bagi projek yang menggunakan Xcode 26 atau lebih baharu, pertimbangkan untuk menukar entri sedia ada yang diekstrak kepada simbol setempat yang dijana. Apple memperkenalkan aliran kerja ini dalam Xcode 26 dan menunjukkan cara menukar kunci kepada nama semantik semasa penukaran. Ini ialah kaedah yang didokumenkan untuk mengubah cara mesej dikenal pasti dan dirujuk secara serentak. Panduan langkah demi langkah: Terokai penyetempatan dengan Xcode

  1. Dalam tetapan binaan, pastikan Generate String Catalog Symbols ditetapkan kepada Yes jika projek sedia ada perlu mengaktifkannya.
  2. Dalam editor katalog, pilih kunci sedia ada, klik sambil menekan Control padanya, kemudian pilih Refactor > Convert Strings to Symbols.
  3. Periksa pratonton yang menunjukkan perubahan kunci katalog dan lokasi sumber yang terjejas.
  4. Edit nama semantik yang dicadangkan dan, jika berkenaan, nama argumen dalam antara muka penukaran.
  5. Bandingkan kod semasa dengan kod yang diubah suai menggunakan pratonton yang diserlahkan, kemudian klik Convert.
  6. Bina projek dan bandingkan entri yang terhasil dengan titik semakan anda, termasuk terjemahan dan varian.

Apple mendokumenkan kawalan penukaran ini dan menunjukkan contoh penggunaan yang dijana dalam Attributes inspector. Gunakan contoh tersebut dan bukannya meneka pengecam Swift berdasarkan tanda baca dalam kunci katalog yang diingini. Simbol yang dijana bergantung pada maklumat katalog, dan jadual bukan lalai memperkenalkan ruang nama jadual. Menggunakan simbol setempat yang dijana dalam kod anda

Pemfaktoran semula ini khusus untuk peralihan daripada rentetan yang diekstrak kepada simbol yang dijana. Dokumentasi yang dirujuk tidak menetapkan operasi penamaan semula sejagat bagi setiap entri yang diurus secara manual atau setiap rujukan luaran. Jika pratonton tidak menyertakan rujukan yang diperlukan, uruskan rujukan itu secara jelas sebelum mengalih keluar kunci terdahulu.

Kekalkan pengekstrakan jika anda memilih kunci dan nilai lalai dalam kod

Anda juga boleh terus menggunakan pengekstrakan yang dipacu kod. Apple secara jelas menyokong kunci carian dan mesej sumber yang berasingan melalui String(localized:defaultValue:...): argumen pertama membekalkan kunci, manakala defaultValue membekalkan rentetan sumber. Contohnya, kunci semantik boleh mengekalkan Open collection sebagai mesej lalainya. Menyediakan teks app anda untuk terjemahan

Sumber app lengkap berikut menunjukkan corak itu dengan satu label statik dan satu kiraan integer. Gunakan sasaran app SwiftUI macOS dengan sasaran penggunaan macOS 12 atau lebih baharu, dan gantikan sumber entri app sedia ada dan bukannya menambah pengisytiharan @main kedua. Tambahkan Localizable.xcstrings pada sasaran app. Contoh ini telah disemak berdasarkan API Apple; ia tidak dikompil di sini kerana toolchain Swift tidak tersedia.

import Foundation
import SwiftUI

@main
struct CatalogRenameDemoApp: App {
    var body: some Scene {
        WindowGroup {
            CatalogRenameDemoView()
        }
    }
}

struct CatalogRenameDemoView: View {
    private let itemCount: Int = 7

    var body: some View {
        VStack(alignment: .leading, spacing: 12) {
            Text(verbatim: String(
                localized: "collection.open",
                defaultValue: "Open collection",
                comment: "Label for opening the selected collection."
            ))

            Text(verbatim: String(
                localized: "collection.itemCount",
                defaultValue: "\(itemCount) items",
                comment: "Number of items in the selected collection."
            ))
        }
        .padding()
    }
}

Di sini, String(localized:...) mendapatkan teks setempat sebelum rentetan yang terhasil dipaparkan. Text(verbatim:) menjadikan langkah paparan itu jelas. Apple membezakan penyetempatan rentetan serta-merta daripada LocalizedStringResource, yang mewakili carian yang boleh ditangguhkan. Bagi antara muka boleh guna semula yang menghantar mesej belum diselesaikan antara paparan, Apple mengesyorkan jenis setempat seperti LocalizedStringResource. LocalizedStringResource, Menyediakan teks app anda untuk terjemahan

Apabila memindahkan mesej sedia ada menggunakan pendekatan ini, bina projek untuk mencipta atau mengemas kini entri destinasi, kemudian pindahkan terjemahan sedia ada sebelum memadam entri terdahulu. Apple mendokumenkan cara memasukkan terjemahan secara langsung dengan memilih penyetempatan dan menyunting lajur bahasa yang sepadan. Bagi mesej berbeza-beza, kekalkan setiap cabang yang berkaitan dan bukannya menyalin teks peringkat atas sahaja. Pemindahan berperingkat ini ialah prosedur migrasi praktikal yang diperoleh daripada alat penyuntingan yang didokumenkan, bukannya jaminan penamaan semula automatik. Menyetempatkan dan mempelbagaikan teks dengan katalog rentetan

Apakah perbezaan antara pengekstrakan dengan pemformatan masa jalan?

Pengekstrakan berlaku semasa pembangunan: Xcode menemui ungkapan setempat yang disokong dan mengemas kini katalog. Pemformatan masa jalan berlaku apabila app mendapatkan mesej dan memasukkan nilai. Kiraan contoh 7 ialah argumen masa jalan; ia tidak sepatutnya menjadi sebahagian daripada kunci yang stabil.

Kekalkan interpolasi integer dalam ungkapan setempat. String.LocalizationValue Apple menyokong interpolasi dan mengarahkan pembangun yang mahukan pengecam sewenang-wenangnya kepada pemula dengan kunci statik dan defaultValue yang berasingan. Membina rentetan biasa yang telah dipaparkan terlebih dahulu tidak sama dengan mengekalkan mesej setempat itu berserta argumennya. String.LocalizationValue

Bagi mesej kiraan yang gramatis, pilih entri kiraan yang diekstrak, klik sambil menekan Control, kemudian pilih Vary by Plural. Lengkapkan varian sumber dan varian yang diperlukan bagi setiap penyetempatan sedia ada. Bagi sumber bahasa Inggeris, Apple menunjukkan One dengan %lld item dan Other dengan %lld items. Menambah interpolasi sahaja tidak melengkapkan varian tersebut. Menyetempatkan dan mempelbagaikan teks dengan katalog rentetan

Semasa menamakan semula, kekalkan jenis, kedudukan dan makna argumen. Jika mesej lama mengandungi kiraan integer, menggantikannya dengan rentetan yang telah diformatkan turut mengubah kontrak pemformatan. Bagi simbol yang dijana, Xcode mencipta fungsi dengan parameter berjenis untuk mesej yang mengandungi penentu format; periksa tandatangan tersebut semasa menukar. Menggunakan simbol setempat yang dijana dalam kod anda

Sahkan kandungan kekal sebelum mengalih keluar entri lama

Gunakan pemeriksaan berikut sebagai ujian penyelesaian. Pemeriksaan ini membezakan masalah katalog daripada masalah carian atau pemformatan.

Pemeriksaan Hasil yang dijangka Periksa jika gagal
Perkataan sumber Sepadan dengan titik semakan Nilai lalai hilang atau berubah
Terjemahan sedia ada Setiap nilai terdahulu masih tersedia di bawah kunci baharu Pemindahan tidak lengkap atau destinasi salah
Struktur varian Semua cabang jamak dan peranti terdahulu dikekalkan Hanya nilai peringkat atas disalin
Label masa jalan Memaparkan mesej yang dimaksudkan Ketidakpadanan kunci, jadual, bundle atau penyetempatan
Kiraan rekaan 0, 1, 7 Nilai dimasukkan dengan betul dan cabang jamak yang diperlukan berfungsi Ketidakpadanan argumen atau varian
Rujukan lama Tiada lagi penggunaan yang diperlukan Migrasi tidak lengkap

Untuk menguji app Mac dalam penyetempatan sedia ada, pilih Product > Scheme > Edit Scheme, pilih Run, buka Options, kemudian pilih App Language. Tutup dialog dan jalankan destinasi Mac. Ulangi bagi penyetempatan yang terjejas oleh penamaan semula itu, sambil memeriksa label sebenar dan mesej kiraan. Apple mendokumenkan aliran kerja ujian berasaskan skema ini. Menguji penyetempatan semasa menjalankan app

Jika kunci baharu muncul tetapi terjemahannya kosong, kembali ke entri terdahulu dan pindahkan kandungan yang hilang. Jika pengecam muncul pada skrin, periksa input carian. Jika hanya kiraan yang gagal, periksa interpolasi dan varian. Alih keluar entri lama selepas kandungannya diambil kira dan rujukan yang diperlukan dipindahkan. Perubahan yang selesai sepatutnya mengubah pengecam sambil mengekalkan mesej, argumennya dan terjemahan yang diterima pembaca sebelum ini.

Sumber