docs and test updates

docs/content/en/browser-language-detection.md

@@ -14,7 +14,7 @@ By default, **nuxt-i18n** attempts to redirect users to their preferred language
   detectBrowserLanguage: {
     useCookie: true,
     cookieKey: 'i18n_redirected',
-    // onlyOnRoot: true,
+    onlyOnRoot: true,  // recommended
   }
 }]
 ```
@@ -25,7 +25,7 @@ For better SEO, it's recommended to set `onlyOnRoot` to `true`. With it set, the
 
 </alert>
 
-Browser language is detected either from `navigator` when running on client-side, or from the `accept-language` HTTP header. Configured `locales` (or locales `code`s when locales are specified in object form) are matched against locales reported by the browser (for example `en-US,en;q=0.9,no;q=0.8`). If there is no exact match for the full locale, the language code (letters before `-`) are matched against configured locales (for backward-compatibility).
+Browser language is detected either from `navigator` when running on client-side, or from the `accept-language` HTTP header. Configured `locales` (or locales `iso` and/or `code` when locales are specified in object form) are matched against locales reported by the browser (for example `en-US,en;q=0.9,no;q=0.8`). If there is no exact match for the full locale, the language code (letters before `-`) are matched against configured locales.
 
 To prevent redirecting users every time they visit the app, **nuxt-i18n** sets a cookie after the first redirection. You can change the cookie's name by setting `detectBrowserLanguage.cookieKey` option to whatever you'd like, the default is _i18n_redirected_.
 

docs/content/en/options-reference.md

@@ -62,7 +62,7 @@ List of locales supported by your app. Can either be an array of codes (`['en',
 
 When using an object form, the properties can be:
 - `code` (**required**) - unique identifier of the locale
-- `iso` (required when using SEO features) - The ISO code used for SEO features. Should be in one of those formats:
+- `iso` (required when using SEO features and) - The ISO code used for SEO features and for matching browser locales when using [detectBrowserLanguage](#detectBrowserLanguage) functionality. Should be in one of those formats:
   * ISO 639-1 code (e.g. `'en'`)
   * ISO 639-1 and ISO 3166-1 alpha-2 codes, separated by hyphen (e.g. `'en-US'`)
 - `file` (required when using `lazy`) - the name of the file. Will be resolved relative to `langDir` path when loading locale messages lazily
@@ -111,7 +111,8 @@ Directory that contains translation files when lazy-loading messages. This CAN N
 - default: `{ alwaysRedirect: false, fallbackLocale: '', onlyOnRoot: false, useCookie: true, cookieCrossOrigin: false, cookieDomain: null, cookieKey: 'i18n_redirected', cookieSecure: false }`
 
 Enables browser language detection to automatically redirect visitors to their preferred locale as they visit your site for the first time.
-Set to false to disable.
+
+See also [Browser language detection](./browser-language-detection) for a guide.
 
 <alert type="info">
 
@@ -130,6 +131,8 @@ Supported properties:
 - `cookieSecure` (default: `false`) - Sets the `Secure` flag for the cookie.
 },
 
+Set to false to disable.
+
 ## `rootRedirect`
 
 - type: `string` or `object` or `null`

docs/content/es/browser-language-detection.md

@@ -15,7 +15,7 @@ Por defecto, **nuxt-i18n** intenta redirigir a los usuarios a su idioma preferid
   detectBrowserLanguage: {
     useCookie: true,
     cookieKey: 'i18n_redirected',
-    // onlyOnRoot: true,
+    onlyOnRoot: true,  // recommended
   }
 }]
 ```
@@ -26,7 +26,7 @@ For better SEO, it's recommended to set `onlyOnRoot` to `true`. With it set, the
 
 </alert>
 
-Browser language is detected either from `navigator` when running on client-side, or from the `accept-language` HTTP header. Configured `locales` (or locales `code`s when locales are specified in object form) are matched against locales reported by the browser (for example `en-US,en;q=0.9,no;q=0.8`). If there is no exact match for the full locale, the language code (letters before `-`) are matched against configured locales (for backward-compatibility).
+Browser language is detected either from `navigator` when running on client-side, or from the `accept-language` HTTP header. Configured `locales` (or locales `iso` and/or `code` when locales are specified in object form) are matched against locales reported by the browser (for example `en-US,en;q=0.9,no;q=0.8`). If there is no exact match for the full locale, the language code (letters before `-`) are matched against configured locales.
 
 Para evitar redirigir a los usuarios cada vez que visitan la aplicación, **nuxt-i18n** establece una cookie después de la primera redirección. Puede cambiar el nombre de la cookie configurando la opción `detectBrowserLanguage.cookieKey` a lo que desee, el valor predeterminado es _i18n_redirected_.
 

docs/content/es/options-reference.md

@@ -62,7 +62,7 @@ List of locales supported by your app. Can either be an array of codes (`['en',
 
 When using an object form, the properties can be:
 - `code` (**required**) - unique identifier of the locale
-- `iso` (required when using SEO features) - The ISO code used for SEO features. Should be in one of those formats:
+- `iso` (required when using SEO features and) - The ISO code used for SEO features and for matching browser locales when using [detectBrowserLanguage](#detectBrowserLanguage) functionality. Should be in one of those formats:
   * ISO 639-1 code (e.g. `'en'`)
   * ISO 639-1 and ISO 3166-1 alpha-2 codes, separated by hyphen (e.g. `'en-US'`)
 - `file` (required when using `lazy`) - the name of the file. Will be resolved relative to `langDir` path when loading locale messages lazily
@@ -111,7 +111,8 @@ Directory that contains translation files when lazy-loading messages. This CAN N
 - default: `{ alwaysRedirect: false, fallbackLocale: '', onlyOnRoot: false, useCookie: true, cookieCrossOrigin: false, cookieDomain: null, cookieKey: 'i18n_redirected', cookieSecure: false }`
 
 Enables browser language detection to automatically redirect visitors to their preferred locale as they visit your site for the first time.
-Set to false to disable.
+
+See also [Browser language detection](./browser-language-detection) for a guide.
 
 <alert type="info">
 
@@ -130,6 +131,8 @@ Supported properties:
 - `cookieSecure` (default: `false`) - Sets the `Secure` flag for the cookie.
 },
 
+Set to false to disable.
+
 ## `rootRedirect`
 
 - type: `string` or `object` or `null`

test/unit.test.js

@@ -101,4 +101,18 @@ describe('matchBrowserLocale', () => {
 
     expect(matchBrowserLocale(appLocales, browserLocales)).toBe('cn')
   })
+
+  test('matches full ISO code', () => {
+    const appLocales = [{ code: 'us', iso: 'en-US' }, { code: 'gb', iso: 'en-GB' }]
+    const browserLocales = ['en-GB', 'en']
+
+    expect(matchBrowserLocale(appLocales, browserLocales)).toBe('gb')
+  })
+
+  test('matches locale when only languages match', () => {
+    const appLocales = ['en-GB', 'en-US']
+    const browserLocales = ['en-IN', 'en']
+
+    expect(matchBrowserLocale(appLocales, browserLocales)).toBe('en-GB')
+  })
 })