Xcode 26 ve sonraki sürümlerde String Catalogs, elle yazılmış yerelleştirme anahtarlarının yerine kullanılabilecek Swift erişicileri oluşturabilir. Bu kılavuz, küçük bir Mac uygulamasının seçim özetini türlenmiş özelliklere ve işlevlere taşır, ardından derleyicinin gerçekte neleri koruduğunu inceler.

Görev özellikle dar kapsamlıdır: bir pencere başlığını ve iki tamsayı sayımı içeren bir özeti görüntülemek. Tüm etiketler ve değerler sentetiktir. Katalog sözleşmesini oluşturacak, SwiftUI'a bağlayacak ve hem derleyici tanılarını hem de görünür çıktıyı doğrulayacaksınız.

Bir yerelleştirme erişicisini derleme zamanında denetlenir yapan nedir?

Apple, Xcode 26'da yerel String Catalog sembolü oluşturma özelliğini kullanıma sundu. Yer tutucusu olmayan bir girdi statik bir özellik; yer tutucuları olan bir girdi ise türlenmiş parametrelere sahip bir işlev oluşturur. Her ikisi de LocalizedStringResource döndürür. Yeni Xcode 26 projelerinde oluşturma varsayılan olarak etkindir; mevcut projelerde derleme ayarının etkinleştirilmesi gerekebilir. Kodla birlikte: Xcode ile yerelleştirmeyi keşfedin

İşe yarayan değişiklik çağrı noktasındadır. Bir dize sabiti, Swift bildirimine başvurmadan arama anahtarını yazabilir. Oluşturulan bir erişici, mevcut olması gereken bir üyeye başvurur ve oluşturulan bir işlev, imzasıyla eşleşen bağımsız değişkenler gerektirir. Belgelenmiş bu mekaniklerin pratik sonucu şudur: yanlış yazılmış bir üye veya uyumsuz bir bağımsız değişken derleyici hatasına yol açar.

Bu korumanın belirli bir kapsamı vardır. Swift, erişicinin var olduğunu ve bağımsız değişkenlerinin uyduğunu denetleyebilir. İfadelerin amaçlanan arayüzü açıklayıp açıklamadığını veya iki geçerli tamsayı bağımsız değişkeninin doğru sayımları temsil edip etmediğini belirleyemez. Erişicileri, mesajlarınıza yönelik denetlenen bir programlama arayüzü olarak ele alın.

Küçük bir Mac uygulaması ve mesaj sözleşmesini ayarlayın

Xcode 26 veya daha yenisini ve macOS SwiftUI uygulama hedefini kullanın. Bu örnekte dağıtım hedefini macOS 15 veya daha yenisi olarak ayarlayın. Temel LocalizedStringResource türü macOS 13'ten itibaren kullanılabilir; örneğin daha yüksek hedefi bir ön koşul tercihidir, bu türün asgari sürümü değildir. Bir kaynak, araması ihtiyaç duyulana kadar ertelenebilen yerelleştirilebilir metni temsil eder. LocalizedStringResource

File > New > File from Template yoluyla bir katalog ekleyin. Resource altından String Catalog seçin, adını Workbench koyun ve uygulama hedefine dahil edin. Apple, her kataloğun bir tabloyu temsil ettiğini belirtir; burada ayrı bir tablo kullanmak örneğin iki mesajını birlikte tutar. Metni dize kataloğuyla yerelleştirme ve çeşitlendirme

Proje düzenleyicisinde Build Settings bölümünü açın, Generate String için filtreleyin ve hedefin etkin yapılandırmasında Generate String Catalog Symbols ayarını Yes yapın. Bu, eski projeler için belgelenmiş anahtardır. Kodunuzda oluşturulan yerelleştirilebilir sembolleri kullanma

Workbench.xcstrings dosyasında İngilizce kaynak yerelleştirmesini seçin. Katalog düzenleyicisinin araç çubuğundaki + düğmesini kullanarak şu iki girdiyi ekleyin. Yorumlar, bağımsız değişkenlerin rolleri de dahil olmak üzere mesajların anlamını tanımlar.

Anahtar İngilizce kaynak değeri Yorum
TITLE Selection overview Seçim özetinin üzerindeki başlık.
SUBTITLE %1$(selectedCount)lld selected; %2$(availableCount)lld available Seçim özeti. selectedCount seçilenlerin sayısıdır; availableCount seçili öğeler dahil kullanılabilir öğelerin toplam sayısıdır.

SUBTITLE için her yer tutucuyu Xcode'un otomatik tamamlama menüsüyle girebilirsiniz: % yazın, tamsayı yer tutucusunu seçin ve adını selectedCount ya da availableCount koyun. Apple, bu biçim belirteçleri için adlandırılmış değişkenleri ve oluşturulan parametreleri belgeliyor. Her girdiyi seçin ve Attributes denetçisindeki Generate Swift Symbol ile Example Usages bölümlerini inceleyin. Kodunuzda oluşturulan yerelleştirilebilir sembolleri kullanma

