Come localizzare la tua app iOS: guida all'internazionalizzazione con SwiftUI

Prepara la tua app Xcode, traduci .xcstrings con l'IA, quindi carica le schermate in modo che PTC (Private Translation Cloud) faccia la revisione dell'app iOS visualizzata in ogni lingua. Questa guida illustra l'intero flusso di lavoro utilizzando SwiftUI e gli String Catalog di Xcode 15+, il percorso moderno consigliato da Apple. Per una panoramica del servizio multipiattaforma che copre sia iOS che Android, vedi tradurre app iOS e Android con l'IA.

Parte 1: Come funziona la localizzazione iOS

La localizzazione iOS è il processo di adattamento dei testi, della formattazione e degli asset della tua app per supportare più lingue e regioni. Con gli String Catalog introdotti in Xcode 15, il flusso di lavoro è drasticamente più semplice rispetto al vecchio approccio .strings / .stringsdict.

Internazionalizzazione e localizzazione a confronto

Queste sono due fasi separate e devono avvenire in questo ordine:

• L'internazionalizzazione (i18n) è il lavoro tecnico di base. Strutturi il tuo codice in modo che testo, immagini e formattazione possano variare in base al locale senza modifiche al codice. Viene eseguita una volta sola, idealmente prima della tua prima release.
• La localizzazione (l10n) è il lavoro continuo che segue. Scrivere traduzioni, adattare i layout e fornire asset specifici del locale per ogni nuova lingua.

L'errore più comune è trattare la localizzazione come un'attività successiva al lancio, per poi scoprire che la codebase non è pronta. Tornare indietro per correggere stringhe hardcoded, layout a direzione fissa e formattatori non sensibili al locale in un'app esistente richiede molto più tempo che creare un'app tenendo a mente la localizzazione fin dall'inizio.

Come Xcode 15+ utilizza Localizable.xcstrings come singola fonte di verità

Il modello di localizzazione di Apple in Xcode 15+ è incentrato su un singolo file per target: Localizable.xcstrings. Questo file è uno String Catalog in formato JSON che contiene la tua lingua di origine più ogni traduzione, incluse le varianti plurali, le varianti specifiche per dispositivo e le sostituzioni.

Xcode estrae automaticamente le stringhe localizzabili dal tuo codice SwiftUI (qualsiasi Text("..."), Label("...", systemImage:), Button("...") e qualsiasi interpolazione di stringhe che utilizza LocalizedStringKey). L'esecuzione della build della tua app popola Localizable.xcstrings con ogni stringa di origine estratta.

Apple supporta diversi formati. .strings (coppie chiave-valore legacy), .stringsdict (plurali legacy) e .xcstrings (moderno). I nuovi progetti dovrebbero iniziare con .xcstrings. I progetti esistenti basati su .strings possono migrare tramite File > New > File > String Catalog e l'opzione di importazione di Xcode. La documentazione ufficiale sulla localizzazione di Apple copre l'intero contesto.

Parte 2: Configurare il tuo progetto Xcode per la localizzazione

Passaggio 1: Abilita la localizzazione. Apri il tuo progetto in Xcode e seleziona il file di progetto nel Navigator. Sotto la scheda Info, scorri fino a Localizations. L'inglese è già elencato come lingua base. Clicca su + per aggiungere ogni lingua di destinazione (spagnolo, francese, arabo, ecc.).

Passaggio 2: Crea uno String Catalog. Clicca con il tasto destro sul tuo progetto e seleziona New File from Template. Cerca String Catalog e aggiungilo. Mantieni il nome predefinito Localizable.xcstrings. Esegui la build del progetto una volta con Cmd+B. Xcode scansiona il tuo codice, trova ogni stringa localizzabile e popola il catalogo automaticamente.

Passaggio 3: Contrassegna le stringhe per la localizzazione. In SwiftUI, qualsiasi stringa letterale passata a Text(_:), Label, etichette di azioni Button, titoli di navigazione, ecc. è automaticamente LocalizedStringKey:

import SwiftUI

struct WelcomeView: View {
    let userName: String
    let unreadCount: Int

    var body: some View {
        VStack {
            Text("Welcome, \(userName)!")
            Text("You have \(unreadCount) unread messages")
            Button("Get Started") {
                // action
            }
        }
    }
}

Ci sono due pattern in cui Xcode non può estrarre le stringhe automaticamente. Entrambi falliscono silenziosamente:

