refactor!: change useLocaleHead options shape and defaults (#3100)

docs/content/docs/5.v9/2.guide/19.breaking-changes-in-v9.md

@@ -63,7 +63,21 @@ Some properties have changed or swapped names to better fit their functionality,
 
 ## SEO - `useLocaleHead`
 
-We have added a `addLangAttribute` property to the options parameter of `useLocaleHead` and `$localeHead`, originally this was not configurable on its own. If you want to keep the same behavior, if you were passing `addSeoAttributes`, you will also have to pass `addLangAttribute: true`. See [`useLocaleHead`](/docs/v9/api#useLocaleHead)
+The options parameter for `useLocaleHead` and `$localeHead` as changed in shape, having less verbose property names, as well as enabling the options by default.
+
+This table compares the option properties of `useLocaleHead` and `$localeHead for v8 and v9:
+
+| v8 | v9 | Notes |
+| --- | --- | --- |
+| `-` | `lang` | New property to configure the `lang` html attributes, default: `true` |
+| `addDirAttributes` | `dir` | Default changed: `false` -> `true` |
+| `addSeoAttributes` | `seo` | Default changed: `false` -> `true` |
+| `identifierAttribute` | `key` | |
+
+We have added a `lang` property to the options parameter of `useLocaleHead` and `$localeHead`, originally this was not configurable on its own, see [`useLocaleHead`](/docs/v9/api#useLocaleHead) for details on its usage.
+
+
+
 
 ## Nuxt context functions
 

docs/content/docs/5.v9/2.guide/6.seo.md

@@ -77,12 +77,7 @@ To avoid duplicating the code, it's recommended to set globally with [Meta Compo
 <script setup>
 const route = useRoute()
 const { t } = useI18n()
-const head = useLocaleHead({
-  addDirAttribute: true,
-  addLangAttribute: true,
-  identifierAttribute: 'id',
-  addSeoAttributes: true
-})
+const head = useLocaleHead()
 const title = computed(() => t(route.meta.title ?? 'TBD', t('layouts.title'))
 );
 </script>

docs/content/docs/5.v9/4.api/1.index.md

@@ -88,7 +88,7 @@ Example:
 ```vue
 <script setup>
 const i18nHead = useLocaleHead({
-  addSeoAttributes: {
+  seo: {
     canonicalQueries: ['foo']
   }
 })
@@ -114,25 +114,25 @@ declare function useLocaleHead(options: I18nHeadOptions): Ref<I18nHeadMetaInfo>
 
 An object accepting the following optional fields:
 
-- `addDirAttribute`
+- `dir`
 
   **Type**: `Boolean`
 
-  Adds a `dir` attribute to the HTML element. default `false`.
+  Adds a `dir` attribute to the HTML element. default `true`.
 
-- `addLangAttribute`
+- `lang`
 
   **Type**: `Boolean`
 
-  Adds a `lang` attribute to the HTML element. default `false`.
+  Adds a `lang` attribute to the HTML element. default `true`.
 
-- `addSeoAttributes`
+- `seo`
 
   **Type**: `boolean | SeoAttributesOptions`
 
-  Adds various SEO attributes. default `false`.
+  Adds various SEO attributes. default `true`.
 
-- `identifierAttribute`
+- `key`
 
   **Type**: `String`
 

docs/content/docs/5.v9/4.api/5.vue.md

@@ -61,7 +61,7 @@ See also [Link localizing](/docs/getting-started/usage)
 
 The `options` object accepts these optional properties:
 
-- `addDirAttribute` (type: `boolean`) - Adds a `dir` attribute to the HTML element. Default: `false`
-- `addSeoAttributes` (type: `boolean | SeoAttributesOptions`) - Adds various SEO attributes. Default: `false`
+- `dir` (type: `boolean`) - Adds a `dir` attribute to the HTML element. Default: `false`
+- `seo` (type: `boolean | SeoAttributesOptions`) - Adds various SEO attributes. Default: `false`
 
 See also [SEO](/docs/guide/seo)

specs/fixtures/basic/pages/index.vue

@@ -7,13 +7,7 @@ import LangSwitcher from '../components/LangSwitcher.vue'
 
 const { t } = useI18n()
 const localePath = useLocalePath()
-const i18nHead = useLocaleHead({
-  addLangAttribute: true,
-  addDirAttribute: true,
-  identifierAttribute: 'id',
-  addSeoAttributes: { canonicalQueries: ['page'] },
-  router: useRouter()
-})
+const i18nHead = useLocaleHead({ key: 'id', seo: { canonicalQueries: ['page'] } })
 const { data, refresh } = useAsyncData('home', () =>
   Promise.resolve({
     aboutPath: localePath('about'),

specs/fixtures/basic_usage/layouts/default.vue

@@ -5,12 +5,7 @@ import { useI18n, useLocaleHead } from '#i18n'
 
 const route = useRoute()
 const { t } = useI18n()
-const head = useLocaleHead({
-  addDirAttribute: true,
-  addLangAttribute: true,
-  identifierAttribute: 'id',
-  addSeoAttributes: { canonicalQueries: ['page'] }
-})
+const head = useLocaleHead({ key: 'id', seo: { canonicalQueries: ['page'] } })
 const title = computed(() => `Page - ${t(route.meta?.title ?? '')}`)
 </script>
 

specs/fixtures/basic_usage/pages/composables.vue

@@ -6,7 +6,7 @@ const localePath = useLocalePath()
 const localeRoute = useLocaleRoute()
 const switchLocalePath = useSwitchLocalePath()
 const routeBaseName = useRouteBaseName()
-const localeHead = useLocaleHead({ addDirAttribute: true, addSeoAttributes: true, identifierAttribute: 'id' })
+const localeHead = useLocaleHead({ key: 'id' })
 
 const metaTestEntries = computed(() => [
   { id: 'locale-path', content: localePath('/nested/test-route') },

specs/fixtures/basic_usage/pages/index.vue

@@ -7,7 +7,6 @@ import {
   useAppConfig,
   useAsyncData,
   useHead,
-  useNuxtApp,
   useRoute,
   useRuntimeConfig,
   watch
@@ -62,12 +61,7 @@ definePageMeta({
   alias: ['/aliased-home-path']
 })
 
-const i18nHead = useLocaleHead({
-  addDirAttribute: true,
-  addLangAttribute: true,
-  identifierAttribute: 'id',
-  addSeoAttributes: { canonicalQueries: ['page'] }
-})
+const i18nHead = useLocaleHead({ key: 'id', seo: { canonicalQueries: ['page'] } })
 useHead({
   htmlAttrs: {
     lang: i18nHead.value.htmlAttrs!.lang

specs/fixtures/basic_usage/pages/nuxt-context-extension.vue

@@ -6,6 +6,6 @@
     <p id="switch-locale-path">{{ $nuxt.$switchLocalePath('ja') }}</p>
     <p id="locale-path">{{ $nuxt.$localePath('nuxt-context-extension', 'nl') }}</p>
     <p id="locale-route">{{ JSON.stringify($nuxt.$localeRoute()) }}</p>
-    <p id="locale-head">{{ $nuxt.$localeHead({ addLangAttribute: true }) }}</p>
+    <p id="locale-head">{{ $nuxt.$localeHead({ dir: false }) }}</p>
   </div>
 </template>

specs/fixtures/different_domains/pages/index.vue

@@ -1,18 +1,13 @@
 <script setup lang="ts">
 import { watchEffect } from 'vue'
-import { useAsyncData, useHead, useRouter } from '#imports'
+import { useAsyncData, useHead } from '#imports'
 import { useI18n, useLocalePath, useLocaleHead } from '#i18n'
 import BasicUsage from '../components/BasicUsage.vue'
 import LangSwitcher from '../components/LangSwitcher.vue'
 
 const { t } = useI18n()
 const localePath = useLocalePath()
-const i18nHead = useLocaleHead({
-  addDirAttribute: true,
-  identifierAttribute: 'id',
-  addSeoAttributes: { canonicalQueries: ['page'] },
-  router: useRouter()
-})
+const i18nHead = useLocaleHead({ key: 'id', seo: { canonicalQueries: ['page'] } })
 const { data, refresh } = useAsyncData('home', () =>
   Promise.resolve({
     aboutPath: localePath('about'),

specs/fixtures/inline_options/pages/index.vue

@@ -1,18 +1,13 @@
 <script setup lang="ts">
 import { watchEffect } from 'vue'
-import { useAsyncData, useHead, useRouter } from '#imports'
+import { useAsyncData, useHead } from '#imports'
 import { useI18n, useLocalePath, useLocaleHead } from '#i18n'
 import BasicUsage from '../components/BasicUsage.vue'
 import LangSwitcher from '../components/LangSwitcher.vue'
 
 const { t } = useI18n()
 const localePath = useLocalePath()
-const i18nHead = useLocaleHead({
-  addDirAttribute: true,
-  identifierAttribute: 'id',
-  addSeoAttributes: { canonicalQueries: ['page'] },
-  router: useRouter()
-})
+const i18nHead = useLocaleHead({ key: 'id', seo: { canonicalQueries: ['page'] } })
 const { data, refresh } = useAsyncData('home', () =>
   Promise.resolve({
     aboutPath: localePath('about'),

specs/fixtures/issues/2590/app.vue

@@ -7,15 +7,9 @@
 <script setup lang="ts">
 const { locale, locales, setLocale } = useI18n()
 
-const head = useLocaleHead({
-  addDirAttribute: true,
-  addLangAttribute: true,
-  addSeoAttributes: true
-})
+const head = useLocaleHead()
 
-useHead({
-  htmlAttrs: head.value.htmlAttrs
-})
+useHead({ htmlAttrs: head.value.htmlAttrs })
 
 console.log(head.value.htmlAttrs)
 

specs/fixtures/lazy/pages/index.vue

@@ -6,7 +6,7 @@ import LangSwitcher from '../components/LangSwitcher.vue'
 
 const { t } = useI18n()
 const localePath = useLocalePath()
-const i18nHead = useLocaleHead({ addLangAttribute: true, addSeoAttributes: { canonicalQueries: ['page'] } })
+const i18nHead = useLocaleHead({ seo: { canonicalQueries: ['page'] } })
 const { data, refresh } = useAsyncData('home', () =>
   Promise.resolve({
     aboutPath: localePath('about'),

specs/fixtures/multi_domains_locales/pages/index.vue

@@ -7,12 +7,7 @@ import LangSwitcher from '../components/LangSwitcher.vue'
 
 const { t } = useI18n()
 const localePath = useLocalePath()
-const i18nHead = useLocaleHead({
-  addDirAttribute: true,
-  identifierAttribute: 'id',
-  addSeoAttributes: { canonicalQueries: ['page'] },
-  router: useRouter()
-})
+const i18nHead = useLocaleHead({ key: 'id', seo: { canonicalQueries: ['page'] } })
 const { data, refresh } = useAsyncData('home', () =>
   Promise.resolve({
     aboutPath: localePath('about'),

specs/fixtures/restructure/pages/index.vue

@@ -6,7 +6,7 @@ import LangSwitcher from '../components/LangSwitcher.vue'
 
 const { t } = useI18n()
 const localePath = useLocalePath()
-const i18nHead = useLocaleHead({ addLangAttribute: true, addSeoAttributes: { canonicalQueries: ['page'] } })
+const i18nHead = useLocaleHead({ lang: true, seo: { canonicalQueries: ['page'] } })
 const { data, refresh } = useAsyncData('home', () =>
   Promise.resolve({
     aboutPath: localePath('about'),

src/runtime/composables/index.ts

@@ -39,7 +39,7 @@ export * from './shared'
  * @public
  */
 export type SetI18nParamsFunction = (params: Partial<Record<Locale, unknown>>) => void
-export function useSetI18nParams(seoAttributes?: SeoAttributesOptions): SetI18nParamsFunction {
+export function useSetI18nParams(seo?: SeoAttributesOptions): SetI18nParamsFunction {
   const common = initCommonComposableOptions()
   const head = getActiveHead()
   const i18n = getComposer(common.i18n)
@@ -86,18 +86,18 @@ export function useSetI18nParams(seoAttributes?: SeoAttributesOptions): SetI18nP
     // Adding SEO Meta
     if (locale && i18n.locales) {
       // Hard code to 'id', this is used to replace payload before ssr response
-      const idAttribute = 'id'
+      const key = 'id'
 
       // prettier-ignore
       metaObject.link.push(
-        ...getHreflangLinks(common, locales, idAttribute),
-        ...getCanonicalLink(common, idAttribute, seoAttributes)
+        ...getHreflangLinks(common, locales, key),
+        ...getCanonicalLink(common, key, seo)
       )
 
       metaObject.meta.push(
-        ...getOgUrl(common, idAttribute, seoAttributes),
-        ...getCurrentOgLocale(currentLocale, currentLocaleLanguage, idAttribute),
-        ...getAlternateOgLocales(locales, currentLocaleLanguage, idAttribute)
+        ...getOgUrl(common, key, seo),
+        ...getCurrentOgLocale(currentLocale, currentLocaleLanguage, key),
+        ...getAlternateOgLocales(locales, currentLocaleLanguage, key)
       )
     }
 
@@ -136,10 +136,10 @@ export type LocaleHeadFunction = (options: I18nHeadOptions) => ReturnType<typeof
  * @public
  */
 export function useLocaleHead({
-  addDirAttribute = false,
-  addLangAttribute = false,
-  addSeoAttributes = false,
-  identifierAttribute = 'hid'
+  dir = true,
+  lang = true,
+  seo = true,
+  key = 'hid'
 }: I18nHeadOptions = {}): Ref<I18nHeadMetaInfo> {
   const common = initCommonComposableOptions()
   const metaObject: Ref<I18nHeadMetaInfo> = ref({
@@ -157,12 +157,7 @@ export function useLocaleHead({
   }
 
   function updateMeta() {
-    metaObject.value = localeHead(common, {
-      addDirAttribute,
-      addLangAttribute,
-      addSeoAttributes,
-      identifierAttribute
-    })
+    metaObject.value = localeHead(common, { dir, lang, seo, key })
   }
 
   if (import.meta.client) {