Yararlı bir çevirmen yorumu, bir etiketin ne anlama geldiğini, nerede göründüğünü ve biri onu kullandığında ne olduğunu açıklar. Bu kılavuz, sentetik İngilizce etiketler kullanarak basit bir Mac şekil tarayıcısı için Xcode’da bu yorumların nasıl yazılıp ekleneceğini gösterir.

Çevirmen yorumu neyi açıklamalı?

Çevirmenin vermesi gereken kararla başlayın. Round gibi kısa bir etiket, dilbilgisel rolünü ve amaçlanan anlamını belirsiz bırakır. Bir yorum, bunun şekil kategorisini tanımlayan bir sıfat olduğunu belirtebilir ve önizleme grubunun üstünde göründüğünü açıklayabilir. Apple, arayüzde bir dizenin nerede ve nasıl kullanıldığını açıklığa kavuşturan yorumlar önerir. Dize Kataloglarını Keşfedin

Bir Mac uygulamasının etiketlerini çeviriye hazırlayan kişi için somut görev, belirsiz her dizeyi kısa ve kendi başına anlaşılır bir açıklamaya dönüştürmektir. Çevirmen, kaynak kodda gezinmeden dizenin amacını anlayabilmelidir.

Bu dört parçalı yazım yardımını kullanın. Bu, Apple’ın rehberliğinden türetilmiş bir editoryal yöntemdir; Apple’ın zorunlu tuttuğu bir yorum biçimi değildir:

Bölüm Yanıtlanacak soru Örnek ayrıntı
Anlam Kaynak metindeki ifade neyi anlatıyor? Round, dış çizgileri eğri olan şekilleri tanımlar.
Arayüz rolü Bu ne tür bir arayüz metni? Şekil önizlemelerinin üstünde yer alan kategori başlığı.
Davranış veya konum Ne olur ya da etrafında ne bulunur? Expand, önizlemenin altında ayrıntıları gösterir.
Değişken içerik Eklenen değerlerin her biri neler içerebilir? İlk değer bir şeklin adıdır; ikinci değer bir koleksiyonun adıdır.

Yalnızca yorumu etkileyen bölümleri ekleyin. Sabit bir başlık için eylem açıklaması gerekmez. Bir düğme, tıklanınca ne yaptığının açıkça belirtilmesinden yarar görür. Eklenen iki ad içeren bir iletide, bu adlar arasındaki ilişki belirtilmelidir.

Apple özellikle arayüz öğesinin, çevresindeki arayüzün ve yer tutucuların temsil ettiği içeriğin açıklanmasını önerir. Bu ayrıntıları, çeviri için pratik bağlam olarak ele alın. Kod eşliğinde: Xcode ile yerelleştirmeyi keşfedin

Muğlak yorumları yararlı ileti sözleşmelerine dönüştürün

Aşağıdaki örnekler, açıklama amacıyla oluşturulmuş bir Mac şekil tarayıcısına aittir. Her iyileştirilmiş yorum, varsayılan ve açık bir arayüz davranışını açıklar; ifadeyi kullanmadan önce davranışı gerçek denetime göre uyarlayın.

Kaynak etiketi Zayıf yorum Daha yararlı yorum
Shapes Şekiller için etiket. Geometrik şekiller listesini açan kenar çubuğu gezinme öğesi. Çoğul isim.
Round Şekil metni. Dış çizgileri eğri olan şekillerin önizlemelerinin üstündeki kategori başlığı. Şekilleri tanımlayan sıfat.
Expand Düğme başlığı. Şekil önizlemesinin altında bulunan ve ayrıntılarını önizlemenin altında gösteren düğme. Eylem bildiren fiil.
Selected Seçim etiketi. Önizleme için o anda seçilmiş şeklin yanında görünen durum. Şeklin mevcut durumunu tanımlar.

Zayıf sürümler, çevirmenin zaten görebildiği şeyi tekrarlar. Daha güçlü sürümler eksik ilişkileri açıklar: sıfatın hangi nesneyi tanımladığı, düğmenin hangi içeriği gösterdiği veya hangi öğenin belirli bir durumda olduğu.

İngilizcede isim bir şeyi adlandırır, sıfat bir şeyi niteler ve emir kipindeki fiil bir eylemi yönlendirir. Bu ayrımlar, kısa arayüz ifadelerini açıklamaya yardımcı olur. Örneğin, bu örnekteki Selected mevcut bir durumu tanımlar; düğmedeki Select ise bir eylem ister. Arayüzün hangi yorumu gerektirdiğini belirtin.

