Per un’etichetta riutilizzabile su macOS, accetta i messaggi localizzabili come LocalizedStringResource, mantieni un percorso verbatim: separato per il testo letterale e conserva l’interpolazione fino alla localizzazione. Questo tutorial definisce tale contratto per un contatore di elementi desktop e verifica separatamente l’estrazione e la visualizzazione.

Quali garanzie dovrebbe offrire l’API di testo riutilizzabile?

Supponiamo che un’app per Mac abbia bisogno di un riepilogo compatto che mostri il conteggio degli elementi e un’etichetta di raccolta fittizia come Sample Set. Il componente riutilizzabile deve distinguere tre tipi di input: un messaggio scritto dall’app che richiede una traduzione, una chiave di localizzazione SwiftUI esistente e un testo che deve essere visualizzato esattamente come fornito.

Apple consiglia LocalizedStringResource per rappresentare e passare stringhe localizzabili alle viste personalizzate e ad altro codice Swift. Le indicazioni attuali mostrano proprietà di viste personalizzate di questo tipo visualizzate con Text. Usalo come contratto principale per i messaggi quando progetti un nuovo componente. Preparing your app’s text for translation.

La tabella decisionale seguente propone un’API basata sui comportamenti documentati. Le etichette esplicite degli argomenti permettono di verificare l’intento di chi chiama senza affidarsi a due overload di stringa concorrenti e privi di etichetta.

Intento di chi chiama Punto d’ingresso proposto Percorso di rendering
Passare un messaggio traducibile con contesto facoltativo SummaryLabel(localized:) Text(resource)
Passare una chiave SwiftUI, inclusa l’interpolazione SwiftUI SummaryLabel(key:) Text(key, tableName:bundle:)
Visualizzare un’etichetta esatta SummaryLabel(verbatim:) Text(verbatim:)
Fornire testo già composto da chi chiama SummaryLabel(text:) Memorizzare il Text fornito

Mantieni disponibile LocalizedStringKey quando il componente ha bisogno specificamente del comportamento basato su chiavi di SwiftUI. Apple documenta che un valore letterale stringa passato direttamente a Text crea una chiave di localizzazione, mentre una variabile String segue normalmente un percorso che non usa la localizzazione. Un wrapper che accetta solo String cambia quindi il significato di chiamate che altrimenti sembrerebbero simili. LocalizedStringKey.

Crea un componente completo con punti d’ingresso espliciti

Per questo esempio, usa un progetto di app SwiftUI per macOS in Xcode 26 o versione successiva, con la destinazione di distribuzione impostata su macOS 26. Sostituisci le dichiarazioni generate dell’app e della vista del contenuto con il programma completo seguente; mantieni una sola dichiarazione @main nel target. Tutte le etichette e i conteggi sono fittizi. Il codice è stato esaminato rispetto alle API documentate, ma qui non è stato compilato perché questo ambiente non dispone di un compilatore Swift.

import Foundation
import SwiftUI

struct SummaryLabel: View {
    private let text: Text

    init(localized resource: LocalizedStringResource) {
        text = Text(resource)
    }

    init(
        key: LocalizedStringKey,
        tableName: String? = nil,
        bundle: Bundle? = nil,
        comment: StaticString? = nil
    ) {
        text = Text(
            key,
            tableName: tableName,
            bundle: bundle,
            comment: comment
        )
    }

    init(verbatim value: String) {
        text = Text(verbatim: value)
    }

    init(text: Text) {
        self.text = text
    }

    var body: some View {
        text
            .font(.callout)
            .padding(8)
    }
}

struct ContentView: View {
    @State private var itemCount = 2
    private let collectionLabel = "Sample Set"

    var body: some View {
        VStack(alignment: .leading, spacing: 12) {
            Stepper(value: $itemCount, in: 0...12) {
                Text("Item count")
            }

            SummaryLabel(
                localized: LocalizedStringResource(
                    "summary.item-count",
                    defaultValue: "\(itemCount) items",
                    comment: "Summary below the item-count control. The integer is the number of items."
                )
            )

            SummaryLabel(
                key: "Collection: \(collectionLabel)"
            )

            SummaryLabel(verbatim: collectionLabel)

            SummaryLabel(
                text: Text(
                    "Preview",
                    comment: "Heading for a preview of the current item selection."
                ).bold()
            )
        }
        .padding(20)
        .frame(minWidth: 320)
    }
}

