Un commento utile per i traduttori spiega cosa significa un’etichetta, dove compare e cosa succede quando viene usata. Questa guida mostra come scrivere e associare questi commenti in Xcode per un semplice visualizzatore di forme per Mac, usando etichette inglesi di esempio.

Cosa dovrebbe spiegare un commento per i traduttori?

Parti dalla decisione che deve prendere il traduttore. Un’etichetta breve come Round non chiarisce il suo ruolo grammaticale né il significato previsto. Un commento può indicare che è un aggettivo che descrive una categoria di forme e spiegare che compare sopra un gruppo di anteprime. Apple consiglia commenti che chiariscano dove e come viene usata una stringa nell’interfaccia. Scopri i cataloghi di stringhe

Per chi prepara le etichette di un’app per Mac per la traduzione, il compito concreto consiste nel trasformare ogni stringa ambigua in una spiegazione breve e autonoma. Il traduttore dovrebbe poterne capire lo scopo senza consultare il codice sorgente.

Usa questo schema di scrittura in quattro parti. È un metodo editoriale basato sulle indicazioni di Apple, non un formato di commento obbligatorio di Apple:

Parte Domanda a cui rispondere Dettaglio di esempio
Significato A cosa si riferisce il testo originale? Round descrive forme con contorni curvi.
Ruolo nell’interfaccia Che tipo di testo dell’interfaccia è? Un’intestazione di categoria sopra le anteprime delle forme.
Comportamento o posizione Cosa succede o cosa c’è intorno? Expand mostra i dettagli sotto l’anteprima.
Contenuto variabile Cosa può contenere ciascun valore inserito? Il primo valore è il nome di una forma; il secondo è il nome di una raccolta.

Includi solo le parti che influiscono sull’interpretazione. Un’intestazione statica non richiede la spiegazione di un’azione. Per un pulsante è utile chiarire cosa accade quando lo si tocca. Un messaggio con due nomi inseriti richiede di spiegare il rapporto tra quei nomi.

Apple consiglia in particolare di spiegare l’elemento dell’interfaccia, l’interfaccia circostante e il contenuto rappresentato dai segnaposto. Considera questi dettagli un contesto pratico per la traduzione. Guida pratica: esplorare la localizzazione con Xcode

Trasformare commenti vaghi in descrizioni utili del messaggio

Gli esempi seguenti appartengono a un visualizzatore di forme per Mac a scopo illustrativo. Ogni commento migliorato descrive un comportamento ipotizzato ed esplicito dell’interfaccia; adattalo al controllo effettivo prima di usare il testo.

Etichetta originale Commento poco utile Commento più utile
Shapes Etichetta per le forme. Elemento di navigazione nella barra laterale che apre l’elenco delle forme geometriche. Nome plurale.
Round Testo della forma. Intestazione di categoria sopra le anteprime delle forme con contorni curvi. Aggettivo che descrive le forme.
Expand Titolo del pulsante. Pulsante sotto l’anteprima di una forma che mostra i dettagli sotto l’anteprima. Verbo che esprime un’azione.
Selected Etichetta di selezione. Stato accanto alla forma attualmente scelta per l’anteprima. Descrive lo stato corrente della forma.

Le versioni poco utili ripetono ciò che il traduttore può già vedere. Quelle più efficaci chiariscono i rapporti mancanti: quale oggetto descrive l’aggettivo, quali contenuti mostra il pulsante o quale elemento si trova in un determinato stato.

In inglese, un sostantivo nomina qualcosa, un aggettivo lo descrive e un verbo all’imperativo indica un’azione. Queste distinzioni aiutano a spiegare le formulazioni concise delle interfacce. Per esempio, in questa illustrazione Selected descrive uno stato esistente, mentre Select su un pulsante richiederebbe un’azione. Indica quale interpretazione richiede l’interfaccia.

Mantieni i commenti concreti. Per Expand, spiega se il controllo mostra un testo dettagliato, ingrandisce un’anteprima o apre un gruppo nella barra laterale. Descrivere l’operazione è più utile che dire che qualcosa diventa più grande.

