Nuxt I18n 模块使用指南:从基础配置到路由本地化
前言
在构建多语言应用时,国际化(i18n)是一个不可或缺的功能。Nuxt I18n 模块为 Nuxt.js 应用提供了完整的国际化解决方案,本文将详细介绍如何从零开始配置和使用这个强大的模块。
基础配置
1. 模块安装与配置
首先需要在 Nuxt 配置文件中添加模块并定义语言环境(locales)。每个语言环境需要包含以下关键属性:
code
: 必填项,作为语言的唯一标识符name
: 语言名称,用于用户界面展示file
: 包含翻译信息的 JSON 文件
export default defineNuxtConfig({
modules: ['@nuxtjs/i18n'],
i18n: {
defaultLocale: 'en', // 默认语言
locales: [
{ code: 'en', name: 'English', file: 'en.json' },
{ code: 'nl', name: 'Nederlands', file: 'nl.json' }
]
}
})
2. 翻译文件结构
按照约定,翻译文件应放置在项目根目录的 /i18n/locales
文件夹下。每个语言对应一个 JSON 文件,包含键值对形式的翻译内容。
示例翻译文件:
// en.json
{
"welcome": "Welcome"
}
// nl.json
{
"welcome": "Welkom"
}
基本使用
1. 语言切换器实现
在页面组件中,我们可以使用 useI18n
组合式函数来实现语言切换功能:
<script setup>
const { locales, setLocale } = useI18n()
</script>
<template>
<div>
<button
v-for="locale in locales"
:key="locale.code"
@click="setLocale(locale.code)"
>
{{ locale.name }}
</button>
<h1>{{ $t('welcome') }}</h1>
</div>
</template>
这段代码实现了:
- 遍历所有配置的语言环境,生成切换按钮
- 点击按钮时调用
setLocale
切换语言 - 使用
$t
方法显示当前语言的翻译文本
2. 自动导入说明
Nuxt 会自动导入 useI18n
等组合式函数。如果禁用了自动导入功能,需要手动从 #imports
导入:
<script setup>
import { useI18n, useLocalePath } from '#imports'
// 其他代码...
</script>
路由本地化
1. 本地化路由解析
Nuxt I18n 会为每个路由生成本地化版本。使用 $localePath
或 useLocalePath
可以获取当前语言的本地化路由路径。
<template>
<!-- 使用全局函数 -->
<NuxtLink :to="$localePath('index')">首页</NuxtLink>
<!-- 使用组合式函数 -->
<NuxtLink :to="localePath({ name: 'user-profile' })">个人资料</NuxtLink>
</template>
<script setup>
const localePath = useLocalePath()
</script>
2. 语言切换路由
$switchLocalePath
或 useSwitchLocalePath
可以获取当前页面在不同语言下的路由路径:
<template>
<NuxtLink :to="switchLocalePath('en')">English</NuxtLink>
<NuxtLink :to="switchLocalePath('nl')">Nederlands</NuxtLink>
</template>
<script setup>
const switchLocalePath = useSwitchLocalePath()
</script>
3. 高级路由处理
对于需要编程式导航的场景,可以使用 useLocaleRoute
获取完整的路由对象:
<script setup>
const localeRoute = useLocaleRoute()
function navigateToProfile() {
const route = localeRoute({
name: 'user-profile',
query: { tab: 'settings' }
})
if (route) {
navigateTo(route.fullPath)
}
}
</script>
<template>
<button @click="navigateToProfile">前往设置</button>
</template>
最佳实践建议
-
类型安全:在 Nuxt 配置中启用
typedPages
可以获得更好的类型提示和开发体验。 -
路由命名:始终使用路由名称而非路径来引用路由,这样即使路由结构发生变化,代码也能保持正确。
-
默认语言:虽然可选,但强烈建议设置
defaultLocale
作为回退语言。 -
文件组织:保持翻译文件的目录结构清晰,便于维护和扩展。
通过本文的介绍,您应该已经掌握了 Nuxt I18n 模块的基础使用方法。从简单的文本翻译到复杂的路由本地化,这个模块提供了全面的解决方案,能够满足大多数国际化需求。
创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考