Localization (multi-language)

Hyprism ships with English (default) and German translations covering both the storefront (what customers see) and the theme editor (what merchants see when customizing). This chapter covers using the built-in locales, adding new languages, and the translation architecture.

15.1 The two layers of localization

Shopify themes have two parallel translation systems:

Layer	What it translates	File
Storefront	Buttons, labels, messages visible to customers	locales/en.default.json, locales/de.json, locales/X.json
Theme editor	Settings labels, info-text, dropdown options visible to merchants	locales/en.default.schema.json, locales/de.schema.json, locales/X.schema.json

The storefront locale is what controls what your customers read. The theme editor locale is what controls what you read when customizing the theme.

For most merchants, only the storefront matters. The theme-editor locale is automatically read based on the language setting of your Shopify Admin account.

15.2 Built-in EN + DE

What’s translated

• All theme strings — error messages, button labels, empty-state copy, accessibility labels
• All section settings — 4041 customizer-schema keys translated (verified at 2026-05-18 audit; deduplicated namespace structure that re-uses common labels across sections)
• All section names and presets — visible in the “Add section” picker

Enabling German on your storefront

1. Shopify Admin → Settings → Languages.
2. Add language → German.
3. Click Publish next to German.

The German storefront is now available. To make it the default for German-speaking visitors, configure Shopify Markets (per-country language preferences).

Switching between languages on the storefront

Hyprism’s footer-localization block (chapter 5) provides a language switcher. Add it to your footer to give visitors a UI to switch languages.

Alternatively, Shopify auto-detects browser language and redirects to the appropriate locale (if Markets is configured).

15.3 Adding a new language

To add a new language (e.g., French, Spanish, Italian, Dutch, Portuguese):

Step 1: enable on Shopify

Shopify Admin → Settings → Languages → Add language → pick the target.

The new language is “unpublished” — visitors can’t see it yet.

Step 2: translate storefront strings

Two options:

Option A: use the Translate & Adapt app (recommended)

Shopify offers a free app called Translate & Adapt that translates your store content using machine translation, with optional manual review.

1. Install Translate & Adapt from the Shopify App Store.
2. Add your new language.
3. The app translates products, collections, articles, pages, and theme strings automatically.
4. Review and edit translations as needed.

Option B: edit JSON directly

For developers / advanced users:

1. Create locales/{lang}.json (copy en.default.json as a starting point).
2. Translate every value to the target language (the keys stay the same).
3. Push to Shopify with shopify theme push.

Step 3: translate theme-editor strings (optional)

If you want the theme editor to render in the new language too (for merchants who admin in that language):

1. Create locales/{lang}.schema.json (copy en.default.schema.json).
2. Translate the values.
3. Push.

This is optional — the Shopify Theme Store doesn’t require theme-editor translations beyond English. But it’s a nice touch for stores managed by non-English-speaking teams.

Step 4: publish

Shopify Admin → Settings → Languages → click Publish next to the new language.

15.4 hreflang

Hyprism’s meta-tags.liquid snippet auto-emits hreflang annotations for every published locale:

<link rel="alternate" hreflang="en" href="https://yourstore.com/en/product-handle">
<link rel="alternate" hreflang="de" href="https://yourstore.com/de/product-handle">
<link rel="alternate" hreflang="x-default" href="https://yourstore.com/product-handle">

This tells Google “this page exists in these languages at these URLs” — Google then serves the right language to the right visitor.

15.5 RTL (right-to-left) support

Hyprism’s CSS is partially RTL-aware — most layout uses CSS logical properties (margin-inline-start instead of margin-left), which automatically flip in RTL languages (Arabic, Hebrew, Persian).

Some legacy CSS still uses physical properties (margin-left / margin-right) — these would need manual RTL overrides. For an Arabic or Hebrew storefront, expect to make some manual CSS adjustments.

If RTL is critical for your business, plan for ~10–20 hours of polish work in addition to the base translation.

15.6 Locale-specific overrides

You can override theme settings per locale. Example: different hero image for English vs German.

Shopify’s mechanism: publish multiple theme versions, each configured for a specific locale.

Or use the Translate & Adapt app which lets you swap images / videos / specific section settings per locale.

15.7 Currency

Currency is separate from language — Shopify’s Markets feature controls per-country currency display.

Setting	Where	What it does
Shop currency	Shopify Admin → Settings → General	Your base currency for transactions
Display currency	Shopify Markets	Per-country presentation currency
Auto-format	Auto	Hyprism uses Shopify’s money filter — currency symbol + decimal separator render per the visitor’s locale

The footer-localization block shows the current country/currency and lets visitors switch.

15.8 Translation toolchain (engineering note)

Hyprism’s locale files are large (~1810 keys × 2 languages = 3620 strings). The translation was done with this workflow:

1. Migrate hardcoded English in schema-JSON to t: references (scripts/migrate-schemas-to-t-refs.py).
2. Deduplicate common labels across schemas (scripts/dedup-translations.py) — reduced 4374 keys → 1810 unique.
3. DeepL API auto-translation EN → DE (scripts/translate-de-schema-deepl.py).
4. Manual polish-pass for UX-specific terms (scripts/fix-de-overrides.py) — ~400 corrections across 4 review rounds.

If you want to add a new language quickly:

# Copy template
cp locales/de.schema.json locales/fr.schema.json

# Edit overrides for the new language in scripts/fix-de-overrides.py
# (rename to scripts/fix-fr-overrides.py and adjust the maps)

# Run translation
DEEPL_API_KEY='your-key' python3 scripts/translate-de-schema-deepl.py \
  --source de.schema.json --target fr.schema.json --target-lang FR

For the storefront file (X.json), the same approach works (smaller file, faster).

⚠️ DeepL Free tier = 500k characters / month. One language ≈ 46k chars (10% of monthly quota). 8 languages = 80% of monthly quota.

Next

Chapter 16 — App compatibility — integrating apps with Hyprism.