Suggerimento 1: Evita di passare variabili a Text. Quando passi una variabile a una vista Text invece di una stringa letterale, SwiftUI la tratta come una stringa semplice e salta completamente la ricerca nel catalogo:

// NOT localized - SwiftUI treats the variable as a plain String
let title = "welcome_title"
Text(title)

// Localized correctly
Text(LocalizedStringKey(title))

Suggerimento 2: Usa String(localized:) all'esterno delle viste. Per le stringhe che devi localizzare in un view model, in una funzione helper o ovunque al di fuori di una vista SwiftUI, usa String(localized:) invece di una stringa semplice:

let errorMessage = String(localized: "error_generic")

Passaggio 4: Aggiungi varianti plurali e per dispositivo. Le stringhe spesso necessitano di forme diverse a seconda del contesto.

Per la pluralizzazione, inizia con la stringa nella tua vista SwiftUI:

Text("\(bookCount) books on your shelf")

Apri lo String Catalog, clicca con il tasto destro sulla chiave e scegli Vary by Plural. Xcode genera automaticamente le categorie plurali e le precompila con la stringa di origine. Per l'inglese vedrai One e Other. Correggi il campo One in "%lld book on your shelf". Contrassegnali entrambi come revisionati.

Quando in seguito invierai il catalogo a PTC, la struttura plurale viaggerà con il file. Per l'arabo, PTC genera le traduzioni per tutte e sei le categorie plurali (zero, one, two, few, many, other) perché la grammatica araba le richiede tutte e sei. Lo spagnolo ne richiede due, proprio come l'inglese.

Per le varianti per dispositivo (ad esempio, “Tap to continue” su iPhone rispetto a “Click to continue” su Mac), clicca con il tasto destro sulla chiave e scegli Vary by Device. Aggiungi i dispositivi che desideri personalizzare e inserisci la stringa appropriata per ciascuno. iOS fornisce la versione che corrisponde al dispositivo corrente a runtime.

Parte 3: Tradurre i tuoi .xcstrings con PTC

Per i piccoli progetti potresti aprire ogni colonna della lingua nel catalogo e digitare le traduzioni direttamente. Man mano che la tua app cresce, ciò diventa ingestibile con centinaia di chiavi e dozzine di lingue. PTC gestisce il caricamento, la traduzione e la sincronizzazione.

Passaggio 1: Esporta il tuo String Catalog da Xcode. Vai su Product > Export Localizations. Xcode pacchettizza il tuo String Catalog in un file .xcloc per ogni lingua di destinazione. Per PTC, hai solo bisogno del file .xcstrings all'interno del pacchetto .xcloc. Clicca con il tasto destro sul .xcloc esportato nel Finder e seleziona Show Package Contents per trovare Localizable.xcstrings.

Se visualizzi una notifica “Unable to build project for localization string extraction”, il tuo progetto utilizza API esclusive per iOS che Xcode non può compilare con il suo SDK macOS interno durante l'estrazione delle stringhe. Soluzione: seleziona il target del progetto sotto TARGETS, vai su Build Settings, cerca “Use Compiler to Extract Swift Strings” e impostalo su No. Quindi esporta di nuovo.

Passaggio 2: Iscriviti a PTC. La prova copre 20.000 parole in 2 lingue, il che è sufficiente per localizzare la maggior parte delle app. Dopo la prova, PTC funziona con pagamento a consumo (Pay-As-You-Go). Nessun abbonamento, le prime 500 parole ogni mese sono gratuite.

Passaggio 3: Configura il tuo progetto e traduci. Trascina Localizable.xcstrings in PTC. Lascia il nome del file di output come Localizable.xcstrings. Xcode si aspetta esattamente quel nome quando risolve le stringhe localizzate. Seleziona le tue lingue di destinazione.

PTC genera automaticamente una descrizione della tua app dal file caricato. Revisionale e modificala se necessario. Se hai file di traduzione esistenti, caricali in modo che PTC possa adattarsi al tuo stile. Altrimenti traduci da zero. Aggiungi i termini del glossario. PTC aggiunge il nome della tua app automaticamente. Aggiungi qualsiasi terminologia specifica del brand che dovrebbe essere tradotta in un modo specifico o non tradotta affatto. Clicca su Start Translation.

