Shopify localization, accessibility, and performance

Use this guide before returning a finished theme change. A visually correct theme can still fail merchants through untranslated copy, inaccessible controls, or slow Liquid and media.

Localize storefront and editor copy

Put customer-facing theme strings in locales/<language>.json and render them with the t filter. Put theme-editor schema strings in matching locales/<language>.schema.json files and reference them with t: keys from schema JSON.

• Keep exactly one storefront default such as en.default.json and one default schema locale such as en.default.schema.json.
• Name regional locales with IETF language tags such as en-GB.json or fr-CA.json.
• Organize keys by feature and meaning, not by the current English sentence.
• Interpolate variables into translation strings instead of concatenating translated fragments.
• Preserve HTML escaping unless the translation intentionally contains reviewed markup.
• Use sentence case and consistent commerce terms for new fixed interface copy.
• Do not put merchant-authored content into locale files. Settings hold merchant content; locales hold interface language.

Example:

{
  "products": {
    "add_to_cart": "Add to cart",
    "price_from": "From {{ price }}"
  }
}

{% assign formatted_price = product.price_min | money %}
{{ 'products.price_from' | t: price: formatted_price }}

When filters need grouping, assign the formatted value first so the translation receives the finished string.

Meet storefront accessibility requirements

• Every interaction must work with a keyboard and expose a visible focus state.
• Keep focus order aligned with DOM order. Do not use positive tabindex values to repair visual ordering.
• Give form controls unique IDs and matching labels. Error messages must identify the affected field.
• Use buttons for actions and links for navigation.
• Give meaningful images useful alt text; use empty alt text for decorative images.
• Maintain at least 4.5:1 contrast for normal text and 3:1 for large text and essential non-text boundaries.
• Keep pointer targets at least 24 by 24 CSS pixels unless a documented exception applies.
• Use a logical heading outline and landmarks. Do not pick headings for their default size.
• Announce asynchronous cart and validation updates where needed, without moving focus unexpectedly.
• Honor reduced-motion preferences and keep essential state understandable without animation.

Protect Core Web Vitals

Render navigation, hero content, product information, prices, and primary actions in Liquid and HTML. Do not wait for JavaScript to create essential storefront content.

• Do not lazy-load the likely largest-contentful-paint image. Give that one image high fetch priority when appropriate.
• Supply responsive image widths, intrinsic width and height, and suitable sizes through image_url and image_tag.
• Lazy-load below-the-fold images and defer non-critical scripts.
• Avoid deeply nested Liquid loops. Filter or map collections before looping, and move repeated assignments and filters outside loops.
• Paginate large collections rather than rendering unbounded product or article lists.
• Load theme CSS predictably. Keep section-specific CSS and JavaScript scoped and avoid shipping the same asset repeatedly.
• Prefer Shopify-hosted assets and fonts. Use resource hints sparingly and only for a measured need.
• Test home, product, collection, cart, search, and content templates with realistic catalog sizes.

Primary Shopify sources

• Locales
• Storefront locale files
• Accessibility best practices
• Performance best practices
• Theme Store requirements