Per convalidare i segnaposto di una traduzione sul Mac, confronta la posizione, il tipo e l’uso previsto di ciascun argomento con il messaggio sorgente. Usa le diagnostiche di Xcode per individuare le discrepanze, poi esamina le sostituzioni plurali e prova l’etichetta renderizzata con valori di esempio distinti.

Questa guida è rivolta a chi esamina in Xcode le etichette localizzate di un’app per Mac. L’obiettivo è confrontare un messaggio e le sue traduzioni con i valori forniti dall’app. Tutte le etichette riportate di seguito sono esempi sintetici in inglese; illustrano i meccanismi di formattazione, non traduzioni effettive.

Cosa comprende il contratto degli argomenti di un messaggio?

Il contratto degli argomenti è una scheda di revisione che descrive i valori ricevuti da un messaggio: posizioni, tipi di formattazione, significati e usi previsti. È una lista di controllo pratica ricavata dal codice sorgente e dal catalogo, non un formato di file Apple separato.

String.LocalizationValue di Swift supporta stringhe localizzabili con valori di runtime interpolati. La documentazione distingue inoltre l’uso del testo sorgente come chiave di localizzazione dalla fornitura di una chiave e di un valore predefinito separati. Di conseguenza, un identificatore da solo potrebbe non rivelare gli argomenti del messaggio: esamina il testo sorgente predefinito e il punto in cui viene chiamato. String.LocalizationValue

Considera la stringa di formato Added %lld items to %@. In questo esempio, l’app fornisce un conteggio intero seguito da un’etichetta di raccolta basata su un oggetto. Prima di modificare la traduzione, annota il contratto:

Posizione dell’argomento Significato Formato previsto Valore d’esempio
1 Numero di elementi aggiunti %lld 7
2 Etichetta della raccolta di destinazione %@ Canvas

Il riferimento di Apple ai formati definisce %@ come conversione di un oggetto, %d come intero con segno a 32 bit, %f come conversione di un double e ll come modificatore di lunghezza intera per long long. Documenta anche forme posizionali come %1$@. Conserva tutte le informazioni sul tipo: cambiare %lld in %d modifica il tipo intero previsto. Il riferimento è archiviato, quindi usalo per la sintassi dei formati insieme alla documentazione attuale dei cataloghi. String Format Specifiers

Aggiungi al verbale di revisione anche il significato degli argomenti, persino quando hanno lo stesso tipo. Per Moved %@ to %@, un controllo dei tipi non permette di distinguere l’etichetta dell’elemento da quella della destinazione. Una sintassi corretta deve comunque mantenere la relazione giusta tra i valori e le parole.

Come si individua la fonte autorevole in Xcode?

Apri il progetto in Xcode e individua il catalogo che contiene il messaggio. Se la fonte è cambiata, scegli Product > Build per aggiornare le stringhe estratte. Seleziona il catalogo nel navigatore del progetto, scegli Editor > Assistant e seleziona la chiave del messaggio per visualizzarne la fonte. Apple documenta questo flusso di lavoro per individuare e aggiornare le voci del catalogo. Localizing and varying text with a string catalog

Verifica quali valori fornisce effettivamente il punto di chiamata, in quale ordine e tramite quale API di localizzazione. Apple consiglia API localizzabili come String(localized:); un inizializzatore con un defaultValue separato usa il primo parametro come chiave e il secondo come stringa sorgente predefinita. Questo è importante quando il messaggio è associato a un identificatore neutro come collection.added.summary. Preparing your app’s text for translation

Registra insieme tre elementi: il catalogo e la chiave, il testo sorgente predefinito e i significati e tipi degli argomenti nell’ordine in cui compaiono. Se non concordano, risolvi la discrepanza prima di modificare le traduzioni. Altrimenti, potresti far corrispondere una traduzione a una fonte obsoleta invece che agli input attuali dell’app.

Aggiungi anche un contesto utile per le modifiche future. Apple supporta i commenti sulle stringhe localizzabili per spiegarne l’uso. Un commento sintetico utile potrebbe specificare che l’argomento 1 è il conteggio degli elementi e l’argomento 2 è l’etichetta della raccolta di destinazione. Così il localizzatore riceve informazioni che uno specificatore di formato non può esprimere. Preparing your app’s text for translation

Come si controllano conteggi, tipi e posizioni degli argomenti?

Apple ha introdotto la convalida dei cataloghi di stringhe per individuare problemi comuni, tra cui specificatori di formato non corrispondenti, e per alcuni problemi sono disponibili correzioni. Esamina le eventuali diagnostiche che Xcode mostra per la voce. Considera le correzioni proposte come riparazioni sintattiche e verifica che preservino il significato del messaggio. Build multilingual-ready apps

Per un messaggio semplice senza sostituzioni plurali, segui questa sequenza di revisione:

  1. Individua ogni segnaposto che usa un argomento nel testo sorgente e in quello candidato.
  2. Assegna ogni segnaposto alla posizione del rispettivo argomento.
  3. Confronta il tipo di formato completo con il contratto.
  4. Verifica che ogni valore richiesto compaia nel punto previsto dal testo.
  5. Esamina singolarmente i riferimenti aggiunti, omessi o ripetuti.

La notazione posizionale consente di cambiare l’ordine delle parole in una traduzione mantenendo l’identità degli argomenti. In %2$@: added %1$lld items, il primo segnaposto visibile fa riferimento all’argomento 2 e il secondo all’argomento 1. Apple documenta la sintassi posizionale n$. String Format Specifiers

