i18n Support

[rylanharper]

This feature was first proposed in this discussion last year.

⚡️ Summary

We should add multilingual support for Nitrogen using the Nuxt i18n module. However, there are some considerations regarding implementation and the components/files that need modifications..

For reference, Hydrogen outlines a localization strategy in its "Markets" documentation. Hydrogen seem to provide some utility functions and helpers to help with the following:

1. Adjust store localization dynamically (both language and currency codes).
2. Modify the URL to reflect the selected language/country.

We might take a different approach with Nitrogen. Instead of manually defining data helpers with additional utils, we could explore whether the Nuxt i18n module can pull dynamic locale data from our existing localization query. This query already provides availableLanguages and availableCountries based on the storefront’s Markets settings.

Warning

I’m unsure if Nuxt i18n supports dynamic localization data at runtime (or at any time haha). If not, we may still need a countries.ts helper or additional utilities functions to integrate this.

🛠️ Implementation

A general implementation of this feature would look like this:

1. Dynamic Locale Handling

   • Investigate if Nuxt i18n can accept dynamic locale data from the localization query.
   • This data would then be passed to the shop.ts store. (Currently, there’s a locale.language state, but it isn’t being used yet.)

2. Updating the Locale Modal

   • Modify the locale modal component to include an additional language selection dropdown after the existing country selector.
   • When a user saves their selection, both store country locale and language should update in the store.

3. URL Localization (To Be Determined)

   • Ideally, the URL should reflect the selected language, similar to Hydrogen: hydrogen.shop/fr/my-route
   • However, we need to test how this interacts with existing route parameters (e.g., collection filters, product variants, pagination, etc.).

@alefbarbeli Any thoughts on this approach? Also, if you’ve worked with Nuxt i18n before, do you know if it supports dynamic locale configuration?

[alefbarbeli]

Thanks for adding me to this issue! A few thoughts regarding your questions and next steps:

About dynamic fetching of locales:
Yes, Nuxt i18n supports fetching locales dynamically at build time, and we can certainly configure it at runtime as well. However, it's important to note that translations themselves aren't dynamic—they need to be prepared ahead of time on our side.

Suggested approach:
I'll begin by adding the nuxt-i18n module directly to the Nitrogen template. After that, I'll refactor the current hardcoded texts, extracting them into an initial translation file (en-us.json). Once we have this foundation, it'll be easier for the community to contribute additional translations as the template evolves.

From there, we can dynamically sync (or selectively choose not to sync) our prepared translation/localization files with Shopify's dynamic localization settings (availableLanguages, availableCountries). This should provide the flexibility we need.

Finally, I'll take a closer look at Hydrogen's current implementation to better understand their choices, which might help guide us towards.

Let me know if you have any other insights or considerations!

[rylanharper]

Yes, Nuxt i18n supports fetching locales dynamically at build time, and we can certainly configure it at runtime as well. However, it's important to note that translations themselves aren't dynamic—they need to be prepared ahead of time on our side.

@alefbarbeli I think this is incorrect. I need to investigate this further as I haven't actually used this feature in Shopify, but I am certain that Shopify actually provides translation data via the Translate & Adapt Shopify app? This is also part of the reason why every query/mutation in this template using the @inContext directive to get the current currency code and current language for collection and product data - it just keeps things simple.

Or did do you mean the Nuxt i18n does not support dynamic translations? If that is the case, it might be better to not use the i18n module for translations, but rather to change the route only, as it would be more simple for both us as developers and clients (its a lot of work translating potentially hundreds of collections/product data). This can possibly be done by Hydrogen does it, by providing some sort of countries.ts json file to tie which language you want to correspond to each type of currency. I've referenced this file before on the Pack Digital starter, which I used as influence for this template (although this is React-based Hydrogen).

Like maybe this countries.ts file can be used within the locale component and then the data can be sent to the shop.ts locale state. Since each collection/product useAsyncData call watches the shop store locale, it should then just update automatically. Again, I haven't tried this out. A good way to test this would be to simply go to to Settings → Languages on a pre-existing Shopify store and add in a new language. The "Translate & Adapt" app should be added automatically and you can then change the locale for any given product.

TLDR - For the sake of the user (Shopify admin content editors), all translated data should come from Shopify, while there should be additional helper functions/utils to help change the app URL to reflect these changes (which can possibly come from the i18n module if that is even possible).

[rylanharper]

@alefbarbeli Sorry for all these posts, but after thinking a bit on this, I think the solution should be the best of both worlds.. We use the i18n module to update the route and to update/change the default hardcoded text like you said! Then the collection/product data can come from Shopify. This seems like the best approach 👀

I think this may actually be what you initially meant haha, but I just misunderstood 🤦‍♂️

[alefbarbeli]

@rylanharper I think you're right about choosing the best of both worlds. Sorry if my previous explanation wasn't clear when I mentioned translations being handled "on our side." I was specifically referring to the template’s hardcoded texts.

This would be the first step, because we’ll need to translate elements like the "Cart" button into the user's language, and Nuxt i18n is perfect for handling this part. I can have this first part of the Pull Request ready by this week.

Doing this alone already provides a multi-language template for stores using Shopify admin in a single language. For example, if someone builds a storefront in Portuguese, the "Cart" button will become "Carrinho," and all user-facing pages will be translated accordingly. If their Shopify product data is already in Portuguese, this will immediately serve most users who don’t require multilingual product information.

Then, as a second step, I completely agree that we should leverage Shopify’s "Translate & Adapt" app. This will ensure that product data from Shopify matches the language selected by the user through Nuxt i18n. For this part, I'll dive deeper into Shopify’s documentation and Hydrogen’s implementation to get a better reference. Completing this second step will enable fully multilingual storefronts, making it ideal for stores serving international audiences.

One last thing worth noting: Nuxt i18n offers various Routing Strategies and even supports Different Domains. This gives us the flexibility to shape URLs in a way that better fits client needs.

[rylanharper]

Yep, totally agree! Excited to see this feature included in the template. Please take your time - there is no rush (I'm actually finishing up a big ecom project over the next few weeks). All I ask is to keep your code neat and to avoid expensive functions if possible, in order to keep Nitrogen performant and approachable for both new and experienced devs. Also, keep in mind that this feature should still function even if no secondary language is set up in Shopify; it's an optional feature that developers can choose to enable if needed.

Got it. Good to hear there are various routing strategies in the i18n module! Here is the Hydrogen "Markets" documentation, which doesn't seem to be of much help since our "Nuxt" way of doing things is very different haha.

PS - I'll be creating a new discussion later today on various changes I plan on integrating on this project for this year. Nothing major, as most of the core functionality is done (I also like the current folder structure), but I plan on adding some new features, components, and some typescript improvements over the coming months. You can look this over if you want or suggest new features/improvements :)

[alefbarbeli]

@rylanharper Nice! I'll keep you posted on the updates or any question about the implementation.

And be sure that I'll add my thoughts to the discussion.

I really appreciate the fact that all core functionality is already working, and that's why I've picked Nitrogen as the starter point of a project that I'm working on. Well done job on the folder structure and overall project architecture simplicity.