@main
struct TextContractDemoApp: App {
    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
}

L’inizializzatore della risorsa separa deliberatamente la chiave stabile summary.item-count dal messaggio predefinito, \(itemCount) items. Apple documenta per questo inizializzatore una chiave statica, un valore predefinito localizzabile, una tabella, una lingua, un bundle e un commento per il traduttore. Il valore predefinito viene usato quando la chiave non è presente nella tabella specificata. LocalizedStringResource initializer.

L’inizializzatore verbatim: definisce una garanzia altrettanto chiara: visualizzare la stringa fornita senza localizzarla. Funziona sia con un argomento letterale sia con una variabile. Usa questo percorso per l’etichetta di raccolta fittizia quando la grafia esatta è il contenuto da visualizzare. Text.init(verbatim:).

Il punto d’ingresso text: consente a chi chiama di comporre testo localizzato o con uno stile prima di passarlo al componente. Questo componente aggiunge tipografia e spaziatura condivise; chi chiama sceglie comunque la semantica del messaggio. Passare Text è una via di fuga, quindi un componente che deve imporre un contratto più restrittivo può omettere quell’inizializzatore.

In che modo differiscono l’estrazione e la formattazione in fase di esecuzione?

Considera la localizzazione come due verifiche distinte. Durante una compilazione, Xcode individua le espressioni localizzabili nel codice sorgente e aggiorna il catalogo stringhe. Durante l’esecuzione, l’app risolve il messaggio e sostituisce i suoi argomenti. La sessione Apple sui cataloghi stringhe descrive esplicitamente il riconoscimento dei valori letterali usati per creare LocalizedStringResource nel punto in cui si chiama una vista personalizzata. Indica inoltre l’impostazione di compilazione Use Compiler to Extract Swift Strings. Discover String Catalogs.

L’interpolazione deve raggiungere un tipo consapevole della localizzazione prima di diventare una stringa ordinaria completa. Apple spiega che il generatore di interpolazione di SwiftUI mantiene separati la chiave di formato e i valori degli argomenti, consentendo la localizzazione prima della sostituzione. Convertire una String già interpolata in una chiave non può ricostruire gli argomenti tipizzati originali. What’s New in Swift.

Questo frammento diagnostico mostra la distinzione; non è una seconda app. Tutti i valori usati nel frammento sono definiti localmente.

import SwiftUI

let count = 2

// Ordinary String interpolation has already produced "2 items".
let completed: String = "\(count) items"
let exactDisplay = Text(completed)

// Looks up the completed value as a key.
// This does not restore a count placeholder.
let completedValueLookup = Text(LocalizedStringKey(completed))

// Preserves localization-aware interpolation from the beginning.
let messageKey: LocalizedStringKey = "\(count) items"
let interpolatedDisplay = Text(messageKey)

Creare LocalizedStringKey a partire da una variabile è un modo documentato per richiedere la ricerca in fase di esecuzione. È utile quando la variabile contiene intenzionalmente una chiave nota. Non garantisce che Xcode abbia estratto nel catalogo tutti i possibili valori di quella variabile. Gestisci esplicitamente le chiavi dinamiche previste oppure usa dichiarazioni di risorse letterali per l’insieme finito di messaggi dell’app. Il comportamento di ricerca e il fallback sono documentati in Text.init(_:tableName:bundle:comment:).

Mantieni l’intero messaggio, inclusi la punteggiatura e la posizione dei segnaposto, in un’unica espressione localizzabile. Per questo esempio, tieni unito Collection: \(collectionLabel). Comporre un messaggio completo a partire da frammenti risolti separatamente lascerebbe a chi chiama la responsabilità di ordinarli e spaziarli.

Aggiungi il catalogo e configura il comportamento dei plurali

