Adding Localization to Your Storefront

For a full overview of localization in Pack Admin and the Customizer, see Localization.

GraphQL Queries

  • Queries now accept two optional parameters—language and country—which will return translated content when available, or default to your primary locale.
  • You must also use the @inContext directive. For example, fetching a page by handle becomes:
query PageByHandle(
  $handle: String!
  $language: String
  $country: String
) @inContext(language: $language, country: $country) {
  pageByHandle(handle: $handle) {
    id
    handle
  }
}
  • To request the French-Canadian version of “About Us,” pass these variables:
{
  "handle": "about-us",
  "language": "fr",
  "country": "CA"
}

Fallback Resolution

When querying localized content, Pack resolves content in this order:

  1. Requested locale — Exact match for the language + country provided
  2. Fallback locale — The locale's configured fallback (if set)
  3. Primary locale — The store's primary locale
  4. Non-localized content — Legacy content created before localization (has no locale)

If no content is found at any level, the query returns null.

Example Fallback Chain

Request: fr-CA (French Canadian)
    ↓ not found
Fallback: fr-FR (French)
    ↓ not found
Primary: en-US (English)
    ↓ found
Returns: en-US content

This means you can launch new locales immediately—untranslated content automatically falls back without requiring code changes.

Handle Uniqueness

Content handles are unique per locale. This means you can have:

  • /pages/about in en-US
  • /pages/about in fr-FR
  • /pages/about in de-DE

Each is a separate piece of content, linked together as translations.

SEO Considerations

Storefronts implementing localization must handle hreflang tags correctly to avoid SEO issues:

  • Localization creates duplicate versions of the same content for each locale.

    • If SEO settings or meta tags are not updated for each localized version, search engines may flag them as duplicate content.
    • Be explicit about content intent and ensure localized URLs (e.g. /fr-CA/...) and hreflang tags are implemented.

  • Risks of not doing so:

    • Diluted search rankings if search engines can’t determine which version is canonical.
    • Google may surface the wrong language version (e.g. en-US instead of fr-CA), leading to bounce and poor customer experience.

  • Action: Always update localized meta tags, titles, and hreflang references. Ensure Pack Admin / Customizer changes carry through to your storefront implementation.

Fallback Handling & Direct Visitors

Localization introduces complexity for direct visitors and mismatched URLs:

  • An implementor in Remix must handle redirects smartly:

    • Example: /fr-CA/pages/about-us → /fr-CA/pages/a-propos-de-nous if a translated handle exists.
    • If no translation exists, redirect to the primary locale instead of a 404.

  • Common issues to account for:

    • Users guessing URLs (/fr-CA/...) or following old links.
    • Links in localized markdown pointing to English handles (/en-US/...). These should redirect intelligently.

  • Recommendation:

    • Decide how storefronts should handle falling back: exact match, redirect, or 404.
    • Default best practice: redirect to the primary locale equivalent page if no localized version exists.

Known Issues & Performance Notes

  • Duplicate SEO pages can occur when localization is enabled but SEO meta settings aren’t updated per locale.
  • This is not a bug in Pack but a configuration issue - the frontend code should control what values are passed in the GraphQL queries and ensure proper locale handling.

Was this page helpful?