Skip to content
Guida del Centro assistenza · Modelli di pass
4 min di letturaVerificato 2026-11-16

Lingue del pass e localizzazione

Distribuisci pass Apple e Google Wallet multilingue utilizzando dizionari .lproj/pass.strings, immagini localizzate e alberi di fallback.

In questa guida

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 .lproj per Apple Wallet: dizionari di stringhe standard Apple PassKit (<language>.lproj/pass.strings) impacchettati direttamente nell'archivio .pkpass insieme alle immagini localizzate.
  • Risorse LocalizedString per 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

FLUSSO ARCHITETTURALE
ARCHITETTURA INTERATTIVA
LOCALIZZAZIONE PASS E COMPILAZIONE STRINGHE
FASE 01 REPOSITORY LOCALIZZAZIONE MODELLO (templateLocalization.ts)
Lingua base (es. en): etichette canoniche, valori e messaggi di modifica
Dizionari di traduzione: de, es, fr, it, nl, pt, ja, ecc.
Override asset localizzati: localizedImages[locale] (es. banner strip DE)
FASE 02 COMPILATORE LOCALIZZAZIONE (template-localization.util.ts)
1
Esegue l'escape dei letterali UTF-16/UTF-8 Apple ("Key" = "Valore";)
2
Preserva gli specificatori (%@) in changeMessage in tutte le lingue
3
Costruisce la gerarchia fallback: EsattaLingua baseModello primario
FASE 03A APPLE WALLET (Bundle .pkpass)
de.lproj/pass.strings de.lproj/logo.png, strip.png fr.lproj/pass.strings fr.lproj/logo.png iOS renderizza in base alla lingua del dispositivo
FASE 03B GOOGLE WALLET (Class/Object)
"label": { "defaultValue": { "language": "en", "value": "POINTS" }, "translatedValues": [ { "language": "de", "value": "PUNKTE" } ]
}

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. 1
    Corrispondenza locale esatta: se il dispositivo richiede de-AT (tedesco – Austria) ed esiste un dizionario de-AT, questo viene caricato per primo.
  2. 2
    Corrispondenza lingua base: se de-AT è assente, il motore ripiega su de (tedesco).
  3. 3
    Lingua primaria del modello: se anche de è assente, il motore utilizza la lingua base canonica del modello (predefinita: en).
  4. 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:

ElementoMeccanismo Apple WalletMeccanismo Google WalletEsempio
Etichette dei campiChiave mappata in pass.stringstranslatedValues sull'etichetta LocalizedString"POINTS" -> "PUNKTE" / "POINTS DE FIDÉLITÉ"
Valori statici dei campiChiave mappata in pass.stringstranslatedValues sul valore LocalizedString"Gold Member" -> "Membre Or"
Messaggi push di modificaChiave 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.stringslocalizedString nell'intestazione della classe"Artisan Cafe" -> "Café Artisan"
Immagini localizzateArchiviate nella cartella <lang>.lproj/ nel .pkpassURI immagine provider per classe localizzataStrip promozionale localizzata con testo tradotto
Campi sul retro e terminiChiavi di testo esteso in pass.stringsModuli localizzati textModulesDataTermini 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. 1
    Apri il modello nell'Editor visuale.
  2. 2
    Nella barra laterale sinistra, vai su Design e contenuti -> Lingue e traduzioni.
  3. 3
    Fai clic su + Aggiungi lingua e seleziona i codici lingua desiderati (ad es. tedesco de, francese fr, spagnolo es).
  4. 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. 5
    Inserisci le stringhe tradotte per ciascun campo.
  6. 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. 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):

JSON
{
  "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/:

TEXT
/* 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. 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.

  1. 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.

  1. 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.

Pronto a lanciare il tuo primo programma di carte Wallet?

Crea il tuo workspace, configura il modello e testa una carta reale in Apple Wallet e Google Wallet prima di scalare.