La tabella seguente si applica al contratto d’esempio con due argomenti. Sono esiti di revisione proposti, non il risultato dell’esecuzione di Xcode:

Testo candidato con formati Esito della revisione Motivo
Added %lld items to %@ Corrisponde al contratto semplice Prima il conteggio, poi la destinazione
%2$@: added %1$lld items Corrisponde dopo il riordino Le posizioni esplicite mantengono l’identità di entrambi gli argomenti
Added %d items to %@ Correggere il tipo intero L’argomento 1 non usa più il modificatore di lunghezza previsto
Added %lld items Esaminare l’omissione Manca la destinazione richiesta da questo messaggio
Added %1$lld items to %1$@ Correggere i riferimenti L’argomento 1 è richiamato con tipi in conflitto; l’argomento 2 manca
Added %1$lld items to %2$@ (%2$@) Esaminare la ripetizione Ci sono tre occorrenze, ma solo due argomenti distinti richiamati

Tieni separati il numero di occorrenze e quello degli argomenti distinti. L’ultima riga illustra proprio questa differenza: ripetere l’argomento 2 non crea un terzo valore fornito. Decidere se la ripetizione sia appropriata nel testo è una scelta editoriale. Per questa revisione, segnalala finché non ne è chiaro lo scopo.

Allo stesso modo, non contare ogni carattere percentuale come un argomento. Apple definisce %% come un segno di percentuale letterale. Un’etichetta di formato come Scale: %lld%% contiene un segnaposto di valore e un segno di percentuale con escape. String Format Specifiers

Perché le sostituzioni plurali richiedono un controllo diverso?

I messaggi al plurale richiedono di esaminare sia il meccanismo di selezione sia il testo che visualizza un valore. Nella sessione sui cataloghi di stringhe, Apple spiega che le sostituzioni possono contenere dizionari di casi plurali. L’inspector mostra la posizione dell’argomento di controllo e lo specificatore di formato in stile C. Una sostituzione può quindi dipendere da un argomento anche quando un ramo specifico non lo visualizza in forma numerica. Discover String Catalogs

Per un messaggio sintetico sul conteggio degli elementi, confronta One item added con %lld items added. Il primo ramo scrive la quantità in lettere; il secondo la visualizza. Una regola che esiga lo stesso numero di segnaposto visibili in ogni ramo rifiuterebbe inutilmente il primo. La documentazione Apple sul comportamento dei dizionari stringsdict consente esplicitamente di omettere lo specificatore di formato numerico nelle forme plurali e indica la scrittura in lettere del numero come un’opzione. Stringsdict file format

Segui invece questa revisione, che tiene conto dei rami:

  • Verifica nell’inspector la posizione e il tipo dell’argomento che controlla la sostituzione.
  • Esamina ogni ramo plurale presente per la localizzazione di destinazione.
  • Confronta ogni segnaposto visualizzato con l’argomento a cui fa riferimento.
  • Spiega ogni omissione di una visualizzazione numerica in base al testo del ramo.
  • Controlla separatamente gli altri argomenti del messaggio: scrivere un conteggio in lettere non spiega l’assenza di un’etichetta di raccolta.

Per due conteggi che variano indipendentemente, mantieni distinti i loro ruoli. Un messaggio sintetico su elementi e raccolte deve usare il conteggio degli elementi per controllare la sostituzione degli elementi e quello delle raccolte per controllare la sostituzione delle raccolte. Apple documenta più sostituzioni in un singolo messaggio e spiega che l’output in fase di esecuzione combina i rispettivi casi plurali selezionati. Discover String Catalogs

Come si conferma il messaggio corretto sul Mac?

Dopo aver corretto la voce, compila l’app ed esamina le eventuali diagnostiche rimaste nel catalogo. Poi esegui la schermata pertinente nella localizzazione di destinazione. Il flusso di lavoro supportato da Apple consiste nello scegliere Product > Scheme > Edit Scheme, selezionare Run, aprire Options, scegliere App Language e l’App Region appropriata, fare clic su Close ed eseguire la destinazione selezionata. Testing localizations when running your app

Scegli valori di esempio che rendano visibili gli scambi. Per due argomenti di conteggio, usa numeri diversi, ad esempio 2 e 7. Per due argomenti di testo, usa etichette distinte come Tile e Canvas. Sono input di prova illustrativi: servono a rivelare quale valore fornito compare in ciascuna parte del messaggio.

Per i messaggi con forme plurali, prova valori che raggiungano i rami in esame. Quando due sostituzioni variano indipendentemente, includi combinazioni in cui cambia un conteggio mentre l’altro resta fisso. Esamina sia il testo selezionato sia la posizione di ogni valore visualizzato. Se una combinazione viene renderizzata correttamente, gli altri rami restano da esaminare.

Tieni separato lo stato della traduzione dal controllo del contratto. Apple descrive il segno di spunta verde del catalogo come indicatore dello stato di traduzione dopo l’inserimento del testo. Registra i controlli effettivamente eseguiti — corrispondenza degli argomenti, confronto dei tipi, esame dei rami ed esempi renderizzati — invece di considerare quell’indicatore come prova di tutti e quattro. Localizing and varying text with a string catalog

Il messaggio è pronto per passare alla fase successiva quando i suoi segnaposto corrispondono agli argomenti forniti previsti, i tipi coincidono e ogni omissione o ripetizione specifica di un ramo ha una spiegazione chiara. Tenere questo contratto sintetico accanto al messaggio rende più semplice valutare la prossima modifica alla fonte o alla traduzione.

Fonti