Nuxt I18n Micro

Appearance

🌍 useLocaleHead Composable ​

The useLocaleHead composable is a utility in Nuxt I18n Micro that helps you manage SEO attributes and HTML meta tags for localized routes. It dynamically generates attributes for the lang and dir of the HTML document and creates meta and link tags to improve the SEO of your localized content.

⚙️ Options ​

ts
useLocaleHead(options: UseLocaleHeadOptions): { metaObject: Ref<{ htmlAttrs: { dir?: "ltr" | "rtl" | "auto"; lang?: string }; link: { href: string; hreflang?: string; rel: string; [key: string]: string | undefined }[]; meta: { content: string; property: string; [key: string]: string }[] }, MetaObject | { htmlAttrs: { dir?: "ltr" | "rtl" | "auto"; lang?: string }; link: { href: string; hreflang?: string; rel: string; [key: string]: string | undefined }[]; meta: { content: string; property: string; [key: string]: string }[] }>; updateMeta: () => void }

The SEO head tags for the current route: hreflang alternates for every locale plus x-default, a canonical link, og:locale, and lang/dir on <html>.

Only needed when meta is disabled or the defaults need adjusting — with meta: true the module registers the same tags itself.

ParameterTypeDescription
optionsUseLocaleHeadOptions

Returns — a ref holding the head object, ready to pass to useHead

ts
const head = useLocaleHead({ addSeoAttributes: true })
useHead(head)

🛠️ Return Values ​

The useLocaleHead composable returns a reactive object and an updater function you should call when source data changes. Both shapes are in the signature above, generated from the source.

metaObject ​

Reactive head payload (html attrs, meta, link) suitable for useHead(metaObject).

  • Example:
    js
    const { metaObject } = useLocaleHead()
useHead(metaObject)

updateMeta ​

Recomputes metaObject based on current route, locale and config. Call it when inputs change — on a route change, for example.

  • Example:
    js
    const { metaObject, updateMeta } = useLocaleHead()
useHead(metaObject)
watch(
  () => route.fullPath,
  () => updateMeta(),
  { immediate: true },
)

The link and meta arrays are accessible via metaObject.value:

  • Example:
    js
    const { metaObject, updateMeta } = useLocaleHead()
updateMeta()
console.log(metaObject.value.link)
// Output: [{ id: 'i18n-can', rel: 'canonical', href: 'https://example.com/about' }, ...]
console.log(metaObject.value.meta)
// Output: [{ id: 'i18n-og', property: 'og:locale', content: 'en_US' }, ...]

🛠️ Example Usages ​

Basic Usage ​

Generate locale-specific head attributes with default options.

js
const head = useLocaleHead()

Customize Identifier Attribute ​

Use a custom identifier attribute for the generated tags.

js
const head = useLocaleHead({ identifierAttribute: 'data-i18n' })

Disable SEO Attributes ​

Generate head attributes without adding SEO-related meta and link tags.

js
const head = useLocaleHead({ addSeoAttributes: false })

Specify a Base URL ​

Set a custom base URL for canonical and alternate URLs.

js
const head = useLocaleHead({ baseUrl: 'https://mywebsite.com' })

🚀 Additional Features ​

When addSeoAttributes is enabled, the composable automatically generates the following tags:

  • og:locale for the current locale (language_TERRITORY, underscore). Derived from locale.og or converted from locale.iso when possible.
  • og:url for the canonical URL of the page.
  • og:locale:alternate for alternate language versions.
  • rel="canonical" and rel="alternate" links for SEO optimization.
  • hreflang="x-default" link pointing to the default locale's URL. This tells search engines which URL to show users whose language doesn't match any of the defined locales.

Dynamic Locale and Direction ​

The composable dynamically determines the lang and dir attributes based on the current route's locale, ensuring that your HTML document is correctly configured for international users.

Handling Localized Routes ​

If your routes are prefixed with locale codes (e.g., /en/about), the composable intelligently adjusts the full path for generating URLs, ensuring that SEO attributes are accurate and relevant.

This composable simplifies the process of optimizing your Nuxt application for international audiences, ensuring that your site is well-prepared for global search engines and users.

🛠️ Example Usage ​

The following example demonstrates how to use the useLocaleHead composable within a Vue component with default settings:

vue
<script setup>
import { useRoute, watch } from '#imports'
const route = useRoute()
const { metaObject, updateMeta } = useLocaleHead({
  addDirAttribute: true,
  identifierAttribute: 'id',
  addSeoAttributes: true,
})
useHead(metaObject)
watch(
  () => route.fullPath,
  () => updateMeta(),
  { immediate: true },
)
</script>

Explanation of the Code ​

  • useLocaleHead Composable: This composable is called in the <script setup> section and returns an object containing htmlAttrs, meta, and link.

  • <html> Tag: The lang and dir attributes for the HTML document are dynamically determined based on the current locale and are applied to the <html> tag.

  • <head> Section:

    • Meta Tags: SEO-related meta tags are generated, including og:locale, og:url, and rel="canonical" and rel="alternate" tags to specify alternate language versions of the page.
    • Link Tags: Canonical links, links to alternate language versions, and the hreflang="x-default" link (pointing to the default locale URL) are included.

  • <body> Section: The main content of the page is displayed here. In this example, a simple header and paragraph are used.

📝 Notes ​

  1. Attributes: The attributes used (lang, dir, rel, href, hreflang, property, content) are extracted from the object returned by useLocaleHead.

  2. SEO Tags Generation: If the addSeoAttributes option is set to true, the composable automatically generates SEO tags for the current locale.

  3. Base URL: You can set your custom base URL using the baseUrl option to correctly generate canonical and alternate links.

This example demonstrates how easy it is to integrate useLocaleHead into your application's components to ensure correct SEO attributes and improve the search engine indexing of localized pages.

🧩 Customization & Lifecycle ​

  • useLocaleHead does not subscribe to changes by itself. It returns metaObject and updateMeta.
  • You should call updateMeta() when inputs change (typically on route change), for example from a plugin:
ts
// plugins/02.meta.ts
export default defineNuxtPlugin(() => {
  const route = useRoute()
  const { metaObject, updateMeta } = useLocaleHead({ baseUrl: 'https://example.com' })
  useHead(metaObject)
  if (import.meta.server) updateMeta()
  else
    watch(
      () => route.fullPath,
      () => updateMeta(),
      { immediate: true },
    )
})

When to use useI18nHead instead ​

When meta: true (the default), prefer useI18nHead for per-page overrides (custom hreflang, extra og:title, partial disable). Use useLocaleHead directly only when meta: false or you manage useHead yourself.

Released under the MIT License.