Per prima cosa, aggiungi un catalogo stringhe tramite File > New > File from Template, seleziona String Catalog e chiamalo Localizable. Poi scegli Product > Build. Apple documenta che la compilazione popola il catalogo con le API localizzabili e lo aggiorna quando cambiano i messaggi nel codice sorgente. Localizing and varying text with a string catalog.

Per l’esempio, esamina la voce summary.item-count e il suo intero interpolato. Fai clic tenendo premuto Control sulla voce e scegli Vary by Plural. Nella localizzazione inglese di origine, imposta One su %lld item e Other su %lld items, mantenendo il segnaposto intero fornito da Xcode. Quando aggiungi altre localizzazioni, aggiungi le forme richieste: le categorie del plurale dipendono dalla lingua. Localizing and varying text with a string catalog.

L’interpolazione fornisce il conteggio, ma da sola non crea la forma singolare. L’esercitazione guidata di Apple mostra come aggiungere le varianti di plurale nel catalogo e come il sistema selezioni a runtime la variante corrispondente. Per questo, una compilazione riuscita e un messaggio estratto sono solo una parte della verifica. Code-along: Explore localization with Xcode.

Dopo aver configurato le forme del plurale nella localizzazione di origine, usa questa piccola matrice di accettazione. Sono risultati attesi per il programma esemplificativo, non risultati di un’esecuzione effettiva.

Verifica Risultato atteso
Compilare ed esaminare summary.item-count Una voce del messaggio con una sostituzione intera
Impostare il conteggio su 0 0 items
Impostare il conteggio su 1 1 item
Impostare il conteggio su 2 2 items
Esaminare la riga dell’etichetta esatta Sample Set resta letterale
Esaminare il messaggio della raccolta L’etichetta è un argomento all’interno del messaggio completo

Diagnostica separatamente le voci mancanti e la visualizzazione errata

Se manca un messaggio nel catalogo, controlla prima il tipo nel codice sorgente. Un parametro String potrebbe aver eliminato l’espressione localizzabile prima che raggiungesse il componente. Controlla il target del catalogo, compila lo schema che contiene il punto di chiamata e verifica Use Compiler to Extract Swift Strings. Apple spiega che l’estrazione opera sullo schema e sulla piattaforma correnti, quindi controlla la configurazione che compila effettivamente il messaggio. Discover String Catalogs.

Se una voce è presente ma l’app visualizza una chiave o un testo di fallback, controlla la configurazione della ricerca. L’inizializzatore di Text basato su chiavi cerca nella tabella e nel bundle specificati; se omessi, vengono selezionati la tabella predefinita e il bundle principale. Una chiave o una tabella assente produce la rappresentazione testuale della chiave. Un fallback leggibile può quindi nascondere una ricerca incompleta. Text.init(_:tableName:bundle:comment:).

Quando sposti il componente in un framework o in un pacchetto, decidi dove devono risiedere i messaggi. I messaggi di proprietà del componente richiedono il bundle delle risorse del componente; le risorse fornite da chi chiama dovrebbero mantenere le informazioni di ricerca specificate. Le indicazioni attuali di Apple supportano il passaggio di #bundle alle API di localizzazione per identificare il bundle del target che contiene il codice. Anche le tabelle con nome richiedono cataloghi corrispondenti. Preparing your app’s text for translation.

Infine, non dare per scontato che ogni interpolazione accettata da SwiftUI possa essere usata anche in una risorsa Foundation. LocalizedStringKey dispone di metodi di interpolazione specifici, incluse varianti basate su formati e formattatori. Scegli il tipo di messaggio prima di comporre l’espressione e consulta le operazioni di interpolazione supportate se un argomento non viene compilato. LocalizedStringKey.StringInterpolation.

Un componente di testo riutilizzabile è pronto quando chi lo usa può esprimere chiaramente il proprio intento e verificarlo in entrambe le fasi: la compilazione produce il messaggio previsto nel catalogo e l’app Mac in esecuzione visualizza la sostituzione, la forma plurale o l’etichetta esatta corretta. Mantieni queste verifiche accanto al contratto dell’API ogni volta che il componente cambia.

Fonti