Passaggio 4: Revisiona e scarica. Una volta completata la traduzione, la scheda Translations mostra ogni stringa di origine accanto alla sua traduzione. Chiunque tu aggiunga al progetto può modificare le traduzioni direttamente. Se qualcosa non va, segnala un problema con una traduzione specifica e richiedi una ritraduzione gratuita con IA. PTC impara dal feedback e lo applica alle stringhe future nello stesso progetto.

Se una stringa tradotta supera il suo limite di lunghezza, viene evidenziata. Hai tre opzioni. Accetta la traduzione più lunga se la tua interfaccia utente può accoglierla. Richiedi una ritraduzione che rispetti il limite attuale. Regola il limite in Impostazioni > Lunghezze traduzioni.

Parte 4: Integrare i file .xcstrings tradotti nel tuo progetto Xcode

Hai tre opzioni.

Opzione 1: Scarica manualmente i file da PTC. Vai alla scheda Resource Files e scarica lo ZIP. Contiene un singolo Localizable.xcstrings con le tue stringhe di origine in inglese e tutte le traduzioni. Chiudi Xcode, sostituisci il Localizable.xcstrings esistente nella cartella del tuo progetto con quello di PTC, quindi riavvia Xcode. Le tue traduzioni appariranno nello String Catalog con un segno di spunta accanto a ogni lingua completamente tradotta.

Opzione 2: Integrazione Git. Se il tuo progetto si trova su GitHub, GitLab o Bitbucket, collega PTC direttamente. L'integrazione Git è una funzionalità Pro. Attiva Pay-As-You-Go per accedervi. Nel tuo pannello di controllo PTC, vai su Impostazioni > Merge Requests e clicca su Add Git Integration. Fornisci l'URL del tuo repository, concedi l'accesso a PTC e scegli il tuo branch e i file di origine. PTC invia una merge request con le traduzioni.

Opzione 3: Usa l'API. L'API di PTC ti dà il pieno controllo su quando e come le traduzioni vengono inserite nella tua pipeline di build. Con Pay-As-You-Go attivato, vai su Impostazioni > Gestisci token API, clicca su Add access token, quindi consulta la documentazione dell'API di PTC per gli endpoint API.

Un selettore di lingua in-app (alcune app ne hanno bisogno) può sovrascrivere il locale di sistema per singola vista tramite l'ambiente SwiftUI:

import SwiftUI

@MainActor
class LocaleManager: ObservableObject {
    @Published var currentLocale: Locale = .current

    func setLocale(_ identifier: String) {
        currentLocale = Locale(identifier: identifier)
        UserDefaults.standard.set([identifier], forKey: "AppleLanguages")
    }
}

struct LanguageSettingsView: View {
    @EnvironmentObject var localeManager: LocaleManager

    var body: some View {
        List {
            Button("English") { localeManager.setLocale("en") }
            Button("Español") { localeManager.setLocale("es") }
            Button("Français") { localeManager.setLocale("fr") }
        }
        .environment(\.locale, localeManager.currentLocale)
    }
}

La modifica di AppleLanguages a runtime richiede il riavvio dell'app per alcune stringhe di sistema. L'override dell'ambiente SwiftUI ha effetto immediato per le viste all'interno di quell'ambito.

Parte 5: Testa la tua app iOS localizzata

Testa con l'impostazione della lingua dello scheme. Il modo più rapido per testare una lingua specifica è tramite il tuo scheme di Xcode. Vai su Product > Scheme > Edit Scheme, clicca sulla scheda Options, cambia App Language e App Region con il locale che desideri ed esegui con Cmd+R. Funziona bene per la maggior parte delle lingue. Dovresti vedere lo stesso layout e design dell'inglese con tutto il testo cambiato.

Testa l'arabo e altre lingue RTL. L'impostazione della lingua dello scheme può essere inaffidabile nel Simulator per le lingue da destra a sinistra (RTL). Usa le impostazioni della lingua del Simulator stesso:

1. Esegui l'app con Cmd+R per aprire il Simulator.
2. Premi Cmd+Home per andare alla schermata iniziale.
3. Apri Settings > General > Language & Region.
4. Tocca Add Language, seleziona l'arabo e impostalo come lingua principale.
5. Il Simulator si riavvia. Apri la tua app dalla schermata iniziale.

Controlla che il testo appaia in arabo e che il layout si rifletta correttamente, con il titolo di navigazione e il contenuto allineati a destra. Per i test di anteprima senza impegnarsi in una lingua, Edit Scheme > Options > Application Language > Right-to-Left Pseudolanguage è un controllo più veloce. Per i test sull'espansione del testo, usa Double-Length Pseudolanguage per vedere come i layout gestiscono stringhe più lunghe del 30-40% prima di impegnarti con una lingua di destinazione.