Amaçlanan sözleşme, bir başlık özelliği ve iki Int değeri kabul eden bir alt başlık işlevidir. Devam etmeden önce denetçide oluşturulan yazımı kontrol edin: Apple, sembol adlarının hem anahtarı hem de değeri kullandığını belirtir. Aşağıdaki örneklerde Apple'ın belgelenmiş büyük harfli anahtar düzenine uygun olarak .Workbench.title ve .Workbench.subtitle(selectedCount:availableCount:) kullanılmıştır. Kodla birlikte: Xcode ile yerelleştirmeyi keşfedin

Bu sözleşme önemli bir ayrımı açıkça ortaya koyar: availableCount seçili öğeleri de kapsar. Bu yorum olmadan bir çağıran, bunu kalan öğelerin sayısı olarak makul biçimde yorumlayabilir. Her iki yorum da tür denetiminden geçer; bu nedenle anlamı belgelemek, erişiciyi kullanışlı kılmanın parçasıdır.

Oluşturulan erişicileri eksiksiz bir pencerede kullanın

Kataloğu oluşturduktan sonra Product > Build seçeneğini belirleyin. Şablon uygulama bildirimini ve içerik görünümünü aşağıdaki programla değiştirin; hedefte tam olarak bir @main bildirimi bulunsun. Bu program için katalog gerekli bir kaynaktır; Swift kodunu tek başına bir dosyaya yapıştırmak erişicileri oluşturmaz.

import Foundation
import SwiftUI

@main
struct SelectionOverviewApp: App {
    var body: some Scene {
        WindowGroup {
            SelectionOverviewView(
                selectedCount: 3,
                availableCount: 12
            )
        }
    }
}

struct SelectionOverviewView: View {
    let selectedCount: Int
    let availableCount: Int

    var body: some View {
        VStack(alignment: .leading, spacing: 12) {
            Text(.Workbench.title)
                .font(.title2)

            Text(
                .Workbench.subtitle(
                    selectedCount: selectedCount,
                    availableCount: availableCount
                )
            )
        }
        .padding(24)
        .frame(minWidth: 360, minHeight: 140)
    }
}

İngilizce kaynak yerelleştirmesi etkin olduğunda örnek girdiler Selection overview ve ardından 3 selected; 12 available göstermelidir. Sayımlar sabittir; böylece seçim yönetimi kodu eklemeden bağımsız değişkenlerin yerleşimini kontrol edebilirsiniz.

Apple, oluşturulan kaynakların Text dahil SwiftUI'da ve Foundation'ın String(localized:) başlatıcısı aracılığıyla kullanılabildiğini belgeliyor. Mevcut bir Mac arayüzü çözümlenmiş bir String gerektiriyorsa, oluşturulan kaynağı bu sınırda dönüştürün. Kodla birlikte: Xcode ile yerelleştirmeyi keşfedin

Örneğin katalog mevcut olduktan sonra aynı uygulama hedefine ekleyebileceğiniz eksiksiz bir yardımcı işlev şöyledir:

import Foundation

func selectionSummary(
    selectedCount: Int,
    availableCount: Int
) -> String {
    String(
        localized: .Workbench.subtitle(
            selectedCount: selectedCount,
            availableCount: availableCount
        )
    )
}

Kendi arayüzünüzden LocalizedStringResource döndürmek, daha sonra aranmak üzere bir kaynağı korur; String döndürmek ise başlatıcı çalıştığında kaynağı çözümler. Alan arayüzün gereksinimine göre seçim yapın. Apple, Foundation belgelerinde bu ertelenmiş ve anlık arama ayrımını açıklıyor. LocalizedStringResource

Örnekler, alınan belgelerle karşılaştırılarak incelendi. Kullanılabilir ortamda Swift yürütülebilir dosyası veya Xcode bulunmadığından burada derlenmediler.

Baştaki nokta ve bağımsız değişken etiketleri neden önemlidir?

Baştaki nokta, Swift'in örtük üye sözdizimidir. Çevresindeki bağlam Swift'in türü çıkarsamasına izin verdiğinde bir tür üyesine erişimi kısaltır. Özel bir dize anahtarı işleci değil, sıradan Swift sözdizimidir. İfadeler — Örtük Üye İfadesi

Oluşturulan yerelleştirme sembollerinde varsayılan Localizable tablosu üyeleri doğrudan sunarken, adlandırılmış bir tablo tablo ad alanı oluşturur. Bu nedenle örnekte üye adından önce .Workbench bulunur. Apple her iki biçimi de belgeliyor. Kodunuzda oluşturulan yerelleştirilebilir sembolleri kullanma

selectedCount: ve availableCount: etiketleri işlev çağrısına aittir. Swift, çağrı noktasında görünen bağımsız değişken etiketlerini işlev içinde kullanılan parametre adlarından ayırır. Bir parametre etiket gerektirdiğinde çağıran bu etiketi sağlamalıdır. İşlevler — İşlev Bağımsız Değişken Etiketleri ve Parametre Adları

