Guides

I18n & Localization

Copy for LLMs
Last updated by
Harlan Wilton
 in fix: normalize incorrect BCP 47 locales.

Introduction

Nuxt SEO Utils automatically sets the <html lang="..."> attribute and locale-based meta tags for your site.

How is Locale Used?

Nuxt SEO Utils will automatically set:

  • <html lang="..."> - Current locale based on your configuration
  • og:locale - OpenGraph locale (e.g., en_US, ja_JP)
  • Schema.org inLanguage - For WebSite, WebPage, and other structured data (when using Nuxt Schema.org)
  • useBreadcrumbItems() - Automatically handles locale-prefixed routes and translates labels via i18n keys (breadcrumb.items.{routeName}.label)
og:locale requires a locale format with underscore (e.g., en_US). If your locale is just "en", the module won't set og:locale automatically.

How Locale is Determined

When automaticDefaults is enabled (default), the module sets the lang attribute using this priority:

  1. @nuxtjs/i18n or nuxt-i18n-micro module - Automatically detected and integrated
  2. Site Config currentLocale - Dynamic locale from useSiteConfig()
  3. Site Config defaultLocale - Static default from nuxt.config.ts
  4. Fallback - Defaults to "en"

The locale is set with low priority, allowing you to override it manually if needed.

Setting up Nuxt SEO Utils for I18n

If you're building a multilingual site, install @nuxtjs/i18n.

For single language sites without @nuxtjs/i18n, set the locale via Site Config:

nuxt.config.ts
export default defineNuxtConfig({
  site: {
    defaultLocale: 'ja-JP'
  }
})
Set your locale as specific as possible using BCP 47 format (hyphen-separated). Instead of en, use en-US, en-AU, or whatever is appropriate for your site. The module automatically converts this to underscore format (en_US) for og:locale.

Dynamic Locale Changes

If you need to change the locale dynamically without using the I18n module, use updateSiteConfig():

<script setup>
updateSiteConfig({
  currentLocale: 'ja-JP'
})
</script>

Manual Control

To manually control all locale settings, disable automatic defaults:

nuxt.config.ts
export default defineNuxtConfig({
  seo: {
    automaticDefaults: false
  }
})

Then set everything manually:

app.vue
useHead({
  htmlAttrs: { lang: 'ja-JP' }
})

useSeoMeta({
  ogLocale: 'ja_JP'
})
Edit this page
Markdown For LLMs
Did this page help you?

SEO Route Rules

Utilise route rules for dynamic SEO meta tags.

Config