Skip to content
Help Center Guide · Pass Templates
4 min readVerified 2026-11-16

Pass Languages & Localization

Deliver multi-lingual Apple and Google Wallet passes using .lproj/pass.strings dictionaries, localized images, and fallback trees.

In This Guide

Overview

Global brands, airlines, international events, and retail chains often issue wallet passes to customers across diverse language regions. Passinstance provides a native multi-language localization engine that compiles localized strings and assets into:

  • Apple Wallet .lproj Bundles: Standard Apple PassKit string dictionaries (<language>.lproj/pass.strings) packaged directly into the .pkpass archive alongside localized images.
  • Google Wallet LocalizedString Resources: Google Wallet API structures with fallback strings and language-specific translations (translatedValues[]).

When a customer installs a pass, iOS and Android automatically inspect the user's operating system language and region settings, displaying field labels, values, lock-screen notifications, and brand graphics in their native language—with zero separate templates required.

System Architecture: Multi-Lingual PassKit & Google Compilation

SYSTEM ARCHITECTURE FLOW
INTERACTIVE ARCHITECTURE
PASS LOCALIZATION & STRING COMPILATION
STAGE 01 TEMPLATE LOCALIZATION REPOSITORY (templateLocalization.ts)
Base Language (e.g., en): Canonical field labels, values, and change messages
Translation Dictionaries: de, es, fr, it, nl, pt, ja, etc.
Localized Asset Overrides: localizedImages[locale] (e.g., German strip banner)
STAGE 02 LOCALIZATION COMPILER (template-localization.util.ts)
1
Escapes Apple UTF-16 / UTF-8 string literals ("Key" = "Translated Value";)
2
Preserves format specifiers (%@) in changeMessage across all languages
3
Constructs fallback hierarchy: ExactBase LanguagePrimary Template
STAGE 03A APPLE WALLET (.pkpass Bundle)
de.lproj/pass.strings de.lproj/logo.png, strip.png fr.lproj/pass.strings fr.lproj/logo.png iOS renders based on device locale
STAGE 03B GOOGLE WALLET (Class/Object)
"label": { "defaultValue": { "language": "en", "value": "POINTS" }, "translatedValues": [ { "language": "de", "value": "PUNKTE" } ]
}

The 4-Tier Locale Fallback Hierarchy

When a mobile device renders a localized pass, Passinstance applies a 4-tier resolution hierarchy to guarantee that text never appears blank or broken:

  1. 1
    Exact Locale Match: If the device requests de-AT (German - Austria) and a de-AT dictionary exists, it is loaded first.
  2. 2
    Base Language Match: If de-AT is absent, the engine falls back to de (German).
  3. 3
    Primary Template Language: If de is absent, the engine falls back to the canonical base template language (default: en).
  4. 4
    First Available Translation: If base strings are missing, the compiler renders the first available translated string.

Localized Elements & Assets

You can localize the following components of any pass template:

ElementApple Wallet MechanismGoogle Wallet MechanismExample
Field LabelsKey mapped in pass.stringstranslatedValues on label LocalizedString"POINTS" -> "PUNKTE" / "POINTS DE FIDÉLITÉ"
Static Field ValuesKey mapped in pass.stringstranslatedValues on value LocalizedString"Gold Member" -> "Membre Or"
Push Change MessagesKey mapped in pass.strings with %@ placeholderGoogle Wallet push notification payload"Your balance is %@" -> "Ihr Guthaben beträgt %@"
Logo Text & Org NamelogoText key in pass.stringslocalizedString on class header"Artisan Cafe" -> "Café Artisan"
Localized ImagesStored inside <lang>.lproj/ folder in .pkpassProvider image URI per localized classLocalized promo strip with translated typography
Back Fields & TermsLong text keys in pass.stringstextModulesData localized modulesTerms and conditions translated per region

Important: When localizing push update notifications (changeMessage), you must preserve the Apple format specifier %@ in every translation (for example, "Votre solde est désormais de %@"). If %@ is omitted from a localized translation, iOS will suppress the lock-screen notification when that language is active.

Configuring Localization in the Visual Editor

  1. 1
    Open your template in the Visual Editor.
  2. 2
    In the left navigation sidebar, navigate to Design & content -> Languages & translations.
  3. 3
    Click + Add Language and select target language codes (e.g., German de, French fr, Spanish es).
  4. 4
    The editor displays a side-by-side translation grid listing all field keys, labels, values, and change messages.
  5. 5
    Enter translated strings for each field.
  6. 6
    To upload language-specific imagery (such as a German strip banner with German text), click Localized Images under the selected language tab and upload the corresponding @2x / @3x PNG.
  7. 7
    Click Save Draft and preview your changes in the simulator by switching the preview language selector.

Programmatic API: Configuring Multi-Lingual Strings

You can manage translations via the Passinstance REST API by updating 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é."
      }
    }
  }
}

Apple pass.strings File Format Reference

When Passinstance compiles an Apple Wallet .pkpass bundle, it automatically generates UTF-16 (or UTF-8 with BOM) encoded pass.strings files inside <locale>.lproj/ folders:

TEXT
/* de.lproj/pass.strings */
"MEMBER_LABEL" = "MITGLIED";
"POINTS_LABEL" = "PUNKTESTAND";
"CHANGE_POINTS_MSG" = "Ihr neuer Punktestand ist %@";
"TERMS_TITLE" = "ALLGEMEINE GESCHÄFTSBEDINGUNGEN";

Testing Localized Passes on Mobile Devices

To verify that your localization rules render correctly:

  1. 1
    iOS Testing:

- Go to Settings -> General -> Language & Region on your iPhone. - Add your test language (e.g., German) and set it as the primary system language. - Open Apple Wallet: all field labels and push notifications for the pass will update to German.

  1. 2
    Android Testing:

- Go to Settings -> System -> Languages & Input on your Android device. - Move German or French to the top of your language preference list. - Open Google Wallet to observe the translated textModulesData and header values.

  1. 3
    Download Page Testing:

- PassFlow download pages (/p/:token) automatically detect the browser's Accept-Language header and provide a language switcher in the footer.

Explore Template Design & Configuration to adjust visual card structures or Template Versions & Publishing to promote your localized template to production.

Ready to launch your first pass program?

Create your workspace, configure your pass template, and test a real pass in Apple Wallet and Google Wallet before you scale.