Komen penterjemah yang berguna menjelaskan maksud label, tempat label itu dipaparkan dan perkara yang berlaku apabila seseorang menggunakannya. Panduan ini menunjukkan cara menulis dan melampirkan komen tersebut dalam Xcode untuk pelayar bentuk Mac yang ringkas, menggunakan label bahasa Inggeris sintetik.

Apakah yang patut dijelaskan oleh komen penterjemah?

Mulakan dengan keputusan yang perlu dibuat oleh penterjemah. Label pendek seperti Round tidak menjelaskan peranan tatabahasa dan maksud yang dimaksudkan. Komen boleh mengenal pasti perkataan itu sebagai kata adjektif yang menerangkan kategori bentuk dan menjelaskan bahawa perkataan itu dipaparkan di atas sekumpulan pratonton. Apple mengesyorkan komen yang menjelaskan tempat dan cara sesuatu rentetan digunakan dalam antara muka. Discover String Catalogs

Bagi seseorang yang menyediakan label apl Mac untuk diterjemahkan, tugas khususnya ialah menukar setiap rentetan yang samar kepada penjelasan ringkas yang lengkap dengan sendirinya. Penterjemah sepatutnya dapat memahami tujuannya tanpa meneliti kod sumber.

Gunakan panduan penulisan empat bahagian ini. Ini ialah kaedah editorial yang berasaskan panduan Apple, bukannya format komen Apple yang diwajibkan:

Bahagian Soalan yang perlu dijawab Butiran contoh
Maksud Apakah yang dirujuk oleh perkataan dalam teks sumber? Round menerangkan bentuk dengan garis luar melengkung.
Peranan UI Apakah jenis teks antara muka ini? Tajuk kategori di atas pratonton bentuk.
Tingkah laku atau lokasi Apakah yang berlaku, atau apakah yang terdapat di sekelilingnya? Expand memaparkan butiran di bawah pratonton.
Kandungan berubah-ubah Apakah kandungan bagi setiap nilai yang disisipkan? Nilai pertama ialah nama bentuk; nilai kedua ialah nama koleksi.

Sertakan hanya bahagian yang mempengaruhi tafsiran. Tajuk statik tidak memerlukan penjelasan tentang tindakan. Butang lebih mudah difahami jika komen menerangkan dengan jelas perkara yang berlaku apabila butang itu diklik. Mesej dengan dua nama yang disisipkan memerlukan penjelasan tentang hubungan antara kedua-dua nama tersebut.

Apple secara khusus menyarankan agar komen menerangkan elemen antara muka, antara muka di sekelilingnya dan kandungan yang diwakili oleh pemegang tempat. Anggap butiran ini sebagai konteks praktikal untuk penterjemahan. Discover String Catalogs

Jadikan komen yang kabur sebagai kontrak mesej yang berguna

Contoh berikut adalah untuk pelayar bentuk Mac sebagai ilustrasi. Setiap komen yang diperbaik menerangkan tingkah laku antara muka yang diandaikan dan dinyatakan dengan jelas; sesuaikan tingkah laku itu dengan kawalan sebenar sebelum menggunakan ayat tersebut.

Label sumber Komen yang lemah Komen yang lebih berguna
Shapes Label untuk bentuk. Item navigasi bar sisi yang membuka senarai bentuk geometri. Kata nama jamak.
Round Teks bentuk. Tajuk kategori di atas pratonton bentuk dengan garis luar melengkung. Kata adjektif yang menerangkan bentuk.
Expand Tajuk butang. Butang di bawah pratonton bentuk yang memaparkan butiran di bawah pratonton itu. Kata kerja yang menyatakan tindakan.
Selected Label pilihan. Status di sebelah bentuk yang sedang dipilih untuk pratonton. Menerangkan keadaan semasa bentuk itu.

Versi yang lemah hanya mengulangi perkara yang sudah dapat dilihat oleh penterjemah. Versi yang lebih baik memberikan hubungan yang tiada: objek yang diterangkan oleh kata adjektif, kandungan yang dipaparkan oleh butang atau item yang mempunyai keadaan tertentu.

Dalam bahasa Inggeris, kata nama menamakan sesuatu, kata adjektif menerangkan sesuatu dan kata kerja perintah mengarahkan tindakan. Perbezaan ini membantu menjelaskan perkataan ringkas dalam antara muka. Contohnya, Selected dalam ilustrasi ini menerangkan keadaan sedia ada; Select pada butang pula meminta pengguna melakukan tindakan. Nyatakan tafsiran yang diperlukan oleh antara muka.

Pastikan komen bersifat konkrit. Bagi Expand, jelaskan sama ada kawalan itu memaparkan teks butiran, membesarkan pratonton atau membuka kumpulan bar sisi. Menamakan operasi lebih berguna daripada mengatakan bahawa kawalan itu menjadikan sesuatu lebih besar.

