Per rinominare una chiave di un catalogo di stringhe in Xcode, conserva separatamente il messaggio sorgente, aggiorna i riferimenti nel codice e verifica ogni traduzione e variante esistente. Per le stringhe estratte, Xcode 26 offre un refactoring di conversione; modificare solo una chiave di ricerca non basta.

Questa guida è rivolta a chi mantiene un’app Mac SwiftUI con un catalogo .xcstrings esistente. L’obiettivo è sostituire chiavi che riproducono il testo dei messaggi con identificatori significativi, mantenendo intatti il testo visualizzato e le traduzioni. Apple documenta le API e il flusso di conversione descritti di seguito, ma non garantisce che una modifica arbitraria di una chiave trasferisca automaticamente tutte le traduzioni.

Cosa deve rimanere invariato quando cambia una chiave?

Un messaggio localizzabile comprende più di un identificatore. Apple descrive la chiave, il valore predefinito, il commento e la tabella delle stringhe come componenti separati. La chiave identifica il messaggio in fase di esecuzione; il valore predefinito fornisce il testo sorgente. Un catalogo contiene le traduzioni e i metadati di una tabella. Considera una rinomina come una modifica coordinata al contratto di quel messaggio. Scoprire i cataloghi di stringhe

Prima di modificare, annota quanto segue per ogni voce interessata. Questi esempi sintetici illustrano una rinomina; non sono risultati misurati.

Componente Prima Risultato previsto
Chiave di ricerca Open collection collection.open
Messaggio sorgente Open collection Invariato
Tabella Localizable Invariata
Bundle Bundle principale dell’app Invariato
Contesto per i traduttori Pulsante che apre la raccolta selezionata Conservato
Traduzioni esistenti Valori correnti in ogni localizzazione Conservate
Argomenti numerici, se presenti Conteggio intero Stesso tipo e significato
Varianti plurali o per dispositivo Rami esistenti Conservati

Usa questo registro per il confronto. Una compilazione riuscita, da sola, non dimostra che le traduzioni siano sopravvissute: l’app potrebbe comunque visualizzare un messaggio predefinito quando una ricerca non trova corrispondenze. La documentazione SwiftUI spiega che una chiave localizzata può essere visualizzata direttamente se non esiste una corrispondenza nel catalogo. Con una chiave semantica, nell’interfaccia potrebbe quindi comparire un identificatore come collection.open. Preparare le viste per la localizzazione

Individua la sorgente prima di modificare il catalogo

Apri il catalogo esistente nel navigatore dei progetti di Xcode. Scegli Editor > Assistant, quindi seleziona la voce per esaminarne la sorgente. Apple documenta anche la freccia accanto a una chiave e gli usi di esempio nell’Inspector degli attributi come strumenti per individuare i riferimenti. Per le stringhe estratte, dopo aver modificato il codice scegli Product > Build per sincronizzare il catalogo. Localizzare e variare il testo con un catalogo di stringhe

Verifica se la voce viene estratta dal codice o gestita manualmente. Apple spiega che il codice sorgente governa i messaggi estratti: le compilazioni sincronizzano i relativi valori sorgente. Una voce tradotta che non viene più estratta rimane nello stato Stale; una non tradotta può essere rimossa. Le voci gestite manualmente non vengono aggiornate né rimosse durante l’estrazione. Perciò, non eliminare una vecchia voce tradotta solo perché ne è comparsa una nuova. Scoprire i cataloghi di stringhe

Prima di procedere, crea un punto di ripristino e confronta con esso la voce interessata al termine. Durante questa operazione, mantieni invariati la tabella e il bundle, così ci saranno meno possibili cause per eventuali traduzioni mancanti. Le API di localizzazione di Apple accettano le informazioni sulla tabella e sul bundle proprio perché determinano dove viene trovato un messaggio. Preparare il testo dell’app per la traduzione

Usa il refactoring di conversione di Xcode per le stringhe estratte

Per un progetto che usa Xcode 26 o versioni successive, valuta la conversione della voce estratta esistente in un simbolo localizzabile generato. Apple ha introdotto questo flusso in Xcode 26 e mostra come modificare una chiave assegnandole un nome semantico durante la conversione. È un metodo documentato per cambiare insieme il modo in cui un messaggio viene identificato e referenziato. Esercitazione guidata: esplorare la localizzazione con Xcode

  1. Nelle impostazioni di compilazione, verifica che Generate String Catalog Symbols sia impostato su Yes, se il progetto esistente richiede che venga abilitato.
  2. Nell’editor del catalogo, seleziona la chiave esistente, fai clic tenendo premuto Control e scegli Refactor > Convert Strings to Symbols.
  3. Esamina l’anteprima che mostra la modifica della chiave del catalogo e le posizioni interessate nel codice sorgente.
  4. Nell’interfaccia di conversione, modifica il nome semantico proposto e, se applicabile, i nomi degli argomenti.
  5. Confronta il codice attuale e quello modificato tramite l’anteprima evidenziata, quindi fai clic su Convert.
  6. Compila e confronta la voce risultante con il punto di ripristino, incluse traduzioni e varianti.

Apple documenta questi controlli di conversione e mostra esempi di utilizzo generato nell’Inspector degli attributi. Usa tali esempi anziché indovinare un identificatore Swift a partire dalla punteggiatura della chiave desiderata nel catalogo. I simboli generati dipendono dalle informazioni del catalogo; le tabelle diverse da quella predefinita introducono uno spazio dei nomi per la tabella. Usare nel codice simboli localizzabili generati

Questo refactoring serve specificamente a passare dalle stringhe estratte ai simboli generati. La documentazione citata non definisce un’operazione universale di rinomina per ogni voce gestita manualmente o per ogni riferimento esterno. Se nell’anteprima manca un riferimento necessario, gestiscilo esplicitamente prima di rimuovere la chiave precedente.