Yorumları somut tutun. Expand için denetimin ayrıntı metnini mi gösterdiğini, önizlemeyi mi büyüttüğünü, yoksa bir kenar çubuğu grubunu mu açtığını açıklayın. İşlemi adlandırmak, bir şeyi büyüttüğünü söylemekten daha yararlıdır.

Gereksiz İngilizce biçimlendirme kuralları dayatmaktan kaçının. Arayüzde kısa bir kategori başlığı gerekiyorsa bunu belirtin. Sabit bir karakter sınırı uydurmayın veya çevirinin İngilizce sözcük sırasını korumasını şart koşmayın. Gerçek bir yerleşim kısıtını yalnızca geçerli olduğunu biliyorsanız belgeleyin.

SwiftUI’da çevirmen yorumları ekleyin

Apple, Text üzerindeki comment: parametresini çeviri ipuçları eklemenin bir yolu olarak belgeler. Bir denetimin kullanışlı dize başlatıcısı ihtiyacınız olan yorumu sağlamıyorsa, açık bir Text görünümü içeren içerik oluşturucusunu kullanın. Apple bu kalıbı Label için gösterir ve birçok SwiftUI denetiminin bunu desteklediğini açıklar. Görünümleri yerelleştirmeye hazırlama

Aşağıdaki tam örnek, küçük bir macOS SwiftUI uygulamasıdır. Xcode’da SwiftUI kullanan bir macOS uygulama projesi oluşturun, dağıtım hedefini macOS 13 veya daha yeni bir sürüme ayarlayın ve oluşturulan uygulama ile içerik görünümü kodunu bu tek dosyayla değiştirin. Yalnızca bir uygulama giriş noktası bırakın. Örnek, sabit ve sentetik adlar kullanır; kullanıcı Expand düğmesine tıkladığında bir ayrıntı cümlesini gösterir.

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)
    }
}

Bu örnek, belgelenmiş API kalıplarına göre incelenmiştir; mevcut ortamda Swift araç zinciri bulunmadığından burada derlenmemiş veya çalıştırılmamıştır.

SwiftUI görünümü dışında oluşturulan, kullanıcıya yönelik dizeler için Apple String(localized:comment:) yöntemini belgeler. Bağlamı iletiye eklemek için yerelleştirme API’sinin yorum bağımsız değişkenini kullanın. Apple ayrıca, arama anahtarının ve varsayılan kaynak değerinin birbirinden farklı olması gerektiğinde ayrı ayrı belirlenmesini destekler. Uygulamanızın metinlerini çeviriye hazırlama

Eklenen değerleri anlamlarına ve aralarındaki ilişkiye göre açıklayın

Örnekteki başlık, iki Swift interpolasyonu içerir: \(shapeName) ve \(collectionName). Swift interpolasyonu, ifadelerin değerlerini bir dize sabitine ekler. Değişken adları kaynak koda aittir; açıklama, bu adları göremeyen biri için de anlamlı olmalıdır. Dizeler ve Karakterler

Gösterilen sentetik değerlerle İngilizce başlık Circle A in Shape Set A şeklindedir. Yorum hem eklenen değerlerin sırasını hem de aralarındaki ilişkiyi açıklar: biri şeklin, diğeri onu içeren koleksiyonun adıdır. Bu, iki dize bağımsız değişkenini yalnızca tanımlamaktan daha kullanışlı bilgi sağlar.

Enterpole edilmiş bir iletiyi incelerken şu üç soruyu sorun:

  1. Her konumda ne tür bir içerik görünebilir: bir ad, bir sayı veya başka türde bir değer mi?
  2. Değerler birbiriyle nasıl ilişkilidir?
  3. Uygulamanın sağlayabileceği her değer için yorum doğru kalıyor mu?

Örneklerin örnek olduğu açıkça belirtilmelidir. Burada Circle A ve Shape Set A, bağımsız değişkenlerin rollerini gösterir. Bunlar zorunlu bir çeviri veya olası tüm adların eksiksiz listesi değildir.

Sayılar için ayrıca bir uygulama kararı gerekir. Daha sonra 3 shapes gibi bir başlık eklerseniz yorum neyin sayıldığını açıklayabilir; ancak dilbilgisel biçimler kataloğa aittir. Apple, enterpole edilmiş sayılar için Vary by Plural seçeneğinin kullanılmasını ve İngilizcede 1 item ile 2 items gibi ayrı biçimlerin tanımlanmasını belgeler. Dize kataloğuyla metni yerelleştirme ve çeşitleme

