Bir Mac uygulamasındaki yinelenen iletileri bir araya getirmek için her ortak anlama bir yerelleştirme anahtarı ve bir Swift tanımı verin, ardından bu iletiyi göründüğü her yerde kullanın. Bağımsız değişkenlerini, çoğul kurallarını ve çevirmen bağlamını bir arada tutun; yalnızca İngilizce metinlerin eşleşmesi yeterli değildir.

Bu kılavuz, SwiftUI'da ve Interface Builder penceresinde bir seçim özetini sürdüren Mac geliştiricileri içindir. Amaç, XIB ve Swift kodunda ayrı cümle şablonları tutmadan 2 items selected in Batch A. gibi iletileri tutarlı biçimde görüntülemektir. Aşağıdaki tüm sayılar ve etiketler sentetiktir.

Hangi yinelenen iletilerin birlikte ele alınacağına karar verin

Katalogları düzenlemeden önce ileti sözleşmesini tanımlayın: Cümle ne anlama geliyor, hangi değerleri kabul ediyor ve nerelerde görünüyor? Bu örneğin sözleşmesi şöyledir:

Sözleşme öğesi Tanım
Anlam Adlandırılmış bir koleksiyonda o anda seçili öğelerin sayısı
Anahtar selection.summary
Tablo Localizable
Paket Ana uygulama paketi
Bağımsız değişken 1 Int64 türünde seçim sayısı
Bağımsız değişken 2 Batch A gibi değişmez bir koleksiyon etiketi
Değişken Seçim sayısına göre belirlenen çoğul biçim
Bağlam SwiftUI'da ve AppKit etiketinde görüntülenen tam bir durum cümlesi

Bu sözleşmeyi birleştirme ölçütü olarak kullanın. Anlamları, bağımsız değişkenleri ve dilbilgisel işlevleri uyuşuyorsa iki kullanım aynı iletiyi paylaşabilir. Seçili öğe sayısı ile toplam öğe sayısı, ikisi de şu an 2 items olarak görüntülense bile ayrı kalmalıdır. Select adlı bir düğme de eylem ifade ettiğinden kendi iletisine ihtiyaç duyar.

Apple, metinleri birbirinden ayırmak için açık anahtarların varsayılan değerlerden ayrı kullanılmasını destekler. Böylece okunabilir kaynak metni korurken iletiyi amacına göre adlandırabilirsiniz. Açıklama bağlam sağlar; anahtar ise girdiyi tanımlar. String’in açık anahtarlı başlatıcısı.

Tabloyu ve paketi de arama sözleşmesinin bir parçası olarak ele alın. Başka bir tablodaki anahtar ayrı bir arama hedefidir. Apple, tablo seçiminin table veya tableName parametresi üzerinden yapıldığını belgeliyor ve yerelleştirilebilir metinlerin LocalizedStringResource üzerinden geçirilmesini öneriyor. Bu örnekte yardımcıyı ve kataloğu uygulama hedefinde tutun ve ana paketi kullanın. Uygulamanızın metinlerini çeviriye hazırlama.

Çıkarma ve çalışma zamanı biçimlendirmesi arasındaki sınırı anlayın

Çıkarma, Xcode derleme yaparken gerçekleşir: desteklenen yerelleştirilebilir ifadeleri bulur ve kaynak metinlerini kataloglarla eşitler. Çalışma zamanı yerelleştirmesi ise uygulama bir iletiyi çözümlerken ve gerçek değerleri yerine koyarken gerçekleşir. Katalogda bir girdi bulunması, çıkarma işleminin bu girdiyi bulduğunu kanıtlar; her denetimin bunu doğru görüntülediğini kanıtlamaz.

