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

Prepara la tua app Xcode, traduci i .xcstrings con l'IA, quindi carica le schermate in modo che PTC (Private Translation Cloud) esegua la revisione dell'app iOS renderizzata in ogni lingua. Questa guida illustra l'intero workflow 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 aree geografiche. Con gli String Catalog introdotti in Xcode 15, il workflow è nettamente più semplice rispetto al vecchio approccio con .strings / .stringsdict.

Internazionalizzazione vs. localizzazione

Si tratta di due fasi distinte e devono avvenire in questo ordine:

• L'internazionalizzazione (i18n) è il lavoro tecnico di base. Strutturi il codice in modo che testi, 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à post-lancio, per poi scoprire che la base di codice non è pronta. Tornare indietro per correggere stringhe hardcoded, layout a direzione fissa e formattatori che non tengono conto del locale in un'app esistente richiede molto più tempo rispetto allo sviluppo con la localizzazione in mente fin dall'inizio.

Come Xcode 15+ usa Localizable.xcstrings come unica fonte di verità

Il modello di localizzazione di Apple in Xcode 15+ si concentra 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 stringa che usa LocalizedStringKey). L'esecuzione della build della tua app popola Localizable.xcstrings con ogni stringa di origine estratta.

Apple supporta diversi formati: .strings (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. Nella scheda Info, scorri fino a Localizations. L'inglese è già elencato come lingua base. Fai clic su + per aggiungere ogni lingua di destinazione (spagnolo, francese, arabo, ecc.).

Passaggio 2: Crea uno String Catalog. Fai clic con il tasto destro sul tuo progetto e seleziona New File from Template. Cerca String Catalog e aggiungilo. Mantieni il nome predefinito Localizable.xcstrings. Compila il 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 azione di 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 in modo silenzioso:

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 all'esterno 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 hanno spesso bisogno 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, fai clic 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 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 es., “Tap to continue” su iPhone rispetto a “Click to continue” su Mac), fai clic 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 serve la versione che corrisponde al dispositivo corrente a runtime.

Parte 3: Tradurre i tuoi .xcstrings con PTC

Per piccoli progetti potresti aprire ogni colonna della lingua nel catalogo e digitare direttamente le traduzioni. Man mano che la tua app cresce, ciò diventa ingestibile con centinaia di chiavi e decine 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 lingua di destinazione. Per PTC, hai bisogno solo del file .xcstrings all'interno del pacchetto .xcloc. Fai clic con il tasto destro sul file .xcloc esportato nel Finder e seleziona Show Package Contents per trovare Localizable.xcstrings.

Se vedi una notifica “Unable to build project for localization string extraction”, il tuo progetto usa 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: Registrati a PTC. La prova copre 20.000 parole in 2 lingue, che sono sufficienti per localizzare la maggior parte delle app. Dopo la prova, PTC funziona in 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 quel nome esatto 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 automaticamente il nome della tua app. Aggiungi qualsiasi terminologia specifica del brand che dovrebbe essere tradotta in un modo specifico o non tradotta affatto. Fai clic 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 l'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 UI può ospitarla. Richiedi una ritraduzione che si adatti al limite attuale. Modifica il limite in Impostazioni > Lunghezze traduzioni.

Parte 4: Integrare i .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 il Pay-As-You-Go per accedervi. Nel tuo pannello di controllo PTC, vai su Impostazioni > Merge Requests e fai clic 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 il Pay-As-You-Go attivato, vai su Impostazioni > Gestisci token API, fai clic su Add access token, quindi consulta la reference dell'API PTC per gli endpoint.

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. La sovrascrittura dell'ambiente SwiftUI ha effetto immediato per le viste all'interno di quell'ambito.

Parte 5: Testare 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, fai clic sulla scheda Options, cambia App Language e App Region nel 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 tutti i testi cambiati.

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

1. Esegui l'app con Cmd+R per aprire il Simulatore.
2. Premi Cmd+Home per andare alla schermata iniziale.
3. Apri Impostazioni > Generali > Lingua e zona.
4. Tocca Aggiungi lingua, seleziona l'arabo e impostalo come lingua principale.
5. Il Simulatore si riavvia. Apri la tua app dalla schermata iniziale.

Verifica 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 test di anteprima senza impegnarti con una lingua, Edit Scheme > Options > Application Language > Right-to-Left Pseudolanguage è un controllo più rapido. 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.

Best practice per la localizzazione iOS

• Controlla la tua UI per lunghezze di testo variabili. Il tedesco è circa il 30% più lungo dell'inglese. Il francese e lo spagnolo circa il 20%. Usa il sistema di layout flessibile di SwiftUI, lascia che le etichette crescano e vadano a capo naturalmente, evita vincoli a larghezza fissa sugli elementi di testo e testa in diverse lingue 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 del rilascio.
• 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 fai clic su Localize. Scegli le lingue per cui desideri le varianti e sostituisci ciascuna con la versione appropriata. iOS serve 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 (stale) durante la build.
• Localizza la tua scheda dello store dell'app. Un'app localizzata con una scheda solo in inglese perde utenti nella fase di scoperta. In App Store Connect puoi localizzare il nome dell'app, il sottotitolo, la descrizione e le 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 che tengono conto del locale. Formattatori compatibili con Date.FormatStyle, Decimal.FormatStyle e Locale. Non inserire mai hardcoded "$" 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 ha tradotto 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 andare in overflow in una barra di navigazione in tedesco. “Send” potrebbe essere tradotto come sostantivo in francese quando il pulsante richiedeva un verbo. Una stringa inglese hardcoded all'esterno di Text(_:) risulterà palesemente non tradotta nell'app iOS in esecuzione.

L'AI Visual QA di PTC sostituisce quel passaggio. 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 release. Non un .xcstrings tradotto con il QA manuale ancora da fare.

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

La descrizione del tuo App Store, le note di rilascio con le novità e il testo delle notifiche push si trovano all'esterno di Localizable.xcstrings. La funzionalità Paste to Translate di PTC gestisce quei testi nello stesso progetto. Incolla il testo di origine nel pannello di controllo 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 localizzate sono particolarmente preziose per la scoperta.

Traduci i contenuti utente in-app con l'API 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 Bearer-token, utilizzando lo stesso glossario e la stessa voce del brand delle tue traduzioni .xcstrings.

Risolvere problemi di localizzazione iOS che non funziona

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

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

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

Localizzare 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 fai clic su Localize per aggiungere le 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 il fallback all'inglese 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 (stale) prima di ogni release.

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

PTC usa l'IA per tradurre file .xcstrings, .strings e .stringsdict in pochi minuti, preservando automaticamente le regole dei plurali e i segnaposto. La maggior parte delle stringhe tradotte va in produzione senza modifiche. Per ottenere i migliori risultati, fornisci a PTC informazioni sulla 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 il minor costo di adattamento, 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 offerte da noi, nessuna carta di credito. Carica i tuoi Localizable.xcstrings, traducili in pochi minuti, quindi carica le schermate e lascia che PTC verifichi l'app renderizzata.

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.
• Reference dell'API PTC: endpoint REST per l'integrazione CI.