Bir framework’ün yerelleştirme anahtarını çözümlemek için hem kaynak paketini hem de dizeler tablosunu belirtin. Bu kılavuz, framework’e ait bir etiketin Mac uygulamasında doğru görünmesini ve sonucun varsayılan metinden değil tablodan geldiğinin doğrulanmasını gösterir.

Görev özellikle küçük tutulmuştur: Bir framework’ün Panel.xcstrings kataloğundaki sentetik Open panel etiketini görüntülemek. Xcode’da bir Mac uygulaması projesine ve denetiminizde olan bir framework hedefinə ihtiyacınız olacak. Ana örnek Xcode 26 veya sonrasını kullanır ve macOS 12 veya sonrasını hedefler; Apple, yerelleştirilmiş dize başlatıcısının macOS 12’den itibaren kullanılabildiğini belgeliyor. Swift başlatıcı belgeleri.

Kodu değiştirmeden önce paketi, tabloyu ve anahtarı belirleyin

Yerelleştirilmiş bir iletiyi üç açık koordinatı olan bir arama olarak ele alın. Paket kaynak sahibini, tablo bu paketteki bir dize grubunu, anahtar ise tablodaki bir girdiyi belirtir. Framework’ler ve uygulama hedeflerinin her biri dize kaynakları içerebildiğinden Apple’ın yerelleştirme API’leri paketi ve tabloyu ayrı ayrı sunar. Uygulamanızın metnini çeviriye hazırlama.

Bu örnek için kataloğu açmadan önce aşağıdaki sözleşmeyi not edin. Bunlar açıklayıcı adlardır; Apple’ın zorunlu kıldığı adlar değildir.

Bölüm Örnek değer Amaç
Kaynak sahibi Framework hedefiniz Kataloğu içerir
Katalog dosyası Panel.xcstrings Tablonun kaynak metnini ve çevirilerini saklar
Tablo bağımsız değişkeni Panel Uzantısı olmadan bu kataloğu seçer
Anahtar PANEL_OPEN_ACTION İletiyi tanımlar
İngilizce kaynak değeri Open panel Okunabilir arayüz metni sağlar
Açıklama Paneli açan eylemin etiketi. İletinin kullanımını açıklar

table: \"Panel\" iletmek, Panel.xcstrings tarafından temsil edilen tabloyu seçer. Tablo belirtilmezse Localizable seçilir. Benzer şekilde, paket belirtilmezse dize başlatıcısı ana uygulama paketinde arama yapar. Bu nedenle framework kataloğundaki eşleşen bir anahtar için framework’ün paketinin yanı sıra doğru tablo da gerekir. Swift yerelleştirilmiş dize parametreleri.

Bu, yararlı bir tanılama sırası sağlar: önce sahibi, sonra tabloyu, son olarak girdiyi doğrulayın. İletinin bir framework’e ait olduğu durumda uygulamanın kaynaklarına yöneltilmiş bir arama, anahtarın farklı yazımlarını arayarak düzeltilemez.

Dize kataloğunu framework hedefine ekleyin

Xcode’da File > New > File from Template yolunu izleyin, platformu seçin, string için filtre uygulayın ve String Catalog seçeneğini belirleyin. Dosyayı Panel olarak adlandırın. Kataloğun, kendisine başvuracak framework kaynak koduyla birlikte framework hedefine ait olduğundan emin olun. Apple’ın katalog iş akışı özel katalog adlarına izin verir ve framework gösteriminde katalog framework hedefi içinde oluşturulur. Dize kataloğuyla metni yerelleştirme ve çeşitlendirme, Apple’ın framework yerelleştirme gösterimi.

Örnekte, görüntülenen ifadeyi anahtar olarak kullanmak yerine anlamsal bir anahtar kullanılır. Tanımlayıcı olarak PANEL_OPEN_ACTION, varsayılan değer olarak da Open panel kullanıldığında kod her iki parçayı da açıkça belirtir. Apple, statik bir anahtar ile ayrı bir varsayılan yerelleştirme değerini kabul eden başlatıcı aracılığıyla bu düzeni destekler. Swift statik anahtar başlatıcısı.