Xcode’da yorumları bulun ve inceleyin

Kaynak koddaki yorumları katalogla ilişkilendirmek için Apple’ın belgelenmiş iş akışını izleyin:

  1. File > New > File from Template seçeneğini belirleyin.
  2. string için filtre uygulayın, Resource altından String Catalog seçeneğini belirleyin ve varsayılan Localizable adıyla oluşturun.
  3. Yerelleştirilebilir dizeleri çıkarmak için Product > Build seçeneğini belirleyin.
  4. Project gezgininde Localizable.xcstrings dosyasını seçin.
  5. Editor > Assistant seçeneğini belirleyin, ardından katalogla birlikte kaynağını incelemek için bir anahtar seçin. Dize kataloğuyla metni yerelleştirme ve çeşitleme

Katalogdaki yorumu gerçek kullanımına göre denetleyin. Örnekte Round bir kategori başlığını açıklamalı, Expand ise ayrıntıların gösterilmesini tanımlamalıdır. Bir dize eksikse kodun yerelleştirilebilir bir API kullandığını ve Use Compiler to Extract Swift Strings seçeneğinin etkin olduğunu kontrol edin. Apple, derleyici tabanlı Swift dizesi çıkarımı için bu derleme ayarının gerekli olduğunu belirtir. Dize Kataloglarını Keşfedin

Apple, String Catalog’ın yorumlar sütununda bağlamın doğrudan düzenlenmesini de destekler. Otomatik yorum oluşturma özelliği Xcode 26’da sunulmuştur; güncel belgelerde bir anahtara Control tuşunu basılı tutarak tıklayıp Generate Comment seçeneğini belirleme açıklanır. Bu seçenek kurulumunuzda yoksa kodda yorum ekleyin veya katalogda girin. Kod eşliğinde: Xcode ile yerelleştirmeyi keşfedin, Dize kataloğuyla metni yerelleştirme ve çeşitleme

Oluşturulan ifadeleri arayüzün davranışına göre gözden geçirin. Bir düğmeyi doğru tanımlayan açıklamada, nesnenin veya sonucun da açıklığa kavuşturulması gerekebilir. Bu örnekte önemli ayrım, Expand düğmesinin önizlemenin altında bir ayrıntı cümlesi göstermesidir.

Aynı etiketleri kullanan iki yerin bağlamı paylaşabileceğine karar verin

İngilizce yazımların aynı olması, anlamların da aynı olduğunu göstermez. Başka bir ekranda Round, sayısal bir değeri yuvarlayan bir eylem olarak kullanılıyor olabilir. Bu kullanımı şekil kategorisi başlığıyla birleştirmek, tek bir katalog girdisinin iki farklı dilbilgisel rolü açıklamasını gerektirir.

Apple, yerelleştirilebilir bir dizenin bir arama anahtarı olduğunu ve bir tabloya ait olduğunu açıklar; anahtarlar kendi tablolarında benzersizdir. Apple’ın Swift belgeleri, varsayılan kaynak değerinden farklı bir anahtar kullanmanın desteklenen bir yolunu da sunar. Anlamlar birbirinden bağımsız çeviriler gerektiriyorsa, İngilizce görüntülenen değerleri aynı olsa bile ayrı anahtarlar kullanın. Dize Kataloglarını Keşfedin, Uygulamanızın metinlerini çeviriye hazırlama

Pratik bir karar kuralı olarak, tek bir yorumun her kullanımı doğru biçimde açıklayıp açıklayamayacağını sorun. Anlam ve arayüz rolü tutarlı kalıyorsa bağlamı paylaşmak uygun olabilir. Açıklama birbiriyle ilgisiz işlemleri tarif etmek zorunda kalıyorsa anahtar yapısını yeniden değerlendirin. Bu, her denetimin kendi dizesi olması gerektiğini belirten bir kural değil, Apple’ın anahtar ve tablo modelinden çıkarılan bir tasarım sonucudur.

Bir etiketi devretmeden önce yorumunu kaynak kod olmadan okuyun. Yorum, çevirmenin amaçlanan anlamı belirlemesini, metnin arayüzdeki yerini kavramsal olarak saptamasını ve eklenen içeriği anlamasını sağlamalıdır. Açıklamanın kullanıcının gördüğü arayüzü tarif etmeye devam etmesi için etiketin davranışı veya rolü her değiştiğinde yorumu güncelleyin.

Kaynaklar