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"
}

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?