Aşağıdaki kaynağı ekledikten sonra framework hedefini derleyin. Xcode, derlemeler sırasında yerelleştirilebilir API çağrılarını bulur ve ilgili katalogları günceller. Panel.xcstrings dosyasını açıp PANEL_OPEN_ACTION, İngilizce kaynak değeri Open panel ve açıklamanın bulunduğunu doğrulayın. Girdi eksikse kaynağın hedef üyeliğini ve bu kaynağı içeren hedefin derlenip derlenmediğini kontrol edin. Apple ayrıca katalog girdisiyle ilişkili kodu incelemek için Editor > Assistant seçeneğini sunar. Dize kataloğunu doldurma ve inceleme.

İletiyi framework içinde çözümleyin

Bu tam kaynak dosyasını framework hedefine yerleştirin. Dosya, yerelleştirilmiş dizeyi ve kapsayıcı Mac uygulamasının görüntüleyebileceği küçük bir SwiftUI etiketi tanımlar. Ayrıca sonraki bölümde kullanılacak bir tanılama yöntemi içerir. Kod, Apple’ın belgelenmiş imzalarına göre kontrol edildi; Swift derleyicisi mevcut olmadığından burada çalıştırılmadı.

import Foundation
import SwiftUI

public enum PanelMessages {
    public static var openPanel: String {
        String(
            localized: "PANEL_OPEN_ACTION",
            defaultValue: "Open panel",
            table: "Panel",
            bundle: #bundle,
            comment: "Label for the action that opens the panel."
        )
    }

    public static func lookupReport() -> String {
        let missingMarker = "__PANEL_LOOKUP_MISSING__"
        let result = #bundle.localizedString(
            forKey: "PANEL_OPEN_ACTION",
            value: missingMarker,
            table: "Panel"
        )

        if result == missingMarker {
            return "No entry resolved from the selected bundle and table."
        }

        return "Resolved table value: \(result)"
    }
}

public struct PanelActionLabel: View {
    public init() {}

    public var body: some View {
        Text(verbatim: PanelMessages.openPanel)
    }
}

#bundle ifadesi, yazıldığı konumda değerlendirilir. Bu framework kaynağında, framework hedefiyle ilişkili paketi sağlar. Aynı ifadeyi uygulama hedefi kaynağına taşırsanız uygulamanın paketini sağlar. Swift paketi hedefi için Apple, makronun hedefin kaynak paketini sağladığını belgeliyor. Aramayı, kaynakların sahibi olan kodun yanında tutun. Foundation paket makrosu.

Bildirim, yerelleştirmesi önceden çözülmüş sıradan bir String döndürür. Görünüm, bu sonucu açıkça görüntülemek için Text(verbatim:) kullanır. Herkese açık görünüm yalnızca bir etikettir; metnin görünmesi gereken mevcut uygulama görünümüne ekleyin.

Paket makrosu kullanılamadığında bir framework sınıfından yararlanın

Apple ayrıca framework içinde tanımlanmış bir sınıf üzerinden framework paketini bulmayı destekler. Kendi kaynaklarını içeren geleneksel bir framework için aşağıdaki kod, alternatif bir ileti sağlayıcısının tamamıdır. Bunu önceki PanelMessages bildiriminin yerine kullanın ve yukarıda açıklanan katalog ile dağıtım hedefi gereksinimlerini koruyun.

import Foundation

private final class PanelBundleAnchor: NSObject {}

public enum PanelMessages {
    public static var openPanel: String {
        String(
            localized: "PANEL_OPEN_ACTION",
            defaultValue: "Open panel",
            table: "Panel",
            bundle: Bundle(for: PanelBundleAnchor.self),
            comment: "Label for the action that opens the panel."
        )
    }
}

Çapa sınıf, kaynaklarını kullanmak istediğiniz framework içinde derlenmelidir. Apple, Bundle(for:) metodunun sağlanan sınıfla ilişkili paketi, uygun olduğunda framework paketini de içerecek şekilde döndürdüğünü belgeliyor. Uygulama içinde derlenen bir çapa, uygulamayı tanımlar. Paket kaynakları veya ayrı bir pakete yerleştirilmiş kaynaklar için bunların gerçek kaynak paketini seçin; yalnızca sınıfın konumu bu kaynakların kime ait olduğunu belirlemez. Paketin sınıf tabanlı başlatıcısı, Makroyla kaynak paketi seçimi.

Okunabilir metnin başarılı bir aramadan geldiğini kanıtlayın

Ekranda Open panel görünmesi, katalog aramasının başarılı olduğuna dair yeterli kanıt değildir. Arama başarısız olduğunda başlatıcının defaultValue değeri döndürülür; dolayısıyla aynı görünür metin hem başarılı bir aramayı hem de varsayılan değeri temsil edebilir. Bu davranış okunabilir arayüz metni için yararlıdır, ancak geliştirme sırasında yanlış paket veya tablo kullanımını gizleyebilir. Swift varsayılan değer davranışı.