Interface Builder'ın kendine özgü bir kaynak iş akışı vardır. Apple, bir storyboard veya XIB dosyasıyla eşleştirilmiş katalogları belgeliyor; Swift kaynakları ise normalde Localizable tablosuna katkıda bulunuyor. Belgelenmiş iş akışı, yalnızca görünür metinleri eşleştiği için iletileri birleştiren kaynaklar arası bir takma addan söz etmiyor. Desteklenen pratik bir yaklaşım, arayüz yüklendikten sonra ortak yerelleştirilmiş iletiyi Swift'ten atamaktır. Bu uygulama, Apple'ın belgelenmiş API'lerinden çıkarılmıştır. String Catalogs'u keşfetme.

SwiftUI da doğrudan yerelleştirme anahtarı olan metin ile sıradan bir dize değeri arasında ayrım yapar. Örneğin Text("Summary") yerelleştirme isterken String değişkeni geçirmek, arama yapmadan değişkenin değerini görüntüler. Çalışma zamanındaki bir dizeyi LocalizedStringKey ile sarmalamak arama ister, ancak bu, çıkarmanın olası değerleri bulduğunu kanıtlamakla karıştırılmamalıdır. LocalizedStringKey.

Bu nedenle aşağıdaki tasarım, çıkarılabilir sabit metni tek bir yardımcıda tutar. Sayıyı ve etiketi LocalizedStringResource içinde taşır, ardından tamamlanmış bir dizenin gerektiği yerde bu kaynağı çözümler. Apple, bu kaynak türünü yerelleştirme aramasını erteleyen bir yol olarak tanımlar. Bu örneğin en düşük hedefi olan macOS 13 ve sonraki sürümlerde kullanılabilir. LocalizedStringResource.

Ortak iletiyi Swift'te bir kez tanımlayın

SwiftUI kullanan bir macOS uygulama projesi oluşturun, dağıtım hedefini macOS 13 veya sonraki bir sürüme ayarlayın ve uygulama hedefine Localizable.xcstrings ekleyin. Güncel Xcode belgelerinde dosya oluşturma yolu File > New > File from Template şeklindedir; string için arama yapıp String Catalog öğesini seçin. Dize kataloğuyla metni yerelleştirme ve farklı biçimler oluşturma.

Oluşturulan uygulama giriş noktasını aşağıdaki eksiksiz programla değiştirin. Hedefte yalnızca bir @main bildirimi bulunması için özgün uygulama giriş noktasını kaldırın. SwiftUI penceresi bir XIB'den bağımsız çalışır; sonraki bölümde mevcut bir Interface Builder etiketini uyarlarken eklenen AppKit alt sınıfı kullanılır.

import AppKit
import Foundation
import SwiftUI

enum SelectionMessages {
    static func summary(
        count: Int64,
        collectionLabel: String
    ) -> LocalizedStringResource {
        LocalizedStringResource(
            "selection.summary",
            defaultValue: "\(count) items selected in \(collectionLabel).",
            table: "Localizable",
            comment: "Complete selection-status sentence used in SwiftUI and an AppKit label. Argument 1 is the selected-item count; argument 2 is a literal collection label. Pluralize by argument 1."
        )
    }
}

struct SelectionDemoView: View {
    private let counts: [Int64] = [0, 1, 2]
    private let collectionLabel = "Batch A"

    var body: some View {
        VStack(alignment: .leading, spacing: 12) {
            ForEach(counts, id: \.self) { count in
                Text(String(localized: SelectionMessages.summary(
                    count: count,
                    collectionLabel: collectionLabel
                )))
            }
        }
        .padding(24)
        .frame(minWidth: 360, minHeight: 160)
    }
}

final class SelectionSummaryField: NSTextField {
    override func awakeFromNib() {
        super.awakeFromNib()
        // Synthetic initial state for the Interface Builder example.
        updateSelection(count: 2, collectionLabel: "Batch A")
    }

    func updateSelection(count: Int64, collectionLabel: String) {
        stringValue = String(localized: SelectionMessages.summary(
            count: count,
            collectionLabel: collectionLabel
        ))
    }
}

@main
struct SelectionDemoApp: App {
    var body: some Scene {
        WindowGroup {
            SelectionDemoView()
        }
    }
}

