feat(Link): auto-localize internal links when @nuxtjs/i18n is installed (#5537)

Co-authored-by: Bobbie Goede <bobbiegoede@gmail.com>

Author: benjamincanac

docs/content/docs/1.getting-started/6.integrations/4.i18n/1.nuxt.md

@@ -161,6 +161,22 @@ const { locale } = useI18n()
 </template>
 ```
 
+#### Automatic link localization :badge{label="Soon" class="align-text-top"}
+
+When `@nuxtjs/i18n` is installed, the [Link](/docs/components/link) component automatically localizes internal links using the `$localePath` helper. This means you don't need to manually wrap your links with `localePath()` or `localeRoute()`.
+
+```vue
+<template>
+  <!-- Automatically becomes /en/about or /fr/about based on current locale -->
+  <ULink to="/about">About</ULink>
+  <UButton to="/contact">Contact</UButton>
+</template>
+```
+
+::tip
+External links and absolute URLs are automatically detected and skip localization. You can still manually use `localePath()` or `localeRoute()` if needed.
+::
+
 ::
 
 ### Dynamic direction

docs/content/docs/2.components/link.md

@@ -75,9 +75,8 @@ slots:
 Link
 ::
 
-## IntelliSense
-
-If you're using VSCode and wish to get autocompletion for the classes `active-class` and `inactive-class`, you can add the following settings to your `.vscode/settings.json`:
+::callout{icon="i-simple-icons-visualstudiocode"}
+If you're using the [Tailwind CSS IntelliSense](https://marketplace.visualstudio.com/items?itemName=bradlc.vscode-tailwindcss) extension for VSCode and wish to get autocompletion for the `active-class` and `inactive-class` props, you can add the following settings to your `.vscode/settings.json`:
 
 ```json [.vscode/settings.json]
 {
@@ -87,6 +86,26 @@ If you're using VSCode and wish to get autocompletion for the classes `active-cl
   ]
 }
 ```
+::
+
+### Locale :badge{label="Soon" class="align-text-top"}
+
+The Link component automatically integrates with [`@nuxtjs/i18n`](https://i18n.nuxtjs.org/) when installed. Internal links are automatically localized using the `$localePath` helper without requiring manual wrapping.
+
+```vue
+<template>
+  <!-- Automatically becomes /en/about or /fr/about based on current locale -->
+  <ULink to="/about">About</ULink>
+</template>
+```
+
+::tip
+You can still manually use `localePath()` or `localeRoute()` if needed.
+::
+
+::note{to="/docs/getting-started/integrations/i18n/nuxt#dynamic-locale"}
+Learn more about Internationalization in Nuxt UI.
+::
 
 ## API
 

src/runtime/components/Link.vue

@@ -110,9 +110,9 @@ import { computed } from 'vue'
 import { isEqual } from 'ohash/utils'
 import { useForwardProps, Slot } from 'reka-ui'
 import { defu } from 'defu'
-import { reactiveOmit } from '@vueuse/core'
 import { hasProtocol } from 'ufo'
-import { useRoute, useAppConfig } from '#imports'
+import { reactiveOmit } from '@vueuse/core'
+import { useRoute, useAppConfig, useNuxtApp } from '#imports'
 import { mergeClasses } from '../utils'
 import { tv } from '../utils/tv'
 import { isPartiallyEqual } from '../utils/link'
@@ -130,6 +130,7 @@ defineSlots<LinkSlots>()
 
 const route = useRoute()
 const appConfig = useAppConfig() as Link['AppConfig']
+const nuxtApp = useNuxtApp()
 
 const nuxtLinkProps = useForwardProps(reactiveOmit(props, 'as', 'type', 'disabled', 'active', 'exact', 'exactQuery', 'exactHash', 'activeClass', 'inactiveClass', 'to', 'href', 'raw', 'custom', 'class'))
 
@@ -145,7 +146,26 @@ const ui = computed(() => tv({
   }, appConfig.ui?.link || {})
 }))
 
-const to = computed(() => props.to ?? props.href)
+const to = computed(() => {
+  const path = props.to ?? props.href
+  if (!path) return path
+
+  // Only localize string paths, leave route objects untouched to preserve state/params
+  if (typeof path !== 'string') return path
+
+  // Skip external links and absolute URLs
+  if (props.external || hasProtocol(path, { acceptRelative: true })) {
+    return path
+  }
+
+  // Use `$localePath` from `@nuxtjs/i18n` if available
+  const localePath = nuxtApp.$localePath as ((route: RouteLocationRaw, locale?: string) => string) | undefined
+  if (localePath) {
+    return localePath(path)
+  }
+
+  return path
+})
 
 const isInternalLink = computed(() => {
   if (!to.value) return false