Panoramica
Marchi globali, compagnie aeree, eventi internazionali e catene retail emettono spesso pass wallet destinati a clienti in aree linguistiche diverse. Passinstance offre un motore nativo di localizzazione multilingua che compila stringhe e asset localizzati in:
-
Bundle
.lprojper Apple Wallet: dizionari di stringhe standard Apple PassKit (<language>.lproj/pass.strings) impacchettati direttamente nell'archivio.pkpassinsieme alle immagini localizzate. -
Risorse
LocalizedStringper Google Wallet: strutture API Google Wallet con stringhe di fallback e traduzioni specifiche per lingua (translatedValues[]).
Quando un cliente installa un pass, iOS e Android rilevano automaticamente le impostazioni di lingua e area geografica del sistema operativo, mostrando etichette dei campi, valori, notifiche sulla schermata di blocco e grafiche del brand nella sua lingua madre — senza dover mantenere modelli separati.
Architettura di sistema: compilazione multilingua PassKit e Google
La gerarchia di fallback linguistico a 4 livelli
Quando un dispositivo mobile renderizza un pass localizzato, Passinstance applica una gerarchia di risoluzione a 4 livelli affinché il testo non appaia mai vuoto o corrotto:
-
1
Corrispondenza locale esatta: se il dispositivo richiede
de-AT(tedesco – Austria) ed esiste un dizionariode-AT, questo viene caricato per primo. -
2
Corrispondenza lingua base: se
de-ATè assente, il motore ripiega sude(tedesco). -
3
Lingua primaria del modello: se anche
deè assente, il motore utilizza la lingua base canonica del modello (predefinita:en). -
4
Prima traduzione disponibile: se mancano le stringhe di base, il compilatore mostra la prima stringa tradotta disponibile.
Elementi e asset localizzabili
Puoi localizzare i seguenti componenti di qualsiasi modello di pass:
| Elemento | Meccanismo Apple Wallet | Meccanismo Google Wallet | Esempio |
|---|---|---|---|
| Etichette dei campi | Chiave mappata in pass.strings | translatedValues sull'etichetta LocalizedString | "POINTS" -> "PUNKTE" / "POINTS DE FIDÉLITÉ" |
| Valori statici dei campi | Chiave mappata in pass.strings | translatedValues sul valore LocalizedString | "Gold Member" -> "Membre Or" |
| Messaggi push di modifica | Chiave mappata in pass.strings con segnaposto %@ | Payload notifica push Google Wallet | "Your balance is %@" -> "Ihr Guthaben beträgt %@" |
| Testo logo e nome org. | Chiave logoText in pass.strings | localizedString nell'intestazione della classe | "Artisan Cafe" -> "Café Artisan" |
| Immagini localizzate | Archiviate nella cartella <lang>.lproj/ nel .pkpass | URI immagine provider per classe localizzata | Strip promozionale localizzata con testo tradotto |
| Campi sul retro e termini | Chiavi di testo esteso in pass.strings | Moduli localizzati textModulesData | Termini e condizioni tradotti per area geografica |
Importante: Quando localizzi le notifiche push di aggiornamento (
changeMessage), devi preservare lo specificatore di formato Apple%@in ogni traduzione (ad esempio"Votre solde est désormais de %@"). Se%@viene omesso da una traduzione localizzata, iOS sopprime la notifica sulla schermata di blocco quando quella lingua è attiva.
Configurazione della localizzazione nell'Editor visuale
-
1
Apri il modello nell'Editor visuale.
-
2
Nella barra laterale sinistra, vai su Design e contenuti -> Lingue e traduzioni.
-
3
Fai clic su + Aggiungi lingua e seleziona i codici lingua desiderati (ad es. tedesco
de, francesefr, spagnoloes). -
4
L'editor mostra una griglia di traduzione affiancata con tutte le chiavi di campo, le etichette, i valori e i messaggi di modifica.
-
5
Inserisci le stringhe tradotte per ciascun campo.
-
6
Per caricare immagini specifiche per lingua (come un banner strip in tedesco con testo tedesco), fai clic su Immagini localizzate nella scheda della lingua selezionata e carica i corrispondenti PNG
@2x/@3x. -
7
Fai clic su Salva bozza e visualizza l'anteprima delle modifiche nel simulatore cambiando il selettore della lingua di anteprima.
API programmatica: configurare stringhe multilingua
Puoi gestire le traduzioni tramite la REST API di Passinstance aggiornando template.localization (PATCH /api/v1/templates/:id):
{
"localization": {
"defaultLanguage": "en",
"languages": ["de", "fr", "es"],
"translations": {
"de": {
"MEMBER_LABEL": "MITGLIED",
"POINTS_LABEL": "PUNKTESTAND",
"TIER_GOLD": "Goldstatus",
"CHANGE_POINTS_MSG": "Ihr neuer Punktestand ist %@",
"TERMS_TITLE": "ALLGEMEINE GESCHÄFTSBEDINGUNGEN",
"TERMS_BODY": "Punkte verfallen nach 12 Monaten Inaktivität."
},
"fr": {
"MEMBER_LABEL": "MEMBRE",
"POINTS_LABEL": "POINTS DE FIDÉLITÉ",
"TIER_GOLD": "Statut Or",
"CHANGE_POINTS_MSG": "Votre nouveau solde est de %@",
"TERMS_TITLE": "CONDITIONS GÉNÉRALES",
"TERMS_BODY": "Les points expirent après 12 mois d'inactivité."
}
}
}
}
Riferimento al formato file Apple pass.strings
Quando Passinstance compila un bundle Apple Wallet .pkpass, genera automaticamente i file pass.strings codificati in UTF-16 (o UTF-8 con BOM) all'interno delle cartelle <locale>.lproj/:
/* de.lproj/pass.strings */
"MEMBER_LABEL" = "MITGLIED";
"POINTS_LABEL" = "PUNKTESTAND";
"CHANGE_POINTS_MSG" = "Ihr neuer Punktestand ist %@";
"TERMS_TITLE" = "ALLGEMEINE GESCHÄFTSBEDINGUNGEN";
Testare i pass localizzati sui dispositivi mobili
Per verificare che le regole di localizzazione vengano renderizzate correttamente:
-
1
Test su iOS:
- Apri Impostazioni -> Generali -> Lingua e zona sul tuo iPhone. - Aggiungi la lingua di test (ad es. tedesco) e impostala come lingua principale del sistema. - Apri Apple Wallet: tutte le etichette dei campi e le notifiche push del pass si aggiorneranno in tedesco.
-
2
Test su Android:
- Apri Impostazioni -> Sistema -> Lingue e immissione sul dispositivo Android. - Sposta tedesco o francese in cima all'elenco delle lingue preferite. - Apri Google Wallet per verificare i moduli textModulesData e i valori di intestazione tradotti.
-
3
Test della pagina di download:
- Le pagine di download PassFlow (/p/:token) rilevano automaticamente l'header Accept-Language del browser e offrono un selettore lingua nel piè di pagina.
Approfondisci Design e configurazione dei modelli per perfezionare la struttura visiva della tessera oppure Versioni dei modelli e pubblicazione per promuovere in produzione il modello localizzato.