Statik anahtar iletiyi tanımlar; araya eklenen varsayılan değer ise kaynak cümleyi ve çalışma zamanı bağımsız değişkenlerini sağlar. Başlatıcı tabloyu, paketi ve çevirmen açıklamasını da kabul eder. Varsayılan paketi ana pakettir. LocalizedStringResource’un açık anahtarlı başlatıcısı.

Batch A etiketi, cümleye eklenen örnek içeriktir. Başka bir ileti anahtarı değildir. Bu ayrım, koleksiyon etiketlerini çevrelerindeki arayüz metninden ayrı tutar. Gerçek uygulamanızda önceden tanımlanmış ve çevrilmiş koleksiyon adları varsa, bunları burada sağlamadan önce kendi tanımları üzerinden yerelleştirin.

Bu cümleyi sayı, items selected in ve etiket gibi bağımsız yerelleştirilmiş parçalardan oluşturmayın. Tam cümleyi sözleşmede tutmak, yerelleştiricilere ifadeyi ve bağımsız değişken sırasını birlikte ayarlayabilecekleri tek bir birim verir.

Interface Builder etiketini aynı tanıma yönlendirin

Mevcut bir XIB veya storyboard için özet metnini gösteren statik bir NSTextField etiketi kullanın. Özel sınıfını SelectionSummaryField, modülünü de uygulama hedefi olarak ayarlayın. Bu etiket artık metnini ortak Swift tanımından aldığından, tasarım zamanındaki metin değerinden eski cümleyi silin.

Arayüz yüklendiğinde alt sınıf super.awakeFromNib() metodunu çağırır ve sentetik başlangıç özetini atar. Apple, awakeFromNib() metodunu yükleme sonrası kancası olarak belgeliyor; bu aşamada çıkış ve eylem bağlantıları kurulmuş olur ve üst sınıf uygulamasının çağrılması gerekir. awakeFromNib().

Gerçek pencerede, seçim her değiştiğinde bağlı etiket üzerinde updateSelection(count:collectionLabel:) metodunu çağırıp SwiftUI'ya sağlanan model değerlerinin aynısını kullanın. Sentetik başlangıç atamasını pencerenin gerçek başlatma akışıyla değiştirin. Yükleme sırasında yapılan tek seferlik bir atama sonraki seçim değişikliklerini izleyemez.

AppKit bağdaştırıcısı, NSTextField metnini atamak için belgelenmiş bir yol olan stringValue özelliğini ayarlar. Böylece düzen Interface Builder'da kalırken iletinin sahipliği Swift'e taşınır. Tam cümle için yeterli genişlik veya satır kaydırma olanağı sağlayın. NSTextField.

İlgisiz statik arayüz metinlerini mevcut kaynak iş akışlarında tutun. Bu taşıma tek bir ortak iletiyle ilgilidir; her etiketi Swift'e taşımak gerekmez. Ayrıca bir bağlamanın veya başka bir denetleyici atamasının, özeti daha sonra eski metinle değiştirmediğini kontrol edin.

Bağımsız değişkenleri değiştirmeden çoğul biçimleri yapılandırın

Product > Build öğesini seçin, Localizable.xcstrings dosyasını açın ve selection.summary girdisini bulun. Girdiye Control tuşunu basılı tutarak tıklayın, Vary by Plural öğesini seçin ve Xcode hangi bağımsız değişkeni değiştireceğini sorarsa sayısal sayı bağımsız değişkenini seçin. Apple, araya eklenmiş iletiler için bu iş akışını belgeliyor. Dize kataloğuyla metni yerelleştirme ve farklı biçimler oluşturma.

İngilizce kaynak yerelleştirmesinde tekil biçimi 1 item selected in Batch A.; diğer biçimi ise 2 items selected in Batch A. gibi cümleler üretecek şekilde ayarlayın. Xcode'un sağladığı iki bağımsız değişken yer tutucusunu da koruyun. Bir yer tutucuyu örnek bir sayı veya etiketle değiştirmek yerine çevresindeki ifadeyi düzenleyin.