Evita di imporre regole di formattazione inglesi non necessarie. Se l’interfaccia richiede un’intestazione di categoria concisa, dillo. Non inventare un limite fisso di caratteri né chiedere di mantenere l’ordine delle parole inglesi. Documenta un vincolo reale del layout solo quando sai che si applica.

Aggiungere commenti per i traduttori in SwiftUI

Apple documenta il parametro comment: di Text come modo per includere suggerimenti per la traduzione. Se l’inizializzatore testuale comodo di un controllo non permette di fornire il commento necessario, usa il suo generatore di contenuto con una vista Text esplicita. Apple mostra questo schema per Label e spiega che è supportato da molti controlli SwiftUI. Preparare le viste per la localizzazione

L’esempio completo qui sotto è una piccola app SwiftUI per macOS. In Xcode, crea un progetto per macOS usando SwiftUI, imposta come destinazione di distribuzione macOS 13 o successivo e sostituisci il codice generato per l’app e la vista dei contenuti con questo singolo file. Mantieni un solo punto di ingresso dell’app. L’esempio usa nomi fissi di fantasia e mostra una frase di dettaglio quando l’utente tocca Expand.

import SwiftUI

@main
struct ShapeCommentDemoApp: App {
    var body: some Scene {
        WindowGroup {
            ShapeBrowserView()
        }
    }
}

struct ShapeBrowserView: View {
    @State private var showsDetails = false

    private let shapeName = "Circle A"
    private let collectionName = "Shape Set A"

    var body: some View {
        VStack(alignment: .leading, spacing: 16) {
            Text(
                "Round",
                comment: "Category heading above previews of shapes with curved outlines. Adjective describing the shapes."
            )
            .font(.headline)

            Circle()
                .fill(Color.blue)
                .frame(width: 80, height: 80)

            Text(
                "\(shapeName) in \(collectionName)",
                comment: "Caption below a shape preview. The first value is the shape name; the second is the collection containing it. Sample names: Circle A and Shape Set A."
            )

            Button {
                showsDetails = true
            } label: {
                Text(
                    "Expand",
                    comment: "Button below a shape preview that reveals its details beneath the preview. Verb expressing an action."
                )
            }
            .disabled(showsDetails)

            if showsDetails {
                Text(
                    "A shape with a curved outline.",
                    comment: "Detail sentence revealed below the preview after clicking Expand. Describes the displayed circle."
                )
            }
        }
        .padding(24)
        .frame(minWidth: 360, minHeight: 300)
    }
}

Questo esempio è stato verificato rispetto agli schemi API documentati; non è stato compilato né eseguito qui perché l’ambiente disponibile non dispone della toolchain Swift.

Per le stringhe rivolte all’utente create al di fuori di una vista SwiftUI, Apple documenta String(localized:comment:). Usa l’argomento per il commento dell’API di localizzazione per associare il contesto al messaggio. Apple supporta anche una chiave di ricerca separata dal valore sorgente predefinito, quando è necessario che siano diversi. Preparare il testo dell’app per la traduzione

Spiegare i valori inseriti in base al significato e al rapporto

La didascalia dell’esempio contiene due interpolazioni Swift: \(shapeName) e \(collectionName). L’interpolazione Swift inserisce in una stringa i valori delle espressioni. I nomi delle variabili appartengono al codice sorgente; la spiegazione deve comunque essere comprensibile a chi non può vedere quei nomi. Stringhe e caratteri

Per i valori di esempio mostrati, la didascalia inglese è Circle A in Shape Set A. Il suo commento spiega sia l’ordine dei valori inseriti sia il loro rapporto: uno indica il nome della forma, l’altro quello della raccolta che la contiene. È un’informazione più utile della semplice descrizione di due argomenti di tipo stringa.

Quando esamini un messaggio interpolato, poniti tre domande:

  1. Che tipo di contenuto può comparire in ciascuna posizione: un nome, un conteggio o un altro tipo di valore?
  2. Che rapporto c’è tra i valori?
  3. Il commento rimane corretto per tutti i valori che l’app può fornire?

