Framework’lerin sahip olduğu panellere sahip bir Mac uygulaması için yedeklemeyi iki düzeyde tanımlayın: her paketin hangi dili seçtiği ve arama başarısız olduğunda her mesajın ne döndürdüğü. Geliştirme yerelleştirmesi olarak İngilizceyi ve sahip olduğunuz mesajlar için açık İngilizce varsayılanları kullanın.

Bu kılavuz, uygulamanın sahip olduğu Workspace etiketi ve framework’ün sahip olduğu Panel ready etiketini içeren basit bir masaüstü penceresi için bu sözleşmeyi uygular. Etiketler örnek amaçlıdır. Amaç, çeviriler mevcut olduğunda olağan yerelleştirmeyi korurken bir dil veya çeviri eksik olduğunda bu mesajları okunabilir tutmaktır.

Yedekleme sözleşmesi ne vaat etmeli?

Uygulamanın ve framework’ün sahip olduğu mesajlar için şu sözleşmeyi benimseyin: sistemin dil eşleştirmesi yoluyla seçilen mevcut bir yerelleştirmeyi kullanın; tercih edilen yerelleştirmelerden hiçbiri eşleşmezse geliştirme yerelleştirmesi olarak İngilizceyi kullanın; dize araması başarısız olursa mesajın açık İngilizce varsayılanını döndürün. Her mesaj, ait olduğu paketi ve dize tablosunu belirtmelidir.

Dil seçimi, kullanıcının tercih ettiği dilleri ve kullanılabilir yerelleştirmeleri dikkate alır. İlk tercih edilen dilin bulunmaması, İngilizcenin hemen gösterileceği anlamına gelmez: önce tercih edilen başka bir dil eşleşebilir. Apple’ın arşivlenmiş paket kılavuzu bu seçim sırasını, tercih edilen dillerden hiçbiri eşleşmediğinde geliştirme yerelleştirmesinin kullanılmasını izleyen adımlarla açıklar. Güncel belgeler CFBundleDevelopmentRegion değerini paketin yedek dil tanımlayıcısı olarak tanımlar. Bir Paketin İçeriğine Erişme, CFBundleDevelopmentRegion.

Beklenen sonuçları tanımlarken aşağıdaki karar tablosunu kullanın. Her eksik çeviriyi aynı durum gibi ele almak yerine kaynak seçimini mesaj aramasından ayırır.

Durum Sahip olduğunuz mesajlar için sözleşme Denetlenecekler
Tercih edilen bir dil için kullanılabilir çeviri var Bu çeviriyi gösterin Paket, tablo ve anahtar
İlk tercih edilen dil kullanılamıyor, ancak tercih edilen başka bir dil eşleşiyor Sistem dil eşleştirmesinin kullanılabilir yerelleştirmeyi seçmesine izin verin Tercih sırası ve dağıtılan kaynaklar
Tercih edilen yerelleştirmelerin hiçbiri eşleşmiyor Paketin İngilizce geliştirme kaynaklarını kullanın Geliştirme dili ve İngilizce kaynaklar
Seçilen arama mesajı bulamıyor Mesajın açık İngilizce varsayılanını döndürün Mesajın defaultValue değeri
Framework araması yanlışlıkla uygulama paketini hedefliyor Paket bağımsız değişkenini düzeltin Kaynak sahipliği
Çeviri var ancak içeriği uygun değil Çeviriyi düzeltin Katalog içeriği ve inceleme

Tablo, Apple’ın kaynak seçimi kurallarını Swift başlatıcısının belgelenmiş varsayılan değer davranışıyla birleştirir. Bu, String Catalogs içindeki ayrı bir yedekleme özelliği değil, söz konusu API’lerden çıkarılan bir uygulama politikasıdır. Uygun olmayan içerik taşıyan başarılı bir arama, başlatıcının varsayılanı kullanması için belgelenen koşulu karşılamaz: başarısız arama. String.init(localized:defaultValue:table:bundle:locale:comment:).

Her hedefte İngilizce kaynakları yapılandırın