Sentetik girdi Çoğul yapılandırmasından sonra beklenen İngilizce sonuç
Sayı 0, etiket Batch A 0 items selected in Batch A.
Sayı 1, etiket Batch A 1 item selected in Batch A.
Sayı 2, etiket Batch A 2 items selected in Batch A.
Sayı 2, etiket Batch B 2 items selected in Batch B.

Bunlar ölçülmüş sonuçlar değil, örnek kabul durumlarıdır. Çoğul biçimleri yapılandırılmadan önce varsayılan kaynak cümlesi her sayı için items ifadesini içerir. Çıkarma, araya eklenmiş iletiyi korur; dilbilgisini kendiliğinden düzeltmez.

Son satırdaki değişen etiket tanılama açısından faydalıdır: görüntülenen metin Batch A olarak kalıyorsa bir biçime örnek değer sabit kodlanmış olabilir veya çağıran taraf eski durum değerini sağlıyor olabilir. Etiket kayboluyorsa yardımcının imzasını değiştirmeden önce biçimin yer tutucularını inceleyin.

Eski girdileri kaldırmadan önce her görüntüleme yolunu doğrulayın

SwiftUI penceresini ve gerçek Interface Builder penceresini ayrı ayrı sınayın. Her ikisinde de aynı sayıları ve etiketleri kullanın. İlk yüklemeyi, daha sonraki bir seçim değişikliğini ve Batch A Extended gibi daha uzun bir sentetik etiketi kontrol edin. İfadelerin birbiriyle uyuştuğunu ve cümlenin okunabilir kaldığını doğrulayın.

Desteklenen her yerelleştirme için Product > Scheme > Edit Scheme öğesini seçin, Run öğesini seçin, Options bölümünü açın ve App Language ayarını yapın. Uygulamayı yeniden çalıştırıp her iki görüntüleme yolunu da inceleyin. Apple, tüm sistemin dilini değiştirmeden yerelleştirmeleri sınamak için bu şema ayarlarını belgeliyor. Uygulamayı çalıştırırken yerelleştirmeleri sınama.

Bir sonuç yanlışsa şu sırayı izleyin:

  1. Girdi eksik: Kataloğun uygulama hedefine ait olduğunu doğrulayın ve ilgili şemayı derleyin. Use Compiler to Extract Swift Strings seçeneğinin etkin olduğunu kontrol edin.
  2. Kaynak metin beklenmedik şekilde görünüyor: Okunabilir yedek metni başarı saymadan önce anahtarı, tabloyu, paketi ve çeviriyi kontrol edin.
  3. Yalnızca Interface Builder etiketi farklı: Özel sınıfını, modülünü, yükleme yolunu ve sonraki atamaları kontrol edin.
  4. Yalnızca sonraki değerler farklı: Her iki arayüzün de güncellenmiş model değerlerini aldığını kontrol edin.
  5. Çoğul ifade yanlış: Değişim için seçilen sayısal bağımsız değişkeni ve uygulanabilir her biçimi kontrol edin.

Apple, derleyici çıkarma ayarını belgeliyor ve kaynakta artık bulunmayan çevrilmiş girdilerin Stale olarak işaretli kalabileceğini açıklıyor. Bu durum bir temizleme işaretidir; kaynağın kullanılmadığını kanıtlamaz. Bir girdiyi ve çevirilerini silmeden önce eski arayüz atamasını ve Swift çağrılarını gözden geçirin. String Catalogs'u keşfetme.

Her iki arayüz de aynı bağlamlı iletiyi tek bir tanımdan aldığında, bağımsız değişkenleri korunduğunda ve eski cümle şablonlarını kullanan hiçbir çağrı kalmadığında birleştirme tamamlanmış olur. Gelecekteki ifade değişikliklerinin her iki pencerenin paylaştığı anlamı koruması için sözleşmeyi ve kabul durumlarını yardımcının yanında tutun.

Kaynaklar