Xcode’da bir String Catalog anahtarını yeniden adlandırmak için kaynak mesajı ayrı olarak koruyun, kod referanslarını güncelleyin ve mevcut tüm çevirileri ve varyantları doğrulayın. Çıkarılan dizeler için Xcode 26 bir dönüştürme refaktörü sunar; yalnızca arama anahtarını değiştirmek yeterli değildir.

Bu kılavuz, mevcut bir .xcstrings kataloğuna sahip SwiftUI Mac uygulamasını sürdüren kişiler içindir. Amaç, görüntülenen ifadeyi ve çevirileri korurken mesaj biçimindeki anahtarları anlamlı tanımlayıcılarla değiştirmektir. Apple aşağıdaki API’leri ve dönüştürme iş akışını belgeliyor, ancak gelişigüzel bir anahtar düzenlemesinin her çeviriyi otomatik olarak aktaracağını garanti etmiyor.

Bir anahtar değiştiğinde neler aynı kalmalı?

Yerelleştirilebilir bir mesaj yalnızca bir tanımlayıcıdan ibaret değildir. Apple; anahtarını, varsayılan değerini, yorumunu ve dize tablosunu ayrı bileşenler olarak tanımlar. Anahtar, mesajı çalışma zamanında tanımlar; varsayılan değer kaynak ifadeyi sağlar. Katalog, bir tablonun çevirilerini ve üst verilerini tutar. Yeniden adlandırmayı, bu mesaj sözleşmesinde eşgüdümlü bir değişiklik olarak ele alın. String Catalog’ları keşfedin

Düzenlemeden önce, etkilenen her girdi için aşağıdakileri kaydedin. Bu yapay örnekler yeniden adlandırmayı gösterir; ölçülmüş sonuçlar değildir.

Bileşen Önce Hedeflenen sonuç
Arama anahtarı Open collection collection.open
Kaynak mesaj Open collection Değişmeden kalır
Tablo Localizable Değişmeden kalır
Paket Ana uygulama paketi Değişmeden kalır
Çevirmen bağlamı Seçili koleksiyonu açan düğme Korunur
Mevcut çeviriler Her yerel ayardaki geçerli değerler Korunur
Sayı bağımsız değişkenleri varsa Tamsayı sayısı Türü ve anlamı aynı kalır
Çoğul veya aygıt varyantları Mevcut dallar Korunur

Bu kaydı karşılaştırma yardımı olarak kullanın. Yalnızca başarılı bir derleme, çevirilerin korunduğunu kanıtlamaz: arama başarısız olduğunda uygulama yine varsayılan mesajı görüntüleyebilir. SwiftUI, katalogda eşleşme bulunmadığında yerelleştirilmiş bir anahtarın doğrudan görüntülenebileceğini belgeliyor. Anlamlı bir anahtarla bu durum, arayüzde collection.open gibi bir tanımlayıcının görünmesine yol açabilir. Görünümleri yerelleştirmeye hazırlama

Kataloğu düzenlemeden önce kaynağı bulun

Xcode’un Proje gezgininde mevcut kataloğu açın. Editor > Assistant seçeneğini belirleyin, ardından kaynağını incelemek için girdiyi seçin. Apple ayrıca referansları bulmanın yolları olarak anahtarın yanındaki oku ve Attributes denetçisindeki örnek kullanımları belgeliyor. Çıkarılan dizeler için kaynak değişikliklerinden sonra kataloğu eşitlemek üzere Product > Build seçeneğini belirleyin. Dize kataloğuyla metni yerelleştirme ve varyasyonlarını belirleme

Girdinin koddan çıkarılıp çıkarılmadığını veya elle yönetilip yönetilmediğini kontrol edin. Apple, çıkarılan mesajların kaynağının kaynak kod olduğunu açıklıyor: derlemeler kaynak değerlerini eşitler. Çıkarımda artık bulunmayan çevrilmiş bir girdi Stale olarak kalır; çevrilmemiş bir girdi ise kaldırılabilir. Elle yönetilen girdiler çıkarım tarafından güncellenmez veya kaldırılmaz. Bu nedenle, yeni bir karşılığı göründü diye eski çevrilmiş girdiyi silmeyin. String Catalog’ları keşfedin

İlerlemeden önce geri alınabilir bir kontrol noktası oluşturun ve sonrasında etkilenen girdiyi bu noktayla karşılaştırın. Eksik bir çevirinin olası nedenlerini azaltmak için bu işlem boyunca tabloyu ve paketi değiştirmeyin. Apple’ın yerelleştirme API’leri, mesajın nerede bulunacağını belirledikleri için tablo ve paket bilgilerini kabul eder. Uygulamanızın metnini çeviriye hazırlama

Çıkarılan dizeler için Xcode’un dönüştürme refaktörünü kullanın

