|
| 1 | +# Internationalization |
| 2 | + |
| 3 | +If you're building a shop for an international brand, you likely want it translated to different languages and using different currencies. In this document, you will learn how we're approaching internationalization in Vue Storefront and how to configure your application to use it. |
| 4 | + |
| 5 | +::: warning i18n is not multi-tenancy! |
| 6 | +This document only explains how to make a single shop instance available for multiple countries. If you need to build a system for multiple tenants, we suggest creating an instance of Vue Storefront for each tenant and sharing common resources through an NPM package. |
| 7 | +::: |
| 8 | + |
| 9 | +## How it works by default? |
| 10 | + |
| 11 | +By default, we are using the [`nuxt-i18n`](https://i18n.nuxtjs.org/) module for handling both translations and currencies. It's preinstalled in the [default theme](/getting-started/theme.html#what-s-makes-a-default-theme) and is configured for English and German translations out of the box. |
| 12 | + |
| 13 | +The `nuxt-i18n` module adds the `$t('key')` and `$n(number)` helpers to translate strings and format the currencies. |
| 14 | + |
| 15 | +You can find the translation keys in the `lang` directory of your project and configuration for currencies in `nuxt.config.js`. |
| 16 | + |
| 17 | +::: tip |
| 18 | +Even though the module is included in the default theme, it's not required. You can [disable it](#configuring-modules-separately) and handle internationalization yourself. |
| 19 | +::: |
| 20 | + |
| 21 | +To provide a unified way to configure internationalization across the application for different modules and integrations, we have introduced the `i18n` field in each module's configuration. It has the same format as the `nuxt-i18n` options. You can add any configuration there, and it will be propagated to all other Vue Storefront modules. |
| 22 | + |
| 23 | +All Vue Storefront integrations have the `useNuxtI18nConfig` property set to `true`. It means that they will use the same configuration as you provided for `nuxt-i18n` in the `i18n` field of your `nuxt.config.js`. |
| 24 | + |
| 25 | +```js |
| 26 | +// nuxt.config.js |
| 27 | + |
| 28 | +export default { |
| 29 | + buildModules: [ |
| 30 | + [ |
| 31 | + '@vue-storefront/{INTEGRATION}/nuxt', |
| 32 | + { |
| 33 | + // other comfiguration options |
| 34 | + i18n: { |
| 35 | + useNuxtI18nConfig: true, |
| 36 | + }, |
| 37 | + }, |
| 38 | + ], |
| 39 | + ], |
| 40 | + i18n: { |
| 41 | + locales: [ |
| 42 | + { |
| 43 | + code: 'en', |
| 44 | + label: 'English', |
| 45 | + file: 'en.js', |
| 46 | + iso: 'en', |
| 47 | + }, |
| 48 | + { |
| 49 | + code: 'de', |
| 50 | + label: 'German', |
| 51 | + file: 'de.js', |
| 52 | + iso: 'de', |
| 53 | + }, |
| 54 | + ], |
| 55 | + defaultLocale: 'en', |
| 56 | + }, |
| 57 | +}; |
| 58 | +``` |
| 59 | + |
| 60 | +## Configuring modules separately |
| 61 | + |
| 62 | +You can provide your own i18n configuration for a specific module by setting `useNuxtI18nConfig` to `false`. |
| 63 | + |
| 64 | +```js |
| 65 | +// nuxt.config.js |
| 66 | + |
| 67 | +export default { |
| 68 | + [ |
| 69 | + '@vue-storefront/{INTEGRATION}/nuxt', |
| 70 | + { |
| 71 | + i18n: { |
| 72 | + useNuxtI18nConfig: false, |
| 73 | + locales: [ |
| 74 | + { |
| 75 | + code: 'en', |
| 76 | + label: 'English', |
| 77 | + file: 'en.js', |
| 78 | + iso: 'en', |
| 79 | + }, |
| 80 | + { |
| 81 | + code: 'de', |
| 82 | + label: 'German', |
| 83 | + file: 'de.js', |
| 84 | + iso: 'de', |
| 85 | + }, |
| 86 | + ], |
| 87 | + defaultLocale: 'en' |
| 88 | + } |
| 89 | + } |
| 90 | + ]; |
| 91 | +} |
| 92 | +``` |
| 93 | + |
| 94 | +## CDN and cookies |
| 95 | + |
| 96 | +The server's response cannot contain the `Set-Cookie` header to make CDNs cache the website correctly. |
| 97 | + |
| 98 | +To achieve that, we've made our own mechanism for handling cookies responsible for storing `locale`, `currency`, and `country`. This mechanism also handles language detection and redirecting to the proper locale. For this reason, `@nuxtjs/i18n` language detection is disabled by default. |
| 99 | + |
| 100 | +```js |
| 101 | +// nuxt.config.js |
| 102 | +export default { |
| 103 | + i18n: { |
| 104 | + detectBrowserLanguage: false, |
| 105 | + }, |
| 106 | +}; |
| 107 | +``` |
| 108 | + |
| 109 | +If you don't want to redirect users, you can disable this mechanism, as described in the section below. |
| 110 | + |
| 111 | +## Disabling the auto-redirect mechanism |
| 112 | + |
| 113 | +The `@vue-storefront/nuxt` module includes an auto-redirect mechanism that performs a server-side redirect to different URLs based on the target locale. |
| 114 | + |
| 115 | +You can disable this by setting `autoRedirectByLocale` to `false` in the `i18n` configuration object. |
| 116 | + |
| 117 | +```js |
| 118 | +// nuxt.config.js |
| 119 | + |
| 120 | +export default { |
| 121 | + i18n: { |
| 122 | + autoRedirectByLocale: false, |
| 123 | + }, |
| 124 | +}; |
| 125 | +``` |
| 126 | + |
| 127 | +## Currency detection |
| 128 | + |
| 129 | +In addition to language detection, we also set currency based on locale. You can configure it in `nuxt.config.js` with the `vueI18n.numberFormats` property. |
| 130 | + |
| 131 | +For more configuration options of `numberFormats` entries, check the [Intl.NumberFormat()](https://developer.mozilla.org/en-US/docs/web/javascript/reference/global_objects/intl/numberformat) documentation. |
| 132 | + |
| 133 | +```js |
| 134 | +// nuxt.config.js |
| 135 | + |
| 136 | +export default { |
| 137 | + i18n: { |
| 138 | + vueI18n: { |
| 139 | + numberFormats: { |
| 140 | + en: { |
| 141 | + currency: { |
| 142 | + style: 'currency', |
| 143 | + currency: 'USD', |
| 144 | + currencyDisplay: 'symbol', |
| 145 | + }, |
| 146 | + }, |
| 147 | + // ...other locales |
| 148 | + }, |
| 149 | + }, |
| 150 | + }, |
| 151 | +}; |
| 152 | +``` |
| 153 | + |
| 154 | +**Please note that only one currency can be set for each locale.** |
| 155 | + |
| 156 | +If this is a limitation for you, or if you don't want to have currencies tied to locales, you can disable this mechanism and provide your own. |
| 157 | + |
| 158 | +To disable it, set `autoChangeCookie.currency` to `false` as described in the section below. |
| 159 | + |
| 160 | +## Configuring the Auto Cookie Change |
| 161 | + |
| 162 | +You can configure how `@vue-storefront/nuxt` handles cookie changes when the locale changes with the `autoChangeCookie` object. |
| 163 | + |
| 164 | +The `autoChangeCookie` object holds three properties directly linked to `currency`, `locale`, and `country`. These properties control how the module handles changing cookies. |
| 165 | + |
| 166 | +If set to `false`, the module won't change any cookies based on configurations or browser locale, and the integration will have to handle it. |
| 167 | + |
| 168 | +```js |
| 169 | +// nuxt.config.js |
| 170 | + |
| 171 | +export default { |
| 172 | + buildModules: [ |
| 173 | + [ |
| 174 | + '@vue-storefront/{INTEGRATION}/nuxt', |
| 175 | + { |
| 176 | + i18n: { |
| 177 | + useNuxtI18nConfig: true, |
| 178 | + }, |
| 179 | + }, |
| 180 | + ], |
| 181 | + ], |
| 182 | + i18n: { |
| 183 | + locales: [ |
| 184 | + { |
| 185 | + code: 'en', |
| 186 | + label: 'English', |
| 187 | + file: 'en.js', |
| 188 | + iso: 'en', |
| 189 | + }, |
| 190 | + { |
| 191 | + code: 'de', |
| 192 | + label: 'German', |
| 193 | + file: 'de.js', |
| 194 | + iso: 'de', |
| 195 | + }, |
| 196 | + ], |
| 197 | + defaultLocale: 'en', |
| 198 | + autoChangeCookie: { |
| 199 | + currency: false, |
| 200 | + locale: false, |
| 201 | + country: false, |
| 202 | + }, |
| 203 | + }, |
| 204 | +}; |
| 205 | +``` |
| 206 | + |
| 207 | +## Configuring cookie attributes |
| 208 | + |
| 209 | +You can overwrite the default `locale`, `currency`, and `country` cookie attributes set by `@vue-storefront/nuxt` or add custom attributes. |
| 210 | + |
| 211 | +To do so, add the `cookieOptions` object to the `i18n` configuration object in the `nuxt.config.js` file and specify the attributes you'd like the cookies to have. |
| 212 | + |
| 213 | +```js |
| 214 | +// nuxt.config.js |
| 215 | + |
| 216 | +export default { |
| 217 | + i18n: { |
| 218 | + cookieOptions: { |
| 219 | + // default attributes used by the `@vue-storefront/nuxt` module |
| 220 | + path: '/', |
| 221 | + sameSite: 'lax', |
| 222 | + expires: new Date(new Date().setFullYear(new Date().getFullYear() + 1)), |
| 223 | + }, |
| 224 | + }, |
| 225 | +}; |
| 226 | +``` |
0 commit comments