Indica chiaramente che gli esempi sono tali. Qui Circle A e Shape Set A illustrano i ruoli degli argomenti. Non definiscono una traduzione obbligatoria né un elenco esaustivo di tutti i nomi possibili.

I conteggi richiedono una decisione di implementazione distinta. Se in seguito aggiungi una didascalia come 3 shapes, un commento può spiegare cosa viene conteggiato, ma le varianti grammaticali vanno inserite nel catalogo. Apple documenta l’uso di Vary by Plural per i conteggi interpolati, con forme inglesi distinte come 1 item e 2 items. Localizzare e variare il testo con un catalogo di stringhe

Trovare ed esaminare i commenti in Xcode

Per collegare i commenti nel codice al catalogo, segui il flusso di lavoro documentato da Apple:

  1. Scegli File > New > File from Template.
  2. Filtra per string, seleziona String Catalog sotto Resource e crealo con il nome predefinito Localizable.
  3. Scegli Product > Build per estrarre le stringhe localizzabili.
  4. Seleziona Localizable.xcstrings nel navigatore del progetto.
  5. Scegli Editor > Assistant, poi seleziona una chiave per esaminarne la sorgente accanto al catalogo. Localizzare e variare il testo con un catalogo di stringhe

Confronta il commento nel catalogo con l’uso effettivo. Nell’esempio, Round dovrebbe descrivere un’intestazione di categoria, mentre Expand dovrebbe descrivere la visualizzazione dei dettagli. Se manca una stringa, verifica che il codice usi un’API localizzabile e che Use Compiler to Extract Swift Strings sia attivo. Apple indica che questa impostazione di compilazione è necessaria per estrarre le stringhe Swift tramite il compilatore. Scopri i cataloghi di stringhe

Apple supporta anche la modifica del contesto direttamente nella colonna dei commenti del catalogo di stringhe. La generazione automatica dei commenti è stata introdotta in Xcode 26; la documentazione attuale descrive come fare clic su una chiave tenendo premuto Control e scegliere Generate Comment. Se questa opzione non è disponibile nella tua configurazione, associa un commento nel codice o inseriscilo nel catalogo. Guida pratica: esplorare la localizzazione con Xcode, Localizzare e variare il testo con un catalogo di stringhe

Verifica che il testo generato corrisponda al comportamento dell’interfaccia. Una descrizione che identifica correttamente un pulsante potrebbe comunque dover chiarire l’oggetto o il risultato. In questo esempio, la distinzione utile è che Expand mostra una frase di dettaglio sotto l’anteprima.

Decidere se due etichette identiche possono condividere il contesto

Una grafia inglese identica non implica un significato identico. Supponiamo che un’altra schermata usi Round come azione che arrotonda un valore numerico. Unire questo uso all’intestazione della categoria di forme richiederebbe a una sola voce del catalogo di descrivere due ruoli grammaticali diversi.

Apple spiega che una stringa localizzabile ha una chiave di ricerca e appartiene a una tabella; le chiavi sono univoche all’interno della tabella. La documentazione Swift di Apple fornisce anche un modo supportato per usare una chiave distinta insieme a un valore sorgente predefinito. Usa chiavi separate quando i significati richiedono traduzioni indipendenti, anche se i valori visualizzati in inglese coincidono. Scopri i cataloghi di stringhe, Preparare il testo dell’app per la traduzione

Una regola pratica consiste nel chiedersi se un unico commento può descrivere correttamente ogni uso. Se il significato e il ruolo nell’interfaccia restano coerenti, il contesto condiviso può essere appropriato. Se per la spiegazione occorre descrivere operazioni non correlate, rivedi la struttura delle chiavi. È una deduzione progettuale basata sul modello di chiavi e tabelle di Apple, non una regola secondo cui ogni controllo deve avere una stringa propria.

Prima di consegnare un’etichetta, leggi il suo commento senza consultare il codice sorgente. Dovrebbe permettere al traduttore di individuare il significato previsto, capire in quale punto dell’interfaccia compare il testo e comprendere gli eventuali contenuti inseriti. Aggiorna il commento ogni volta che cambia il comportamento o il ruolo dell’etichetta, così che continui a descrivere l’interfaccia che vede l’utente.

Fonti