Bu örnekte güncel bir Xcode kurulumu, macOS 13 veya sonraki sürümleri hedefleyen macOS SwiftUI uygulaması ve PanelKit adlı gömülü dinamik Swift framework hedefi kullanın. Framework’ü uygulamaya bağlayıp gömün. Bunlar örnek proje ön koşullarıdır; framework adı mevcut bir ürünü belirtmez.

Her iki hedef için de geliştirme dili olarak İngilizceyi ayarlayın ve derlenen her paketin CFBundleDevelopmentRegion değerinin en olarak çözümlendiğini doğrulayın. Her iki hedefe de karşılık gelen İngilizce kaynakları ekleyin. Geliştirme dili tanımlayıcısı yedekleme dilini belirtir; eksik mesaj içeriğini sağlamaz. Apple, en değerini İngilizce dil tanımlayıcısı olarak belgeler. CFBundleDevelopmentRegion.

Her hedef için ayrı bir Localizable.xcstrings kataloğu oluşturun. Xcode’da File > New > File from Template seçeneğini belirleyin, String Catalog şablonunu seçin ve adını Localizable koyun. Kataloglardan birini uygulama hedefine, diğerini framework hedefine atayın. Kaynak sahipliğini ayrı tutmak, her aramayı bağımsız olarak doğrulamayı sağlar. Apple, katalog oluşturma iş akışını belgeler ve birden fazla kataloğu destekler. Bir dize kataloğuyla metni yerelleştirme ve çeşitlendirme.

Aşağıdaki kodu ekledikten sonra Product > Build seçeneğini belirleyin. Xcode, tanınan yerelleştirilebilir çağrıları kataloglara çıkarır. workspace.title değerinin uygulama kataloğunda, panel.ready değerinin ise framework kataloğunda amaçlanan İngilizce kaynak değerleriyle göründüğünü doğrulayın. Katalog kenar çubuğundaki ekleme düğmesini kullanarak desteklenen dilleri ekleyin ve ilgili mesajların çevirilerini girin. Bir dize kataloğuyla metni yerelleştirme ve çeşitlendirme.

Katalog bütünlüğü ile çalışma zamanındaki arama doğruluğu ayrı ayrı denetlenmelidir. Framework kataloğundaki çevrilmiş bir girdi, uygulama paketinde arama yapan bir çağrıya yardımcı olmaz. Apple, ana paket dışındaki dizeleri yükleyen kodun bu hedefle ilişkili paketi geçirmesi gerektiğini özellikle belirtir. Uygulamanızın metnini çeviriye hazırlama.

Her mesaj için paket, anahtar, tablo ve varsayılan belirleyin

Kararlı, örnek amaçlı anahtarlar ve okunabilir İngilizce varsayılanlar kullanın. defaultValue kabul eden Swift başlatıcısı, gösterilen kaynak metninden farklı bir anahtarı destekler. Paketten yerelleştirilmiş dize aranamadığında varsayılan değer döndürülür. table parametresi dize tablosunu seçer; bu parametre atlanırsa Localizable kullanılır. String.init(localized:defaultValue:table:bundle:locale:comment:).

Framework mesajlarını framework’e koyun

Bu Swift kaynak dosyasının tamamını dinamik PanelKit framework hedefine ekleyin. İşaretleyici sınıf bu hedefte tanımlandığı için Bundle(for:) paketi belirler. Apple, sınıf tabanlı bu yaklaşımın güncel #bundle makrosuna bir alternatif olduğunu belgeler. Uygulamanızın metnini çeviriye hazırlama.

import Foundation

private final class PanelBundleAnchor: NSObject {}

public enum PanelText {
    public static var resourceBundle: Bundle {
        Bundle(for: PanelBundleAnchor.self)
    }

    public static var ready: String {
        String(
            localized: "panel.ready",
            defaultValue: "Panel ready",
            table: "Localizable",
            bundle: resourceBundle,
            comment: "Status label above the framework panel."
        )
    }
}

Framework, mesajını uygulamaya bir String döndürmeden önce çözümler. Böylece net bir sahiplik sınırı oluşur: anahtarı, kaynak metni, tabloyu ve kaynak paketini framework denetler. Uygulama, görüntülenecek metni alır.

Uygulama ve framework mesajlarını birlikte gösterin