Mantieni l’estrazione se preferisci definire chiavi e valori predefiniti nel codice

Puoi anche mantenere l’estrazione basata sul codice. Apple supporta esplicitamente chiavi di ricerca e messaggi sorgente separati tramite String(localized:defaultValue:...): il primo argomento fornisce la chiave e defaultValue fornisce la stringa sorgente. Per esempio, una chiave semantica può mantenere Open collection come messaggio predefinito. Preparare il testo dell’app per la traduzione

Il seguente esempio completo di codice dell’app illustra questo modello con un’etichetta statica e un conteggio intero. Usa un target app SwiftUI per macOS con una versione minima di macOS 12 o successive e sostituisci il codice sorgente di ingresso esistente dell’app, invece di aggiungere una seconda dichiarazione @main. Aggiungi Localizable.xcstrings al target dell’app. L’esempio è stato verificato rispetto alle API di Apple; non è stato compilato qui perché non era disponibile una toolchain Swift.

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

Qui, String(localized:...) risolve il testo localizzato prima che la stringa risultante venga visualizzata. Text(verbatim:) rende esplicito questo passaggio di visualizzazione. Apple distingue la localizzazione immediata di una stringa da LocalizedStringResource, che rappresenta una ricerca differibile. Per le interfacce riutilizzabili che passano messaggi non ancora risolti tra viste, Apple consiglia un tipo localizzabile come LocalizedStringResource. LocalizedStringResource, Preparare il testo dell’app per la traduzione

Quando migri un messaggio esistente con questo approccio, compila per creare o aggiornare la voce di destinazione, quindi trasferisci le traduzioni esistenti prima di eliminare la voce precedente. Apple documenta l’inserimento diretto delle traduzioni selezionando una localizzazione e modificando la colonna della lingua corrispondente. Per un messaggio con varianti, conserva ogni ramo pertinente invece di copiare solo il testo di primo livello. Questo trasferimento graduale è una procedura pratica di migrazione basata sugli strumenti di modifica documentati, non una garanzia di rinomina automatica. Localizzare e variare il testo con un catalogo di stringhe

Qual è la differenza tra estrazione e formattazione in fase di esecuzione?

L’estrazione avviene durante lo sviluppo: Xcode individua le espressioni localizzabili supportate e aggiorna il catalogo. La formattazione in fase di esecuzione avviene quando l’app risolve il messaggio e inserisce i valori. Il conteggio di esempio 7 è un argomento di runtime; non dovrebbe diventare parte della chiave stabile.

Mantieni l’interpolazione dell’intero all’interno dell’espressione localizzabile. String.LocalizationValue di Apple supporta l’interpolazione e, per chi vuole usare identificatori arbitrari, rimanda agli inizializzatori con una chiave statica e un defaultValue separato. Costruire prima una normale stringa già formattata non equivale a conservare il messaggio localizzabile e i relativi argomenti. String.LocalizationValue

Per i messaggi con conteggio grammaticale, seleziona la voce estratta del conteggio, fai clic tenendo premuto Control e scegli Vary by Plural. Completa le varianti sorgente e quelle richieste per ogni localizzazione esistente. Per una sorgente inglese, Apple mostra One con %lld item e Other con %lld items. Aggiungere semplicemente l’interpolazione non completa queste varianti. Localizzare e variare il testo con un catalogo di stringhe

Durante una rinomina, conserva i tipi, le posizioni e i significati degli argomenti. Se il vecchio messaggio contiene un conteggio intero, sostituirlo con una stringa preformattata modifica anche il contratto di formattazione. Per i simboli generati, Xcode crea funzioni con parametri tipizzati per i messaggi che contengono specificatori di formato; quando converti, esamina tali firme. Usare nel codice simboli localizzabili generati

Verifica la conservazione prima di rimuovere la vecchia voce

Usa i seguenti controlli per verificare il completamento. Permettono di distinguere un problema del catalogo da un problema di ricerca o formattazione.

Controllo Risultato atteso Se non riesce, verifica
Testo sorgente Corrisponde al punto di ripristino Valore predefinito mancante o alterato
Traduzioni esistenti Ogni valore precedente è ancora disponibile con la nuova chiave Trasferimento incompleto o destinazione errata
Struttura delle varianti Tutti i rami precedenti, plurali e per dispositivo, sono ancora presenti È stato copiato solo un valore di primo livello
Etichetta nell’app Visualizza il messaggio previsto Chiave, tabella, bundle o localizzazione non corrispondente
Conteggi sintetici 0, 1, 7 I valori vengono inseriti correttamente e i rami plurali richiesti funzionano Argomento o variante non corrispondente
Riferimenti precedenti Non rimangono utilizzi necessari Migrazione incompleta

Per verificare l’app Mac in una localizzazione esistente, scegli Product > Scheme > Edit Scheme, seleziona Run, apri Options e scegli una App Language. Chiudi la finestra di dialogo ed esegui la destinazione Mac. Ripeti per le localizzazioni interessate dalla rinomina, controllando l’etichetta effettiva e il messaggio con conteggio. Apple documenta questo flusso di verifica basato sullo schema. Verificare le localizzazioni durante l’esecuzione dell’app

Se compare la nuova chiave ma la traduzione è vuota, torna alla voce precedente e trasferisci il contenuto mancante. Se l’identificatore appare sullo schermo, controlla i parametri della ricerca. Se non funzionano solo i conteggi, verifica l’interpolazione e le varianti. Rimuovi la vecchia voce dopo averne trasferito il contenuto e spostato i riferimenti necessari. La modifica completa dovrebbe cambiare l’identificatore preservando il messaggio, i suoi argomenti e le traduzioni che gli utenti già ricevono.

Fonti