Xcode 26 veya sonraki sürümleri kullanan projelerde, mevcut çıkarılmış girdiyi oluşturulan yerelleştirilebilir bir simgeye dönüştürmeyi değerlendirin. Apple bu iş akışını Xcode 26’da kullanıma sundu ve dönüştürme sırasında bir anahtarın anlamlı bir adla değiştirilmesini gösteriyor. Bu, mesajın tanımlanma ve referans verilme biçimini birlikte değiştirmek için belgelenmiş bir yoldur. Kodla birlikte: Xcode’da yerelleştirmeyi keşfedin

  1. Derleme ayarlarında, mevcut projenin etkinleştirmesi gerekiyorsa Generate String Catalog Symbols seçeneğinin Yes olarak ayarlandığını kontrol edin.
  2. Katalog düzenleyicisinde mevcut anahtarı seçin, Control tuşuna basılı tutarak tıklayın ve Refactor > Convert Strings to Symbols seçeneğini belirleyin.
  3. Katalog anahtarındaki değişikliği ve etkilenen kaynak konumlarını gösteren önizlemeyi inceleyin.
  4. Dönüştürme arayüzünde önerilen anlamlı adı ve uygunsa bağımsız değişken adlarını düzenleyin.
  5. Vurgulanan önizlemeyi kullanarak mevcut kodu değiştirilmiş kodla karşılaştırın, ardından Convert düğmesine tıklayın.
  6. Derleme yapın ve çeviriler ile varyantlar da dahil olmak üzere ortaya çıkan girdiyi kontrol noktanızla karşılaştırın.

Apple bu dönüştürme denetimlerini belgeliyor ve Attributes denetçisinde oluşturulan kullanım örneklerini gösteriyor. İstediğiniz katalog anahtarındaki noktalama işaretlerinden bir Swift tanımlayıcısı tahmin etmek yerine bu örnekleri kullanın. Oluşturulan simgeler katalog bilgilerine bağlıdır ve varsayılan olmayan tablolar bir tablo ad alanı kullanır. Kodunuzda oluşturulan yerelleştirilebilir simgeleri kullanma

Bu refaktör özellikle çıkarılmış dizelerden oluşturulan simgelere geçiş içindir. Alıntılanan belgeler, elle yönetilen her girdi veya her harici referans için evrensel bir yeniden adlandırma işlemi olduğunu göstermiyor. Önizlemede gerekli bir referans yoksa önce bunu ayrıca ele alın, sonra eski anahtarı kaldırın.

Anahtarları ve varsayılanları kodda tutmayı tercih ediyorsanız çıkarımı sürdürün

Kod odaklı çıkarımı da sürdürebilirsiniz. Apple, String(localized:defaultValue:...) aracılığıyla arama anahtarlarıyla kaynak mesajların ayrı olmasını açıkça destekliyor: ilk bağımsız değişken anahtarı, defaultValue ise kaynak dizeyi sağlar. Örneğin, anlamlı bir anahtarın varsayılan mesajı Open collection olarak kalabilir. Uygulamanızın metnini çeviriye hazırlama

Aşağıdaki eksiksiz uygulama kaynağı, bir statik etiket ve bir tamsayı sayısı için bu örüntüyü gösterir. macOS 12 veya sonraki bir dağıtım hedefi olan bir macOS SwiftUI uygulama hedefi kullanın ve ikinci bir @main bildirimi eklemek yerine mevcut uygulama giriş kaynağını değiştirin. Uygulama hedefine Localizable.xcstrings ekleyin. Örnek Apple API’leriyle karşılaştırılarak incelendi; burada Swift araç zinciri bulunmadığından derlenmedi.

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

Burada String(localized:...), ortaya çıkan dize görüntülenmeden önce yerelleştirilmiş metni çözümler. Text(verbatim:) bu görüntüleme adımını açık hale getirir. Apple, dizenin hemen yerelleştirilmesiyle ertelenebilen bir aramayı temsil eden LocalizedStringResource türünü birbirinden ayırır. Çözümlenmemiş mesajları görünümler arasında aktaran yeniden kullanılabilir arayüzlerde Apple, LocalizedStringResource gibi yerelleştirilebilir bir tür öneriyor. LocalizedStringResource, Uygulamanızın metnini çeviriye hazırlama

Bu yaklaşımı kullanarak mevcut bir mesajı taşırken hedef girdiyi oluşturmak veya güncellemek için derleme yapın, ardından önceki girdiyi silmeden mevcut çevirileri aktarın. Apple, bir yerelleştirme seçip karşılık gelen dil sütununu düzenleyerek çevirilerin doğrudan girilebileceğini belgeliyor. Varyasyonlu bir mesaj için yalnızca üst düzey metni kopyalamak yerine ilgili her dalı koruyun. Bu aşamalı aktarım, belgelenmiş düzenleme araçlarından türetilen pratik bir taşıma yöntemidir; otomatik yeniden adlandırma garantisi değildir. Dize kataloğuyla metni yerelleştirme ve varyasyonlarını belirleme