Oluşturulan uygulama giriş noktası dosyasını bu eksiksiz örnekle değiştirin. Bağlı framework modülünün PanelKit olarak adlandırıldığını ve önceki dosyayı içerdiğini varsayar. Uygulama hedefinde yalnızca tek bir uygulama giriş noktası bırakın.

import Foundation
import SwiftUI
import PanelKit

@main
struct FallbackDemoApp: App {
    var body: some Scene {
        WindowGroup {
            VStack(alignment: .leading, spacing: 12) {
                Text(verbatim: String(
                    localized: "workspace.title",
                    defaultValue: "Workspace",
                    table: "Localizable",
                    bundle: .main,
                    comment: "Heading for the main workspace."
                ))

                Text(verbatim: PanelText.ready)
            }
            .padding(24)
        }
    }
}

Uygulama araması açıkça .main kullanır; framework araması kendi kaynak paketini kullanır. Her ikisi de İngilizce varsayılanlar sağlar. Bu, Apple’ın belgelenmiş paket seçimi ve varsayılan değer parametrelerine uygundur. Hedef yapılandırmasının tamamını doğrulamak için projeyi Xcode’da derleyip çalıştırın; bu örnekler burada çalıştırılmamıştır. String.init(localized:defaultValue:table:bundle:locale:comment:).

Bundle.localizedString(forKey:value:table:) kullanan mevcut bir uygulamada, eksik anahtar durumunda okunabilir bir sonuç istiyorsanız boş olmayan ve okunabilir bir value değeri sağlayın. Apple, value yoksa veya boşsa eksik anahtarın kendisinin döndürüldüğünü, boş değilse value değerinin döndürüldüğünü belgeler. Bu nedenle panel.ready gibi bir anahtar için, bu tanımlayıcının kullanıcıya gösterilmesi mesaj sözleşmesini ihlal edecekse açık bir yedek değer gerekir. localizedString(forKey:value:table:).

Framework’lerin farklı diller seçip seçemeyeceğine karar verin

Doğru paketi geçirmek, nerede arama yapılacağını belirler. Karma yerelleştirme yapılandırması, yerelleştirme seçiminin kapsayıcı uygulamayla ilişkisini etkiler. Apple, framework’lerden yerelleştirilmiş dizeler almak için Localized resources can be mixed olarak görüntülenen Boolean CFBundleAllowMixedLocalizations anahtarını sunar. CFBundleAllowMixedLocalizations.

Swift Forums açıklamasına göre bu anahtarı uygulamanın Info.plist dosyasında etkinleştirmek, diğer paketlerin ana uygulamanın desteklediklerinin dışında yerelleştirmeler seçmesine izin verir. Bu tercih açık değilse seçimleri ana paket sınırlar. Bu, Apple’ın güncel anahtar başvuru belgesinin yanında yararlı olan daha eski bir açıklayıcı tartışmadır. Swift paket yöneticisi yerelleştirmesi.

Örnek pencere için uygulama ile framework’te desteklenen dillerin kapsamını eşleştirin ve her ikisinde de İngilizce geliştirme kaynakları bulundurun. İlk sözleşmenin dışında framework’ün bağımsız dil seçmesine izin vermeyin. Bunun yerine framework’ün ek çevirileri kullanmasını istiyorsanız uygulamanın CFBundleAllowMixedLocalizations Boolean değerini YES olarak ayarlayın ve bu yapılandırmayı açıkça test edin. Swift paket yöneticisi yerelleştirmesi.

Bu anahtarı etkinleştirmek bir çeviri veya eksik mesaj varsayılanı sağlamaz. Bu sorumluluklar kaynak dosyalarına ve arama çağrılarına aittir. Benzer şekilde, kendi çağrınıza verdiğiniz varsayılan değer o çağrının başarısız arama sonucunu belirler; her sistem denetimi veya framework mesajı için evrensel bir İngilizce yedek oluşturmaz.

Çeviri dili anahtarı olarak bu String başlatıcısının locale bağımsız değişkenini kullanmayın. Apple, bunun sayı gibi yerelleştirilmiş değerlerin yerelleştirmesini denetlediğini ve yerelleştirilmiş dizenin aranmasında kullanılan yerel ayarı değiştirmediğini açıkça belgeler. Bu görev için desteklenen dil yapılandırmasını ve test denetimlerini kullanın. String.init(localized:defaultValue:table:bundle:locale:comment:).

