# Liquid implementation example

This is a new illustrative snippet, not the client's extracted source code. The actual app namespace/key and JSON structure have not been supplied. Adapt those before integration. No live theme was changed.

## Example contract

Product metafield: `custom.localized_images`, type `json`. Store exact Shopify language codes as top-level keys and original `product.media` positions as string keys. Each record contains `url`, `width`, `height`, and localized `alt`. Example shape:

```json
{"de":{"1":{"url":"https://cdn.shopify.com/REPLACE_WITH_UPLOADED_IMAGE_URL","width":1254,"height":1254,"alt":"Grüne Trinkflasche mit deutschem Produkttext"}}}
```

The URL is a placeholder. The app must write the real uploaded image URL, actual pixel dimensions and approved alt text. Liquid reads the metafield; it cannot create or save it.

## Theme integration

Copy localized-product-image.liquid into the theme's snippets directory. In the existing gallery's IMAGE branch, replace only the image rendering with a render call to `localized-product-image`, passing `product`, `media`, `image_class` and `loading`. Pass eager for the first visible image and lazy for the others. Keep existing slide wrappers, media IDs, variant behavior, videos and models intact.

Apply the same image lookup to thumbnails, zoom links, modal images and any variant-driven gallery rendering. This snippet alone does not modify those surfaces. A language switch must request the localized page or rerender its section for server-side Liquid to update.

The primary locale always keeps the original. Other locales use an exact language-code match, falling back to the original when the record is absent or incomplete. Regional locales are intentionally not reduced to a base language.

This example follows the position-based editor. If the app stores media IDs instead, look up `media.id` rather than `media.position`. Position mappings must be updated when original media is reordered or removed; stable media IDs avoid positional drift. Do not change the storage contract without adapting the app.

The JSON branch renders the saved URL directly. For production responsive replacements, store appropriate responsive sources or use a file-reference/metaobject contract returning Shopify image objects, then apply image_url/image_tag. Keep the theme's own sizes, classes and zoom resolution requirements.

## Verification before deployment

Check primary language, German/Danish replacement, missing mapping, media reorder, variants, thumbnails/zoom, mobile proportions and alt text.

## References

- [JSON metafields in Liquid](https://shopify.dev/docs/api/liquid/objects/metafield)
- [Selected storefront language](https://shopify.dev/docs/api/liquid/objects/localization)
- [Primary locale and ISO code](https://shopify.dev/docs/api/liquid/objects/shop_locale)