Migliori pratiche per la localizzazione iOS

• Controlla la tua interfaccia utente per lunghezze di testo variabili. Il tedesco è circa il 30% più lungo dell'inglese. Francese e spagnolo circa il 20%. Usa il sistema di layout flessibile di SwiftUI, lascia che le etichette crescano e vadano a capo naturalmente, evita vincoli di larghezza fissa sugli elementi di testo e testa in alcune lingue diverse durante lo sviluppo.
• Non saltare le varianti di pluralizzazione. Il russo ha tre categorie plurali, l'arabo ne ha sei, il giapponese nessuna. Gli String Catalog gestiscono questo aspetto quando aggiungi la lingua. Assicurati che tutti i campi generati siano compilati prima di rilasciare.
• Localizza immagini e asset. Le immagini con testo o elementi visivi culturalmente specifici necessitano di varianti localizzate. In Assets.xcassets, seleziona l'immagine e nell'Attributes Inspector clicca su Localize. Scegli le lingue per cui desideri le varianti e sostituisci ciascuna con la versione appropriata. iOS fornisce l'immagine corretta in base al locale dell'utente.
• Mantieni completa la tua lingua base. La tua lingua base (di solito l'inglese) è il fallback per qualsiasi traduzione mancante. Una base incompleta può causare fallback imprevisti anche in lingue altrimenti completamente tradotte. Xcode segnala le stringhe base mancanti o non aggiornate durante la build.
• Localizza la scheda dello store dell'app. Un'app localizzata con una scheda dello store solo in inglese perde utenti in fase di scoperta. In App Store Connect puoi localizzare nome dell'app, sottotitolo, descrizione e parole chiave per territorio. Le parole chiave sono particolarmente preziose. Apple indicizza le parole chiave da più locale per territorio, moltiplicando di fatto il tuo budget di caratteri per le parole chiave oltre i 100 caratteri standard. Usa la funzionalità Paste to Translate di PTC per i contenuti dell'App Store.
• Usa formattatori sensibili al locale. Formattatori sensibili a Date.FormatStyle, Decimal.FormatStyle e Locale. Non inserire mai stringhe hardcoded per "$" o "MM/DD/YYYY".
• Usa %lld per i conteggi interi e String(localized: "You have ^[\(count) message](inflect: true)") dove si applica la concordanza grammaticale automatica di Apple.

Revisione visiva della traduzione della tua app iOS tradotta: rilascia senza QA manuale per lingua

Dopo che PTC traduce i tuoi .xcstrings, devi ancora verificare l'app in esecuzione in ogni lingua. Tradizionalmente un ciclo di QA manuale di più giorni per release. Un'etichetta tradotta potrebbe causare un overflow in una barra di navigazione in tedesco. “Send” potrebbe tradursi come un sostantivo in francese quando il pulsante richiedeva un verbo. Una stringa hardcoded in inglese all'esterno di Text(_:) risulterà palesemente non tradotta nell'app iOS in esecuzione.

L'AI Visual QA di PTC sostituisce quel ciclo. Per le app iOS native (il flusso dell'estensione del browser non si applica), usa il caricamento delle schermate. Cattura le schermate critiche dell'app in esecuzione in ogni lingua di destinazione (accesso, scheda principale, impostazioni, casi limite) e caricale su PTC. L'IA visiva di PTC ispeziona ogni schermata e:

• Corregge i problemi nei .xcstrings quando PTC li controlla. Ritraduce una parte del discorso errata, sceglie un sinonimo più corto che si adatta a una barra di navigazione, rigenera una forma plurale con la corretta concordanza grammaticale.
• Genera un prompt per Cursor / Claude Code quando il problema risiede nel tuo codice Swift. Un LocalizedStringKey mancante, un String hardcoded all'esterno del sistema di localizzazione, una frase costruita per concatenazione invece che per sostituzione.

Il risultato: un'app iOS verificata per ogni release. Non un .xcstrings tradotto con il QA manuale ancora da fare.

Traduci la scheda dello store dell'app, le note di rilascio e le notifiche push