Çıkarım ile çalışma zamanı biçimlendirmesi arasındaki fark nedir?

Çıkarım geliştirme sırasında gerçekleşir: Xcode, desteklenen yerelleştirilebilir ifadeleri keşfeder ve kataloğu günceller. Çalışma zamanı biçimlendirmesi, uygulama mesajı çözümlerken ve değerleri eklerken gerçekleşir. Örnek sayı olan 7, çalışma zamanı bağımsız değişkenidir; sabit anahtarın bir parçası haline gelmemelidir.

Tamsayı enterpolasyonunu yerelleştirilebilir ifadenin içinde tutun. Apple’ın String.LocalizationValue türü enterpolasyonu destekler ve gelişigüzel tanımlayıcılar isteyen geliştiricileri statik anahtarla ayrı bir defaultValue kullanan başlatıcılara yönlendirir. Önce sıradan, görüntülenmeye hazır bir dize oluşturmak; bu yerelleştirilebilir mesajı ve bağımsız değişkenlerini korumakla aynı şey değildir. String.LocalizationValue

Dilbilgisine uygun sayım mesajları için çıkarılmış sayı girdisini seçin, Control tuşuna basılı tutarak tıklayın ve Vary by Plural seçeneğini belirleyin. Kaynak varyantlarını ve her mevcut yerelleştirmenin gerekli varyantlarını tamamlayın. İngilizce bir kaynak için Apple, One varyantında %lld item, Other varyantında %lld items kullanımını örnekliyor. Yalnızca enterpolasyon eklemek bu varyantları tamamlamaz. Dize kataloğuyla metni yerelleştirme ve varyasyonlarını belirleme

Yeniden adlandırma sırasında bağımsız değişken türlerini, konumlarını ve anlamlarını koruyun. Eski mesaj bir tamsayı sayısı içeriyorsa bunu önceden biçimlendirilmiş bir dizeyle değiştirmek biçimlendirme sözleşmesini de değiştirir. Oluşturulan simgelerde Xcode, biçim belirteçleri içeren mesajlar için türlenmiş parametreleri olan işlevler oluşturur; dönüştürme sırasında bu imzaları inceleyin. Kodunuzda oluşturulan yerelleştirilebilir simgeleri kullanma

Eski girdiyi kaldırmadan önce korunduğunu doğrulayın

Tamamlama denetimi olarak aşağıdaki kontrolleri kullanın. Bunlar, katalog sorununu arama veya biçimlendirme sorunundan ayırır.

Kontrol Beklenen sonuç Başarısız olursa inceleyin
Kaynak ifade Kontrol noktasıyla eşleşir Eksik veya değiştirilmiş varsayılan değer
Mevcut çeviriler Önceki her değer yeni anahtar altında kullanılabilir durumda kalır Eksik aktarım veya yanlış hedef
Varyant yapısı Önceki tüm çoğul ve aygıt dalları korunur Yalnızca üst düzey bir değer kopyalanmış
Çalışma zamanı etiketi Amaçlanan mesajı görüntüler Anahtar, tablo, paket veya yerelleştirme uyuşmazlığı
Yapay sayılar 0, 1, 7 Değerler doğru şekilde eklenir ve gerekli çoğul dalları çalışır Bağımsız değişken veya varyant uyuşmazlığı
Eski referanslar Gerekli hiçbir kullanım kalmamıştır Taşıma eksik

Mevcut bir yerelleştirmede Mac uygulamasını test etmek için Product > Scheme > Edit Scheme seçeneğini belirleyin, Run’ı seçin, Options’ı açın ve bir App Language seçin. İletişim kutusunu kapatıp Mac hedefini çalıştırın. Yeniden adlandırmadan etkilenen yerelleştirmeler için bunu tekrarlayın ve gerçek etiketi ve sayı mesajını kontrol edin. Apple, şema tabanlı bu test iş akışını belgeliyor. Uygulamanızı çalıştırırken yerelleştirmeleri test etme

Yeni anahtar görünüyor ancak çevirisi boşsa önceki girdiye dönüp eksik içeriği aktarın. Tanımlayıcı ekranda görünüyorsa arama girdilerini inceleyin. Yalnızca sayılar başarısız oluyorsa enterpolasyonu ve varyantları inceleyin. İçeriği hesaba katıp gerekli referansları taşıdıktan sonra eski girdiyi kaldırın. Tamamlanan değişiklik tanımlayıcıyı değiştirmeli; mesajı, bağımsız değişkenlerini ve okuyucuların aldığı çevirileri korumalıdır.

Kaynaklar