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
.lprojBundles: Standard Apple PassKit string dictionaries (<language>.lproj/pass.strings) packaged directly into the.pkpassarchive alongside localized images. -
Google Wallet
LocalizedStringResources: 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
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
Exact Locale Match: If the device requests
de-AT(German - Austria) and ade-ATdictionary exists, it is loaded first. -
2
Base Language Match: If
de-ATis absent, the engine falls back tode(German). -
3
Primary Template Language: If
deis absent, the engine falls back to the canonical base template language (default:en). -
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:
| Element | Apple Wallet Mechanism | Google Wallet Mechanism | Example |
|---|---|---|---|
| Field Labels | Key mapped in pass.strings | translatedValues on label LocalizedString | "POINTS" -> "PUNKTE" / "POINTS DE FIDÉLITÉ" |
| Static Field Values | Key mapped in pass.strings | translatedValues on value LocalizedString | "Gold Member" -> "Membre Or" |
| Push Change Messages | Key mapped in pass.strings with %@ placeholder | Google Wallet push notification payload | "Your balance is %@" -> "Ihr Guthaben beträgt %@" |
| Logo Text & Org Name | logoText key in pass.strings | localizedString on class header | "Artisan Cafe" -> "Café Artisan" |
| Localized Images | Stored inside <lang>.lproj/ folder in .pkpass | Provider image URI per localized class | Localized promo strip with translated typography |
| Back Fields & Terms | Long text keys in pass.strings | textModulesData localized modules | Terms 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
Open your template in the Visual Editor.
-
2
In the left navigation sidebar, navigate to Design & content -> Languages & translations.
-
3
Click + Add Language and select target language codes (e.g., German
de, Frenchfr, Spanishes). -
4
The editor displays a side-by-side translation grid listing all field keys, labels, values, and change messages.
-
5
Enter translated strings for each field.
-
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/@3xPNG. -
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):
{
"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:
/* 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
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.
-
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.
-
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.