Eksik dilleri ve eksik mesajları ayrı ayrı test edin

Yerelleştirme denetimlerini Product > Scheme > Edit Scheme üzerinden çalıştırın. Run seçeneğini belirleyin, Options bölümünü açın, bir App Language seçin, iletişim kutusunu kapatın ve Mac uygulamasını yeniden çalıştırın. Apple, sistemin tüm ayarlarını değiştirmeden yerelleştirmeleri denemek için bu iş akışını belgeler. Yalnızca dille ilgili bir sorunu incelerken bölge seçimini değiştirmeyin. Uygulamanızı çalıştırırken yerelleştirmeleri test etme.

Projeye özgü bir tanılama yardımı olarak aşağıdaki test matrisini kullanın. Paket yönlendirmesini denetlemek için desteklenen ve kaynak dili olmayan bir yerelleştirmede App translation sample ve Framework translation sample gibi farklı İngilizce test işaretçileri kullanın. Bunlar tanılama içeriğidir; çeviri veya dil tanımlayıcısı değildir.

  1. Kaynak davranışını doğrulayın. İngilizce seçiliyken çalıştırın. Workspace ve Panel ready bekleyin.
  2. Çevrilmiş kaynakların yönlendirilmesini doğrulayın. Desteklenen test yerelleştirmesini seçin. İki sahip kataloğundaki farklı işaretçileri bekleyin.
  3. Eksik mesaj varsayılanını doğrulayın. Geçici bir test düzenlemesinde framework arama anahtarını panel.ready.probe olarak değiştirin, defaultValue değerini olduğu gibi bırakın ve bu yoklama girdisinin test kataloğuna eklenmesini önleyin. Arama başarısız olduğunda Panel ready bekleyin. Ardından özgün anahtarı geri yükleyin.
  4. Desteklenmeyen dil seçimini doğrulayın. Desteklenen hiçbir dille eşleşmeyen bir tercih listesini deneyin. Her iki sahip paketin de İngilizce geliştirme kaynaklarını kullandığını denetleyin. Farklı bir sonuç vermesi beklenen, desteklenmeyen ilk tercihin ardından desteklenen bir tercihin geldiği durumu da test edin.
  5. Etkinse karma yerelleştirmeyi doğrulayın. Yalnızca framework’te bulunan bir dili deneyin. Amaçlanan davranışı kaydedin ve uygulamanın karma yerelleştirme ayarını buna göre test edin.

Üçüncü denetim başarısız aramayı, dördüncü denetim ise dil eşleştirmesini yalıtır. Çevrilmemiş bir katalog satırını test etmek bu koşulları birbirine karıştırabilir; çünkü ortaya çıkan kaynak yapılandırması da aramayı etkiler. Beklenen eksik anahtar sonucu Swift başlatıcısından, tercih edilen dilin seçimi ise paket kurallarından kaynaklanır. String.init(localized:defaultValue:table:bundle:locale:comment:), Bir Paketin İçeriğine Erişme.

Sonuçlar farklıysa kaynak sahibinin gerçek paketini inceleyin. developmentLocalization, CFBundleDevelopmentRegion değerine karşılık gelen değeri bildirir; preferredLocalizations ise dil tercihlerine göre sıralanmış kullanılabilir yerelleştirmeleri bildirir. Bu özellikleri Bundle.main ve PanelText.resourceBundle üzerinde karşılaştırın. Yapılandırma sorunlarını tanılamaya yardımcı olurlar, ancak her aramanın son kontrolü gösterilen mesajlardır. developmentLocalization, preferredLocalizations.

İyi bir yedekleme sözleşmesi her sonucu açıklanabilir kılar: seçilen dil paket eşleştirmesinden, mesaj kendi tablosundan gelir ve başarısız arama açık, okunabilir bir varsayılan döndürür. Bu kuralları sahip olduğunuz her uygulama ve framework mesajına uygulayın, ardından kullanıcıların gördüğü masaüstü penceresinde hepsini birlikte doğrulayın.

Kaynaklar