# General Translation Knowledge Base: Come si localizza un'app iOS con gli String Catalog? URL: https://generaltranslation.com/it/kb/localize-ios-app.mdx Docs index: https://generaltranslation.com/llms.txt Description: Aggiungi le lingue in Xcode, scrivi il testo visibile all'utente con API localizzabili come Text di SwiftUI e String(localized:), quindi esegui la build affinché Xcode raccolga queste stringhe in uno String Catalog (.xcstrings). Traduci in Xcode, tramite XLIFF o con la CLI di General Translation se vuoi che i cataloghi si aggiornino a ogni rilascio e condividano la terminologia con il tuo sito web e la tua app Android. Category: Internazionalizzazione Last updated: 2026-10-20 Authors: Kevin Wu, Jackie Chen Published: 2026-10-20 Uno String Catalog raccoglie in un unico file JSON una tabella di stringhe in tutte le lingue, e Xcode lo sincronizza con il codice a ogni build. A te restano quindi due compiti: far confluire nel catalogo ogni stringa visibile all'utente e reinserirvi traduzioni di qualità. ## Configurare la localizzazione in Xcode ### Aggiungi le tue lingue Nell'editor del progetto, seleziona il progetto, apri **Info** e fai clic sul pulsante di aggiunta sotto **Localizations** (ce n'è uno anche nella barra laterale dell'editor dello String Catalog). Ogni voce ha un ID lingua come `de`, `ja` o `en-IN` ([Apple: Adding support for languages and regions](https://developer.apple.com/documentation/xcode/adding-support-for-languages-and-regions)). Scegli una variante regionale solo se il testo cambia, come nel caso di `pt-BR` e `pt-PT`. (Vedi [codici locale](/docs/platform/core/guides/locale-codes)). ### Aggiungere uno String Catalog ed eseguire la build Scegli **File > New > File from Template**, filtra per "string" e seleziona **String Catalog**. Il nome predefinito è `Localizable.xcstrings`. Poi scegli **Product > Build**: Xcode rileva le stringhe localizzabili nel codice e le aggiunge al catalogo, che verrà poi aggiornato a ogni build successiva ([Apple: Localizing and varying text with a string catalog](https://developer.apple.com/documentation/xcode/localizing-and-varying-text-with-a-string-catalog)). Gli String Catalog sono stati introdotti con Xcode 15 ([note di rilascio](https://developer.apple.com/documentation/xcode-release-notes/xcode-15-release-notes)). In fase di compilazione vengono convertiti in file `.strings` e `.stringsdict`, quindi per adottarli non è necessario alzare il target minimo di distribuzione ([WWDC23: Discover String Catalogs](https://developer.apple.com/videos/play/wwdc2023/10155/)). ### Scrivere il testo con API localizzabili Xcode estrae solo le stringhe passate ad API localizzabili. In SwiftUI, i letterali stringa nelle viste sono valori [`LocalizedStringKey`](https://developer.apple.com/documentation/swiftui/localizedstringkey) e vengono estratti automaticamente. Negli altri casi, usa `String(localized:)` ([Apple: Preparing your app's text for translation](https://developer.apple.com/documentation/xcode/preparing-your-apps-text-for-translation)): ```swift import SwiftUI struct CartView: View { let itemCount: Int let couponCode: String var body: some View { VStack { // I letterali stringa nelle viste SwiftUI sono valori LocalizedStringKey, // quindi Xcode li aggiunge allo String Catalog durante la build. Text("Your cart") // L'interpolazione diventa uno specificatore di formato (%lld) che puoi declinare in base al plurale. Text("\(itemCount) items") // Un commento indica ai traduttori dove e come viene usato il testo. Text("Checkout", comment: "Button that starts payment for the items in the cart.") // Una variabile String viene visualizzata così com'è. Text(verbatim:) lo rende esplicito. Text(verbatim: couponCode) } } } // Al di fuori delle viste SwiftUI, crea il testo localizzabile con String(localized:). let emptyCartMessage = String( localized: "Your cart is empty", comment: "Shown when the cart has no items." ) ``` L'errore più comune è `Text(someString)`: una variabile `String` non viene cercata nel catalogo. Per passare testo localizzabile tra le view, usa `LocalizedStringResource`, il tipo consigliato da Apple, che include anche un commento e il nome della tabella. I commenti sono importanti perché "Checkout" da solo potrebbe essere un sostantivo o un verbo. Aggiungili con il parametro `comment:`, oppure fai Control-clic su una chiave nel catalogo e scegli **Generate Comment** per farne generare uno a Xcode a partire dal codice circostante. Per individuare il testo che non è mai finito nel catalogo, apri **Product > Scheme > Edit Scheme > Run > Options** e attiva **Show non-localized strings**: durante l'esecuzione dell'app, quelle stringhe verranno renderizzate tutte in maiuscolo ([Apple: Preparing your interface for localization](https://developer.apple.com/documentation/xcode/preparing-your-interface-for-localization)). (Vedi [Come faccio a trovare le stringhe hardcoded non tradotte?](/kb/find-hardcoded-strings)). ## Gestire plurali, dispositivi e Info.plist Fai Control-clic su una chiave con un numero interpolato e scegli **Vary by Plural**. Xcode aggiunge le categorie di plurale richieste da ciascuna lingua: `one` e `other` per l'inglese, `one`, `few`, `many` e `other` quando aggiungi il russo. **Vary by Device** assegna a una chiave un valore diverso per ciascun dispositivo, ad esempio "Tap to learn more" su iPhone e "Click to learn more" su Mac. Dietro l'editor, il catalogo è un file JSON, che genera diff puliti nelle pull request. Ecco un breve estratto con un plurale in inglese e una traduzione in spagnolo: ```json title="Localizable.xcstrings" { "sourceLanguage" : "en", "strings" : { "%lld items" : { "comment" : "Number of items in the shopping cart.", "localizations" : { "en" : { "variations" : { "plural" : { "one" : { "stringUnit" : { "state" : "translated", "value" : "%lld item" } }, "other" : { "stringUnit" : { "state" : "translated", "value" : "%lld items" } } } } } } }, "Checkout" : { "comment" : "Button that starts payment for the items in the cart.", "localizations" : { "es" : { "stringUnit" : { "state" : "translated", "value" : "Pagar" } } } } }, "version" : "1.0" } ``` Il testo destinato al sistema in `Info.plist`, come il nome visualizzato dell'app e le descrizioni d'uso nelle richieste di permesso, va inserito in un catalogo separato. Aggiungi un file `InfoPlist.xcstrings` al target e, a ogni build, Xcode lo popolerà con le chiavi localizzabili note di `Info.plist`. ## Monitorare lo stato delle stringhe Ogni traduzione nel catalogo ha uno stato, indicato nella colonna **State** dell'editor: * **New:** non ancora tradotta in quella lingua. * **Needs Review:** il testo sorgente è cambiato dopo la traduzione, oppure qualcuno l'ha segnalata; scegli **Mark as Reviewed** per mantenere il valore attuale. * **Translated:** contrassegnata da un segno di spunta verde; non serve fare altro. * **Stale:** Xcode non trova più la stringa nel codice. Le stringhe non tradotte che scompaiono dal codice vengono rimosse; quelle tradotte vengono conservate e contrassegnate come obsolete finché non le elimini. Le stringhe aggiunte a mano, come le chiavi generate a runtime, possono essere impostate sulla gestione manuale, così le build non le aggiorneranno né le rimuoveranno mai. ## Migrare da .strings e .stringsdict Per convertire un progetto esistente, scegli **Edit > Convert > To String Catalog** (oppure fai Control-clic su un file e scegli **Migrate to String Catalog**). La migrazione avviene file per file e target per target, e durante la migrazione i cataloghi possono coesistere con i file legacy. Un catalogo e un file `.strings` o `.stringsdict` con lo stesso nome nello stesso target generano un errore di build, quindi completa ogni tabella prima di passare alla successiva. Migrando `InfoPlist.strings` si conservano gli eventuali commenti. ## Scegliere come tradurre Questi approcci inseriscono le traduzioni nel catalogo: | Approccio | Chi traduce | Contesto fornito al traduttore | Ripetibile a ogni rilascio | Cosa resta a tuo carico | | ------------------------------------------------------------------------------------------------- | ------------------------------------- | --------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | Inserimento manuale nell'editor del catalogo | Tu o un collega bilingue | L'intera app | No | Ogni stringa in ogni lingua, a mano | | Agente di programmazione di Xcode (Xcode 27) | L'agente che abiliti in Xcode | Dove viene usata ogni stringa, stringhe simili, esigenze di plurale, guide di stile linguistiche di Apple | Eseguito su richiesta in Xcode | Configurazione dell'agente, revisione delle stringhe tradotte automaticamente, allineamento della terminologia con le app web e Android | | Esportazione di `.xcloc` e XLIFF verso traduttori o un sistema di gestione delle traduzioni (TMS) | Traduttori professionisti | Commenti, più gli screenshot che aggiungi alla cartella `Notes` | Automatizzabile con `xcodebuild` | Un ciclo di andata e ritorno per ogni rilascio, con i relativi tempi di attesa | | CLI di General Translation | Il servizio di traduzione di GT | Commenti del catalogo, più Glossario e prompt personalizzati condivisi | Esegui [`gt translate`](/docs/cli/reference/commands/translate) prima della build | Revisione nella dashboard o in Xcode, poi test dell'app | | Script di traduzione automatica o un LLM applicato al JSON | Un modello o un'API di traduzione | Ciò che invia il tuo script | Sì | Varianti, sostituzioni, categorie di plurale per lingua, specificatori di formato, stati e revisione | **Esportazione.** **Product > Export Localizations** crea un Xcode Localization Catalog (una cartella `.xcloc`) per ogni lingua, contenente un file XLIFF ([Apple: Exporting localizations](https://developer.apple.com/documentation/xcode/exporting-localizations)). Attiva l'impostazione di build **Use Compiler to Extract Swift Strings** in modo che l'esportazione includa tutte le stringhe Swift. Reimporta le traduzioni con **Product > Import Localizations**, oppure automatizza entrambe le operazioni con `xcodebuild -exportLocalizations` e `xcodebuild -importLocalizations` ([Apple: Importing localizations](https://developer.apple.com/documentation/xcode/importing-localizations)). **Novità di Xcode 27.** Gli agenti in Xcode ora possono tradurre gli String Catalog: Xcode aggiunge le lingue, crea gli String Catalog mancanti e fornisce all'agente il contesto di ogni stringa ([note di rilascio di Xcode 27](https://developer.apple.com/documentation/xcode-release-notes/xcode-27-release-notes), [WWDC26: Translate your app using agents in Xcode](https://developer.apple.com/videos/play/wwdc2026/213/)). L'editor del catalogo si arricchisce di un pulsante **Generate Translations**, l'output dell'agente riceve lo stato **Machine Translated** e l'XLIFF esportato lo contrassegna con `state-qualifier="leveraged-mt"`. Un commento di localizzazione "do not translate" ora contrassegna la stringa come **Don't Translate** nel catalogo e con `translate="no"` nell'XLIFF. Puoi far puntare `AGENTS.md` o `CLAUDE.md` a un file `TRANSLATION.md` contenente un glossario e un elenco di stringhe che l'agente non deve tradurre ([Apple: Localizing your app using agents](https://developer.apple.com/documentation/xcode/localizing-your-app-using-agents)). Usa l'editor del catalogo per una o due lingue che conosci. Usa l'agente di Xcode se vuoi la traduzione automatica direttamente in Xcode. Scegli General Translation quando ti servono un comando ripetibile nel repository e una terminologia condivisa tra i prodotti, senza rinunciare a Xcode e alle API di localizzazione native di Apple. Usa un'esportazione XLIFF quando il lavoro è affidato a traduttori professionisti o a un [TMS](/kb/what-is-a-translation-management-system) già in uso. ## Testare ogni lingua Scegli **Product > Scheme > Edit Scheme**, seleziona **Run**, poi **Options**, e imposta **App Language** e **App Region** per l'esecuzione successiva ([Apple: Testing localizations](https://developer.apple.com/documentation/xcode/testing-localizations-when-running-your-app)). Lo stesso menu **App Language** include anche le pseudolingue: **Double-Length** per l'espansione del testo, **Right-to-Left** per i layout speculari, **Accented** e **Tall** per i glifi più alti e **Bounded String** per il troncamento. (Vedi [Che cos'è la pseudo-localizzazione?](/kb/pseudo-localization)). Per le anteprime SwiftUI, imposta `.environment(\.locale, .init(identifier: "de"))`. I metadati dell'App Store (nome, descrizione, screenshot) si localizzano separatamente in [App Store Connect](https://developer.apple.com/help/app-store-connect/manage-app-information/localize-app-information). ## Tradurre gli String Catalog con General Translation Se vuoi eseguire la traduzione come comando ripetibile e mantenere una terminologia coerente tra la tua app iOS, il sito web e l'app Android, la CLI di General Translation, `gt`, traduce i file `.xcstrings` in-place (`gt` 2.21.0 o versioni successive). Aggiungi a `gt.config.json` una voce `xcstrings` che punti direttamente a ciascun catalogo: ```json title="gt.config.json" { "defaultLocale": "en", "locales": ["es", "ja"], "files": { "xcstrings": { "include": ["Resources/Localizable.xcstrings", "Resources/InfoPlist.xcstrings"] } } } ``` Tutte le impostazioni regionali si trovano nello stesso file, quindi i percorsi `include` non contengono il segnaposto `[locale]`, e il valore `sourceLanguage` del catalogo deve corrispondere a `defaultLocale`, altrimenti l'esecuzione si interrompe prima del caricamento. Accedi con [`npx gt login`](/docs/cli/reference/commands/login), imposta `GT_PROJECT_ID` ([credenziali della CLI](/docs/cli/guides/configuring#credentials)) e, se l'app esiste già, importa la sorgente e le traduzioni revisionate con [`npx gt upload`](/docs/cli/reference/commands/upload). Poi esegui [`npx gt translate`](/docs/cli/reference/commands/translate) per generare gli aggiornamenti. In CI, salva come `GT_API_KEY` una chiave API di progetto con i permessi **Files > Write** e **Translation queue > Enabled**. La CLI carica solo la porzione nella lingua sorgente e unisce (merge) ogni impostazione regionale di destinazione nel file, preservando le altre impostazioni regionali e la struttura del catalogo. Nell'elaborazione degli String Catalog, la traduzione delle varianti segue le categorie di plurale della lingua di destinazione, e gli specificatori di formato e le sostituzioni vengono preservati. (Consulta il [riferimento `.xcstrings`](/docs/cli/reference/formats/xcstrings-files).) Con il layout legacy, si usano invece le chiavi `dotStrings` e `dotStringsdict` per tradurre i file `.strings` e [`.stringsdict`](/docs/cli/reference/formats/dot-stringsdict-files). Revisiona il catalogo in Xcode oppure usa l'[editor di file raw](/docs/platform/dashboard/guides/reviewing-translations) della dashboard. Se modifichi le traduzioni in Xcode, esegui [`npx gt save-local`](/docs/cli/reference/commands/save-local) affinché le esecuzioni successive le mantengano. Assegna un unico [gruppo di contesto](/docs/platform/dashboard/guides/defining-context-for-translations) ai tuoi progetti iOS, web e [Android](/docs/cli/reference/formats/android-strings-files): così un termine del Glossario, come i nomi dei tuoi piani, resta identico in ogni area del prodotto. Ramp usa GT per oltre 11 impostazioni regionali nella propria dashboard, nella landing page e nell'app iOS: un esempio di come un'unica piattaforma di traduzione possa servire sia prodotti web sia nativi. (Consulta le [distribuzioni in produzione](https://generaltranslation.com/enterprise).) ## Punti chiave * Esegui una build dopo aver aggiunto `Localizable.xcstrings`: Xcode estrae i letterali SwiftUI e il testo di `String(localized:)`, ma non i `Text` costruiti a partire da una variabile `String`. * Usa **Vary by Plural** per i conteggi: Xcode aggiunge le categorie previste da ciascuna lingua, ad esempio quattro per il russo. * Le stringhe tradotte rimosse dal codice non scompaiono, ma diventano **Stale**: eliminale quindi in modo esplicito. * Xcode 27 introduce la traduzione tramite agente, lo stato **Machine Translated** e `leveraged-mt` nei file XLIFF esportati. * La CLI di General Translation traduce il catalogo in-place con `"xcstrings": { "include": [...] }` e [`npx gt translate`](/docs/cli/reference/commands/translate): genera le varianti nelle lingue di destinazione mantenendo intatte la struttura del catalogo e le impostazioni regionali non interessate. ## Related questions - [Che cos'è la pseudo-localizzazione?](https://generaltranslation.com/it/kb/pseudo-localization.mdx): La pseudo-localizzazione è un test che sostituisce il testo di origine con una versione alterata, con caratteri accentati, allungata di circa il 40% e racchiusa tra parentesi quadre, così che stringhe hardcoded, troncamenti, font che non vengono visualizzati correttamente e frasi concatenate emergano prima ancora che esista una traduzione. Android include a questo scopo le pseudo-impostazioni regionali en-XA e ar-XB. - [Come si trovano le stringhe hardcoded non tradotte?](https://generaltranslation.com/it/kb/find-hardcoded-strings.mdx): Esegui in CI un linter che segnali i letterali stringa visibili all'utente, come la regola no-literal-string di eslint-plugin-i18next per JSX, il controllo HardcodedText di Android Lint o il linter HardCodedString di erb_lint per Rails. Poi naviga nell'app con una pseudo-impostazione regionale per individuare il testo che i controlli statici non riescono a tracciare. - [Come si supportano le lingue RTL (right-to-left) in CSS?](https://generaltranslation.com/it/kb/right-to-left-css.mdx): Imposta dir="rtl" e lang sull'elemento html, perché lang da solo non cambia la direzione, poi sostituisci le proprietà CSS fisiche come margin-left con proprietà logiche come margin-inline-start. Le righe flex, le colonne della griglia e l'allineamento predefinito del testo si invertono da sole; translateX(), left e right no. - [General Translation e un TMS (Crowdin, Lokalise, Phrase) a confronto](https://generaltranslation.com/it/kb/general-translation-vs-tms.mdx): Scegli General Translation quando gli sviluppatori vogliono una generazione delle traduzioni, un contesto derivato dal codice e una revisione collegati ai rilasci del prodotto. Puoi mantenere i cataloghi e la libreria di rendering che usi già, oppure scrivere JSX inline senza chiavi di traduzione. Un TMS è adatto a programmi incentrati su fornitori linguistici, editor CAT e scambio di file XLIFF; le sue integrazioni possono automatizzare il trasferimento dei file. ## Previous and next questions - Previous question: [Come assegnare i nomi alle chiavi di traduzione i18n?](https://generaltranslation.com/it/kb/i18n-key-naming.mdx) - Next question: [Come si rende multilingue un sito web?](https://generaltranslation.com/it/kb/make-website-multilingual.mdx) ## Sitemap See the [Knowledge Base sitemap](https://generaltranslation.com/it/kb/sitemap.md) for every article.