Elakkan mengenakan peraturan pemformatan bahasa Inggeris yang tidak perlu. Jika antara muka memerlukan tajuk kategori yang ringkas, nyatakan demikian. Jangan mereka had aksara yang tetap atau mewajibkan terjemahan mengekalkan susunan perkataan bahasa Inggeris. Dokumentasikan kekangan reka letak yang sebenar hanya jika anda tahu kekangan itu terpakai.

Tambahkan komen penterjemah dalam SwiftUI

Apple mendokumenkan parameter comment: pada Text sebagai cara untuk menyertakan petunjuk penterjemahan. Apabila pemula rentetan yang mudah bagi sesuatu kawalan tidak menyediakan komen yang diperlukan, gunakan pembina kandungannya dengan paparan Text yang dinyatakan secara eksplisit. Apple menunjukkan corak ini untuk Label dan menjelaskan bahawa banyak kawalan SwiftUI menyokongnya. Preparing views for localization

Contoh lengkap di bawah ialah apl SwiftUI macOS yang kecil. Dalam Xcode, cipta projek apl macOS menggunakan SwiftUI, tetapkan sasaran penggunaan kepada macOS 13 atau lebih baharu, kemudian gantikan kod apl dan paparan kandungan yang dijana dengan satu fail ini. Kekalkan hanya satu titik masuk apl. Sampel ini menggunakan nama sintetik yang tetap dan memaparkan ayat butiran apabila pengguna mengklik Expand.

import SwiftUI

@main
struct ShapeCommentDemoApp: App {
    var body: some Scene {
        WindowGroup {
            ShapeBrowserView()
        }
    }
}

struct ShapeBrowserView: View {
    @State private var showsDetails = false

    private let shapeName = "Circle A"
    private let collectionName = "Shape Set A"

    var body: some View {
        VStack(alignment: .leading, spacing: 16) {
            Text(
                "Round",
                comment: "Category heading above previews of shapes with curved outlines. Adjective describing the shapes."
            )
            .font(.headline)

            Circle()
                .fill(Color.blue)
                .frame(width: 80, height: 80)

            Text(
                "\(shapeName) in \(collectionName)",
                comment: "Caption below a shape preview. The first value is the shape name; the second is the collection containing it. Sample names: Circle A and Shape Set A."
            )

            Button {
                showsDetails = true
            } label: {
                Text(
                    "Expand",
                    comment: "Button below a shape preview that reveals its details beneath the preview. Verb expressing an action."
                )
            }
            .disabled(showsDetails)

            if showsDetails {
                Text(
                    "A shape with a curved outline.",
                    comment: "Detail sentence revealed below the preview after clicking Expand. Describes the displayed circle."
                )
            }
        }
        .padding(24)
        .frame(minWidth: 360, minHeight: 300)
    }
}

Contoh ini telah diteliti berdasarkan corak API yang didokumenkan; contoh ini tidak dikompil atau dijalankan di sini kerana persekitaran yang tersedia tidak mempunyai rantaian alat Swift.

Untuk rentetan yang dipaparkan kepada pengguna dan dicipta di luar paparan SwiftUI, Apple mendokumenkan String(localized:comment:). Gunakan argumen komen API penyetempatan untuk melampirkan konteks pada mesej. Apple juga menyokong kunci carian dan nilai sumber lalai yang berasingan jika kedua-duanya perlu berbeza. Preparing your app’s text for translation

Jelaskan nilai yang disisipkan berdasarkan maksud dan hubungannya

Kapsyen dalam contoh mengandungi dua interpolasi Swift: \(shapeName) dan \(collectionName). Interpolasi Swift menyisipkan nilai ungkapan ke dalam literal rentetan. Nama pemboleh ubah ialah sebahagian daripada kod sumber; penjelasan itu tetap perlu difahami oleh seseorang yang tidak dapat melihat nama tersebut. Strings and Characters

Bagi nilai sintetik yang ditunjukkan, kapsyen bahasa Inggeris berbunyi Circle A in Shape Set A. Komen itu menerangkan susunan nilai yang disisipkan dan hubungannya: satu menamakan bentuk, manakala satu lagi menamakan koleksi yang mengandungi bentuk itu. Maklumat ini lebih berguna daripada sekadar menerangkan dua argumen rentetan.

Semasa menyemak mesej berinterpolasi, tanya tiga soalan:

  1. Apakah jenis kandungan yang boleh muncul pada setiap kedudukan: nama, bilangan atau jenis nilai yang lain?
  2. Bagaimanakah nilai-nilai itu berkaitan antara satu sama lain?
  3. Adakah komen itu kekal tepat untuk setiap nilai yang boleh diberikan oleh apl?

