Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
benjamincanac merged 10 commits into from
Apr 17, 2026
Merged

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
ba407ae
feat(Link): automatically use `localePath` from `@nuxtjs/i18n`
benjamincanac Nov 26, 2025
32e8343
Merge branch 'v4' into feat/5536
benjamincanac Dec 8, 2025
2a8c9ba
Update src/runtime/components/Link.vue
benjamincanac Dec 8, 2025
3474576
Apply suggestion from @benjamincanac
benjamincanac Dec 8, 2025
c8a7002
up
benjamincanac Dec 8, 2025
b0b0493
up
benjamincanac Dec 8, 2025
1ba5a09
Merge branch 'v4' into feat/5536
benjamincanac Apr 17, 2026
27b9ced
refactor(Link): use `$localePath` instead of `$localeRoute` for i18n …
benjamincanac Apr 17, 2026
6503cde
up
benjamincanac Apr 17, 2026
4ca5bc7
up
benjamincanac Apr 17, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 16 additions & 0 deletions docs/content/docs/1.getting-started/6.integrations/4.i18n/1.nuxt.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
25 changes: 22 additions & 3 deletions docs/content/docs/2.components/link.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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]
{
Expand All @@ -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.
::
Comment thread
coderabbitai[bot] marked this conversation as resolved.

::note{to="/docs/getting-started/integrations/i18n/nuxt#dynamic-locale"}
Learn more about Internationalization in Nuxt UI.
::

## API

Expand Down
26 changes: 23 additions & 3 deletions src/runtime/components/Link.vue
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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'
Expand All @@ -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'))

Expand All @@ -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
})
Comment on lines +149 to +168
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai Bot Apr 17, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

🧩 Analysis chain

🌐 Web query:

@nuxtjs/i18n $localePath accept a locale argument signature and behavior

💡 Result:

Yes, $localePath in @nuxtjs/i18n accepts a locale argument as the second parameter. It is the global function provided by the module (also available via the useLocalePath composable), used to resolve a localized path for a given route. Signature (from TypeScript definition): (localePath function): (route: RawLocation | RouteLocation, locale?: Locale) => string Parameters: - route (first argument, required): Route name (string), path (string), or route object (e.g., { name: 'index' } or { name: 'category-slug', params: { slug: 'value' } }) - locale (second argument, optional): Locale code string (e.g., 'en', 'fr'). Defaults to the current locale if omitted. Behavior: - Returns the path localized according to the specified locale (or current locale). - Prefixes the path with the locale code based on the routing strategy (e.g., '/en/index' for prefix strategy). - Supports route params for dynamic routes. - Use in templates: <NuxtLink :to="$localePath('index', 'en')"> - In <script setup>: const localePath = useLocalePath; localePath('index', 'en') Examples: - $localePath('index') → '/en' (current locale 'en') - $localePath('index', 'fr') → '/fr' - $localePath({ name: 'products-id', params: { id: 123 } }, 'de') → '/de/produkte/123' (if customized)

Citations:

Add locale prop to allow opt-out and explicit locale targeting before shipping.

The typeof guard at line 154 correctly preserves route objects' state/params. However, the component still lacks control over locale selection. $localePath accepts a locale parameter (e.g., localePath(path, 'fr')), but the current code never uses it, always falling back to the current locale.

Two gaps remain:

  1. No opt-out mechanism: Users intentionally linking to another locale (e.g., /fr/about from an en locale) will have the link silently re-localized, breaking existing use cases. A locale?: boolean | string prop (where locale: false opts out and locale: 'fr' targets a specific locale) would preserve current behavior while enabling cross-locale links.

  2. Double-localization risk: Pre-localized paths like /fr/about passed to an already-localized $localePath across different i18n strategies (prefix, prefix_except_default, etc.) can resolve unpredictably. A locale: false opt-out provides users an escape hatch.

Consider a global app.config toggle (opt-in vs. opt-out behavior by default) alongside the prop to mitigate backward-compat risk for apps already using useLocalePath() output in :to directly.

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@src/runtime/components/Link.vue` around lines 149 - 168, Add a new prop
locale?: boolean | string to the Link component and modify the computed to to
pass the explicit locale to nuxtApp.$localePath when available: if locale ===
false skip calling $localePath and return the raw path (to opt-out/detect
already-localized paths), if locale is a string call localePath(path, locale) to
target a specific locale, and if locale is undefined follow a global app.config
default (e.g., app.config.globalProperties.linkLocaleBehavior or leave current
behavior) so existing use of $localePath remains unchanged; update references in
the computed to check props.locale before invoking nuxtApp.$localePath and keep
the typeof path !== 'string' guard and hasProtocol(props, ...) logic intact.


const isInternalLink = computed(() => {
if (!to.value) return false
Expand Down
Loading