İlk kaynak dosyasındaki lookupReport() metodu bu belirsizliği giderir. Gerçek bir katalog değeri olarak kullanılmaması gereken, ayırt edici bir varsayılan işaretçiyle arama yapar. Çalışan uygulamadan veya mevcut bir hata ayıklama bağlamından dönen değeri inceleyin. Çözümlenmiş bir girdi bildirmiyorsa çevirileri düzenlemeden önce seçili kaynakları araştırın.

Bu tanılama, Bundle.localizedString(forKey:value:table:) metodunun belgelenmiş davranışını doğrudan izler: Bir anahtar bulunmadığında ve sağlanan varsayılan değer boş değilse metot bu değeri döndürür. Anahtar eksik ve varsayılan değer nil ya da boşsa anahtarın kendisini döndürür. İşaretçi, başarısızlığın geçerli kaynak metinden ayırt edilmesini kolaylaştırır. Paketin yerelleştirilmiş dize dönüş değerleri).

Gözlem Sonraki kontrol
Tanılama, eksik girdi iletisini döndürüyor Kataloğun seçili pakete derlendiğini doğrulayın, ardından Panel ve PANEL_OPEN_ACTION değerini kontrol edin
Tanılama beklenmeyen bir değer çözümlüyor Seçili tablodaki tam girdiyi ve mevcut çalıştırmada kullanılan dili inceleyin
Tanılama doğru çözümlüyor ancak arayüz farklı Arayüzün gerçekte hangi değeri görüntülediğini izleyin
Çevrilmiş bir çalıştırmada İngilizce kaynak değeri görünüyor Girdinin çevirisini ve çalıştırma yapılandırmasını inceleyin; başarılı arama tek başına istenen çevirinin bulunduğunu kanıtlamaz

Tablo, arama sözleşmesinden türetilmiş bir sorun giderme sırasıdır. İşaretçi testi, aramanın bir girdi döndürdüğünü doğrular; ancak desteklenen her dil için çevirinin tamamlandığını kanıtlamaz. Kaynak çözümlemeyi ve çeviri bütünlüğünü ayrı ayrı kontrol edin.

Etiketi Mac uygulamasının seçili dilinde test edin

Uygulamanız ek dilleri destekliyorsa katalog kenar çubuğundan ilgili dili seçin ve o girdinin metin alanına çeviriyi girin. Ardından kapsayıcı Mac uygulaması üzerinden test edin. Apple, katalog düzenleyicisinde çevirilerin doğrudan girilmesini ve çalışırken her girdinin çeviri durumunun güncellenmesini belgeliyor. Dize kataloğuna çeviri ekleme.

Hata ayıklama çalıştırmasını denetlemek için Product > Scheme > Edit Scheme yolunu izleyin, Run seçeneğini belirleyin ve Options bölümünü açın. App Language değerini projenin desteklediği bir dile ayarlayın, düzenleyiciyi kapatın ve Mac uygulamasını yeniden çalıştırın. Çalıştırmanın sistem dili ayarını izlemesini istiyorsanız System Language seçeneğini belirleyin. Uygulamanızı çalıştırırken yerelleştirmeleri test etme.

Dize başlatıcısının locale: bağımsız değişkenini bu dil testinin yerine kullanmayın. Apple, bu bağımsız değişkenin sayılar gibi yerelleştirilmiş değerlerin yerelleştirmesini denetlediğini ve yerelleştirilmiş dizenin aranacağı yerel ayarı değiştirmediğini belgeliyor. Etiket herhangi bir yerelleştirilmiş değer içermediğinden örnekte bu bağımsız değişken kullanılmıyor. Swift yerelleştirilmiş dize yerel ayar parametresi.

Son sözleşmeyi küçük ve açık tutun: Panel.xcstrings framework’e aittir, arama Panel tablosunu seçer ve PANEL_OPEN_ACTION etiketi tanımlar. Girdiyi tanılama yöntemiyle doğrulayın, ardından görüntülenen çeviriyi uygulamanın seçili çalıştırma dilinde kontrol edin. Bu sıra, uygulamanın hiç okumuyor olabileceği bir ifade üzerinde zaman harcamadan önce kaynak aramasını düzeltmenizi sağlar.

Kaynaklar