Link a folder of images

If you have a folder of your screenshot images (PNG or JPG) ready-to-go, ButterKit can automatically import all screenshots for you, optionally organized by localization – and keep things updated as you change the images. This can save a lot of time, especially if you’re localizing to many languages.

1. Link a Folder

1. View the Project Settings inspector by de-selecting any artboards
2. Click “Link a Fastlane‑style folder…”
3. Choose your folder

2. Supported Folder Structures

For best results, organize screenshots in any of these ways:

Flat root — Place images directly inside the linked folder:

Locale folders (recommended) — Organize by language:

Locale → Device folders — Organize by language, then device:

Device folders (no locale) — Organize by device only:

Notes:

• Locale folders accept BCP‑47 codes and common synonyms. Using BCP‑47 is recommended for predictability.
• Device folder names are case/space/number tolerant. “iPhone 17 Pro Max”, “iphone17promax”, and “iPhone‑17‑Pro‑Max” all match.

3. File Naming and Sorting

Images are applied to 3D devices in a predictable sequence per group (device or locale):

1. Trailing number at end of filename (preferred)
   • …-01.png, …-02.png, …-10.png
2. If no trailing number, a leading number at the start
   • 01 … .png
3. Otherwise, natural (localized) filename order

Recommendations:

• End filenames with a zero‑padded index: -01, -02, -03
• Keep the index immediately before the extension

Example sequence (applied in this order):

• iPhone 15 Pro Max-Calendar-01.png
• iPhone 15 Pro Max-DashboardLight-02.png
• iPhone 15 Pro Max-SubscriptionList-03.png
• iPhone 15 Pro Max-SubscriptionDetailShares-04.png
• iPhone 15 Pro Max-SubscriptionDetailPriceHistory-05.png
• iPhone 15 Pro Max-Calendar-06.png

4. Multiple Devices on One Artboard

If an artboard contains multiple models of the same device, all of them are targeted. Files are applied sequentially to model 1, then model 2, then the next artboard, and so on.

5. How Matching Works

• If locale folders exist:
  • Exact match to the locale’s BCP‑47 code (e.g., fr-CA), else family fallback (e.g., any French to fr-*), else base language when appropriate.
• If no locale folders but the root has images:
  • Applies to the active language; if none, to the project’s base language; else to base artboards.
• For device subfolders:
  • Files go to artboards containing that device; if none match, images are applied sequentially across the group.

Recommended BCP-47 Localization Codes

ButterKit supports the same 39 locales as App Store Connect. Use these as your locale folder names:

• ar-SA — Arabic (Saudi Arabia)
• ca — Catalan
• zh-Hans — Chinese (Simplified)
• zh-Hant — Chinese (Traditional)
• hr — Croatian
• cs — Czech
• da — Danish
• nl-NL — Dutch (Netherlands)
• en-AU — English (Australia)
• en-CA — English (Canada)
• en-GB — English (U.K.)
• en-US — English (U.S.)
• fi — Finnish
• fr-FR — French (France)
• fr-CA — French (Canada)
• de-DE — German (Germany)
• el — Greek
• he — Hebrew
• hi — Hindi
• hu — Hungarian
• id — Indonesian
• it — Italian
• ja — Japanese
• ko — Korean
• ms — Malay
• no — Norwegian
• pl — Polish
• pt-BR — Portuguese (Brazil)
• pt-PT — Portuguese (Portugal)
• ro — Romanian
• ru — Russian
• sk — Slovak
• es-MX — Spanish (Mexico)
• es-ES — Spanish (Spain)
• sv — Swedish
• th — Thai
• tr — Turkish
• uk — Ukrainian
• vi — Vietnamese

Examples:

• screenshots/en-US/iPhone 17 Pro Max/MyScreen-01.png
• screenshots/pt-BR/MyScreen-01.png

Troubleshooting

• No images applied: ensure PNG/JPG and folder permission granted.
• Wrong order: add a trailing -01, -02 index; zero‑pad to avoid -2 sorting after -10.
• Device not matched: rename the device folder closer to the display name (spacing/case doesn’t matter).
• Extra images: if there are more files than models, the extras are ignored; fewer files means some models remain unchanged.