Pastikan contoh dikenal pasti dengan jelas sebagai sampel. Di sini, Circle A dan Shape Set A menggambarkan peranan argumen. Kedua-duanya tidak menetapkan terjemahan yang diwajibkan atau senarai lengkap nama yang mungkin digunakan.

Bilangan memerlukan keputusan pelaksanaan yang berasingan. Jika anda kemudian menambah kapsyen seperti 3 shapes, komen boleh menerangkan perkara yang dikira, tetapi variasi tatabahasa perlu diletakkan dalam katalog. Apple mendokumenkan penggunaan Vary by Plural untuk bilangan berinterpolasi, termasuk bentuk bahasa Inggeris yang berasingan seperti 1 item dan 2 items. Localizing and varying text with a string catalog

Cari dan periksa komen dalam Xcode

Untuk menghubungkan komen sumber dengan katalog, ikut aliran kerja yang didokumenkan oleh Apple:

  1. Pilih File > New > File from Template.
  2. Tapis untuk string, pilih String Catalog di bawah Resource, kemudian cipta katalog itu dengan nama lalai Localizable.
  3. Pilih Product > Build untuk mengekstrak rentetan yang boleh disetempatkan.
  4. Pilih Localizable.xcstrings dalam navigator Projek.
  5. Pilih Editor > Assistant, kemudian pilih kunci untuk memeriksa sumbernya di sebelah katalog. Localizing and varying text with a string catalog

Semak komen dalam katalog berdasarkan penggunaan sebenar. Dalam sampel ini, Round patut menerangkan tajuk kategori dan Expand patut menerangkan cara butiran dipaparkan. Jika rentetan tiada, pastikan kod menggunakan API yang boleh disetempatkan dan Use Compiler to Extract Swift Strings diaktifkan. Apple menyatakan bahawa tetapan binaan ini diperlukan untuk pengekstrakan rentetan Swift berasaskan pengkompil. Discover String Catalogs

Apple juga menyokong penyuntingan konteks secara langsung dalam lajur komen String Catalog. Penjanaan komen automatik diperkenalkan dalam Xcode 26; dokumentasi semasa menerangkan cara mengklik kekunci sambil menekan Control dan memilih Generate Comment. Jika pilihan itu tiada dalam persediaan anda, lampirkan komen dalam kod atau masukkannya dalam katalog. Code-along: Explore localization with Xcode, Localizing and varying text with a string catalog

Semak semula ayat yang dijana berdasarkan tingkah laku antara muka. Huraian yang mengenal pasti butang dengan betul mungkin masih perlu menjelaskan objek atau hasilnya. Bagi contoh ini, perbezaan yang berguna ialah Expand memaparkan ayat butiran di bawah pratonton.

Tentukan sama ada dua label yang sama boleh berkongsi konteks

Ejaan bahasa Inggeris yang sepadan tidak membuktikan bahawa maksudnya sama. Katakan skrin lain menggunakan Round sebagai tindakan untuk membundarkan nilai angka. Menggabungkan penggunaan itu dengan tajuk kategori bentuk akan memerlukan satu entri katalog untuk menerangkan dua peranan tatabahasa yang berbeza.

Apple menjelaskan bahawa rentetan yang boleh disetempatkan mempunyai kunci carian dan tergolong dalam jadual; kunci adalah unik dalam jadual masing-masing. Dokumentasi Swift Apple juga menyediakan cara yang disokong untuk menggunakan kunci berbeza bersama nilai sumber lalai. Gunakan kunci berasingan apabila maksudnya memerlukan terjemahan bebas, walaupun nilai paparan bahasa Inggerisnya sama. Discover String Catalogs, Preparing your app’s text for translation

Peraturan keputusan yang praktikal ialah bertanya sama ada satu komen boleh menerangkan setiap penggunaan dengan tepat. Jika maksud dan peranan UI kekal konsisten, konteks yang dikongsi mungkin sesuai. Jika penjelasan perlu menghuraikan operasi yang tidak berkaitan, pertimbangkan semula struktur kunci. Ini ialah inferens reka bentuk daripada model kunci dan jadual Apple, bukannya peraturan bahawa setiap kawalan memerlukan rentetannya sendiri.

Sebelum menyerahkan sesuatu label, baca komennya tanpa melihat kod sumber. Komen itu sepatutnya membolehkan penterjemah mengenal pasti maksud yang dimaksudkan, memahami kedudukan teks itu dalam antara muka dan memahami sebarang kandungan yang disisipkan. Semak semula komen setiap kali tingkah laku atau peranan label berubah supaya penjelasannya terus menggambarkan antara muka yang dilihat pengguna.

Sumber