Okunaklı etiketler hataları önlemeye yardımcı olur, ancak buradaki iki bağımsız değişken de aynı türdedir. İki tamsayı değerinin yerini değiştirmek geçerli Swift olmaya devam eder. Bu nedenle mesaj sözleşmesi ve görünür çıktı denetimi derleyiciyi tamamlar.

Anlamlarını kaybetmeden mevcut anahtarları taşıyın

Mevcut yerelleştirilebilir dizeler için Apple bir yeniden düzenleme iş akışı sunuyor. String Catalog'da girdileri seçin, Control tuşuna basılı tutarak tıklayın ve Refactor > Convert Strings to Symbols seçeneğini belirleyin. Önizlemeyi inceleyin, gerekirse önerilen sembol veya parametre adlarını ayarlayın ve Convert seçeneğini belirleyin. Kodunuzda oluşturulan yerelleştirilebilir sembolleri kullanma

Önce pencerenin başlığı ve özeti gibi tutarlı bir grubu taşıyın. Önizlemeyi kabul etmeden önce eski mesajla yeni sözleşmeyi karşılaştırın: aynı tabloyu mu kullanıyorlar, aynı arayüz öğesini mi açıklıyorlar ve her yer tutucuya aynı anlamı mı veriyorlar? Anahtar değişikliğinden etkilenen mevcut yerelleştirilmiş değerleri, yeniden düzenlemenin doğruluklarını kanıtladığını varsaymadan inceleyin.

Yeniden düzenlemenin güncellemediği bir çağrı noktası varsa katalog denetçisinin oluşturulan kullanımını kullanın ve bu başvuruyu açıkça değiştirin. Ardından derleyin ve ortaya çıkan metni inceleyin. Çağıranlarını hesaba katmadan eski girdiyi silmekten kaçının.

Yüklü Xcode sürümünüzde yerel oluşturma yoksa bu iş akışı daha yeni bir araç zinciri gerektirir. Apple ayrıca yerelleştirilebilir API'lerden dizelerin kataloglara çıkarılmasını destekliyor ve başlangıç iş akışı olarak çıkarmayı öneriyor. Yerelleştirmeyi yönetmek için desteklenen bir yöntem olmaya devam eder, ancak burada açıklanan oluşturulmuş erişici sözleşmesini tek başına sağlamaz. Kodla birlikte: Xcode ile yerelleştirmeyi keşfedin

Taşımayı küçük bir tanı dizisiyle doğrulayın

Örnek pencerede şu denetimleri kullanın. Bunlar derleyici korumasını, mesaj doğruluğunu ve kaynak tümleştirmesini birbirinden ayırır.

  1. Çalışan bir başlangıç noktası oluşturmak için değişmemiş örneği derleyin.
  2. Başlık üyesinin yazımını geçici olarak bozup derleyin. Var olmayan üye bir derleyici tanısına yol açmalıdır. Eski haline getirin.
  3. Alt başlığın Int gerektirdiği yere geçici olarak String değeri verin. Tür uyuşmazlığını denetlemek için derleyin, ardından tamsayıyı geri koyun.
  4. selectedCount değerini 3, availableCount değerini de 12 olarak ayarlayıp çalıştırın. Sayıların amaçlanan konumlarda olduğunu doğrulayın.
  5. Yalnızca katalog başlık değerini Current selection olarak değiştirin, yeniden derleyin ve görüntülenen başlığı doğrulayın. Oluşturulan imzanın kodunuzun kullandığı imza olarak kaldığını kontrol edin.

Bir üye beklenmedik şekilde eksikse önce katalog girdisinin oluşturulan kullanımını inceleyin. Ardından oluşturma ayarını, kataloğun hedef üyeliğini ve tablo adını kontrol edin. Derleyici tanısı başarısız bir başvuruyu gösterir; bu kontroller yazım hatasını oluşturulmuş bildirimin kullanılamamasından ayırmaya yardımcı olur.

Son olarak gerçek arayüzü sınayın. Apple'ın belgelenmiş yolu Product > Scheme > Edit Scheme, ardından Run > Options bölümüdür; burada çalıştırmadan önce App Language seçebilirsiniz. Projenizin desteklediği yerelleştirmeler için tekrarlayın. Uygulamanızı çalıştırırken yerelleştirmeleri sınama

Erken bir düzen denetimi için Xcode, yerelleştirilebilir metni genişleterek boyutlandırma sorunlarını ortaya çıkaran Double-Length Pseudolanguage seçeneğini de sunar. Özeti dar bir pencere genişliğinde inceleyin; başarılı derleme metnin sığıp sığmadığını göstermez. Yerelleştirmeleri sınama

Tamamlanmış bir taşıma, her çağrı noktasına gerçek bir Swift üyesi verir, her değişkene belgelenmiş bir rol kazandırır ve amaçlanan katalog girdisine giden denetlenmiş yolu korur. Derleyici denetimlerini ve pencere denetimlerini birlikte kullanın: ilki erişici sözleşmesini doğrular, ikincisi ise okuyucunun amaçlanan mesajı gördüğünü teyit eder.

Kaynaklar