La descrizione del tuo App Store, le note di rilascio sulle novità e il testo delle notifiche push risiedono al di fuori di Localizable.xcstrings. La funzionalità Paste to Translate di PTC gestisce questi testi nello stesso progetto. Incolla il testo di origine nel pannello di controllo di PTC, scegli le lingue di destinazione, ottieni traduzioni che usano lo stesso glossario e la stessa voce del brand delle tue stringhe in-app. Apple indicizza le parole chiave da più locale per territorio, quindi le schede dello store localizzate sono particolarmente preziose per la scoperta.

Traduci i contenuti utente in-app con l'API di PTC

Le chat in-app, i post social e le recensioni degli utenti necessitano di traduzione man mano che i contenuti arrivano. L'API REST di PTC traduce questi contenuti su richiesta con autenticazione tramite token Bearer, utilizzando lo stesso glossario e la stessa voce del brand delle tue traduzioni .xcstrings.

Risolvere la localizzazione iOS che non funziona

La causa più comune è che il file di localizzazione non è incluso nel target dell'app. Clicca su Localizable.xcstrings nel Navigator, apri il File Inspector e controlla che il target della tua app sia spuntato sotto Target Membership. Conferma inoltre che la lingua sia elencata nella sezione Localizations del tuo progetto sotto la scheda Info. Se entrambi sembrano corretti, pulisci la cartella di build con Shift+Cmd+K e ricompila.

Formati dei file di localizzazione iOS: .xcstrings, .strings, .stringsdict, .xliff

.xcstrings (String Catalog) è l'impostazione predefinita attuale da Xcode 15. Un singolo file basato su JSON che consolida tutte le stringhe, le regole plurali e le varianti specifiche per dispositivo. .strings è il formato di coppie chiave-valore legacy, ancora valido nelle vecchie codebase, abbinato a .stringsdict per i plurali. .xliff e .xcloc sono formati di esportazione per la consegna ai traduttori. Non sono formati di archiviazione.

Localizza il nome della tua app con InfoPlist.strings

Crea un file InfoPlist.strings e localizzalo per ogni lingua supportata. In ogni versione linguistica, aggiungi CFBundleDisplayName = "Your Translated App Name";. Seleziona il file nel Navigator, apri il File Inspector e clicca su Localize per aggiungere varianti linguistiche. iOS visualizza il nome dell'app corretto in base alla lingua del dispositivo.

Cambiare la lingua dell'app iOS senza riavviare

iOS non fornisce un'API nativa per questo. L'approccio standard è impostare AppleLanguages in UserDefaults e chiedere all'utente di riavviare:

UserDefaults.standard.set(["es"], forKey: "AppleLanguages")
UserDefaults.standard.synchronize()

La modifica ha effetto al successivo avvio dell'app. Se hai bisogno di cambiare lingua durante la sessione senza un riavvio, devi gestire la localizzazione manualmente caricando il bundle appropriato per la lingua selezionata.

Perché iOS usa l'inglese come fallback per le lingue non supportate

iOS usa la tua lingua base come fallback quando una traduzione non è disponibile. Questo è il comportamento previsto. Per ridurre al minimo i fallback, assicurati che il tuo String Catalog non mostri stringhe mancanti o non aggiornate prima di ogni release.

Quanto è accurata la localizzazione con IA per un'intera app iOS

PTC usa l'IA per tradurre i file .xcstrings, .strings e .stringsdict in pochi minuti, preservando automaticamente le regole plurali e i segnaposto. La maggior parte delle stringhe tradotte va in produzione senza modifiche. Per ottenere i migliori risultati, parla a PTC della tua app durante la configurazione in modo che le traduzioni riflettano il tono e la terminologia giusti.

In quali lingue iOS localizzare per prime

Spagnolo, francese, tedesco, giapponese e cinese semplificato sono punti di partenza comuni oltre all'inglese. Se la tua app ha già utenti in una regione specifica, dai priorità alla loro lingua per prima. Per il costo di adattamento più basso, inizia con lingue geograficamente o culturalmente vicine al tuo mercato di base.

Localizza la tua app iOS

Inizia con la prova di 30 giorni di PTC: 20.000 parole incluse, nessuna carta di credito. Carica il tuo Localizable.xcstrings, traducilo in pochi minuti, quindi carica le schermate e lascia che PTC verifichi l'app visualizzata.

Correlati:

• Tradurre app iOS e Android con l'IA: panoramica del servizio multipiattaforma.
• Come localizzare la tua app Android: la guida equivalente per Android Studio.
• Documentazione dell'API di PTC: endpoint REST per l'integrazione CI.