语言切换
如何在你的 Next.js 应用中配置并切换语言
语言切换允许用户更改其首选的 locale，以查看你的应用内容。GT Next 提供多种方式，从简单的编程式切换到结合 middleware 的完整 URL 路由方案。
可用方式
- 以代码实现：用于自定义控制的
useSetLocale钩子 - 预置 UI：带下拉菜单的
<LocaleSelector>组件 - 自定义 UI：用于构建自定义选择器的
useLocaleSelector钩子 - 基于 URL：在 URL 路径中设置 locale 的 Middleware 路由
使用 useSetLocale 钩子
useSetLocale 是一个运行在客户端的钩子，可用于切换应用的语言：
import { useSetLocale } from 'gt-next/client';
export default function MyComponent() {
const setLocale = useSetLocale();
return <button onClick={() => setLocale('en')}>设置语言</button>;
}只需将要切换的 locale 作为参数传递给该 hook 返回的函数即可。
使用 <LocaleSelector> 组件
<LocaleSelector> 组件提供了一个即用型下拉菜单，会自动显示所有已配置的 locale：
import { LocaleSelector } from 'gt-next/client';
export default function MyComponent() {
return <LocaleSelector />;
}该组件会自动：
- 显示项目中已配置的所有 locale
- 以各自的本地语言名称显示 locale
- 处理切换逻辑
- 保持当前选择状态
使用 useLocaleSelector 钩子
如果你需要构建自定义的 locale 选择器组件，请使用 useLocaleSelector：
import { useLocaleSelector } from 'gt-next/client';
function CustomLocaleSelector() {
const {
locale, // 当前生效的 locale（例如：'en'、'es'）
locales, // 项目支持的 locale 列表 ['en'、'es'、'fr']
setLocale, // 更改 locale 的函数：setLocale('es')
getLocaleProperties // 获取某个 locale 显示信息的函数
} = useLocaleSelector();
if (!locales?.length) return null;
return (
<select
value={locale || ''}
onChange={(e) => setLocale(e.target.value)}
>
{locales.map((loc) => {
const props = getLocaleProperties(loc);
return (
<option key={loc} value={loc}>
{props.nativeNameWithRegionCode} {/* 例如："English (US)"、"Español (ES)" */}
</option>
);
})}
</select>
);
}基于 URL 的语言切换
为提升 SEO 和用户体验，你可以通过中间件路由在 URL 中包含 locale。可在 Middleware 指南 中了解此方法的更多信息：
/en/products → 英文产品页
/es/products → 西班牙文产品页
/fr/products → 法文产品页这种方式带来 SEO 优势、可直接访问的各语种版本链接，以及便于分享的本地化链接。
重要注意事项
仅限客户端组件
所有用于语言切换的 hook 和组件必须在带有 'use client' 标记的客户端组件中使用：
'use client';
import { useSetLocale } from 'gt-next/client';
function LanguageSwitcher() {
const setLocale = useSetLocale();
// ... 组件逻辑
}GTProvider 要求
语言切换组件必须在 <GTProvider> 内使用：
// ✅ 正确
<GTProvider>
<LanguageSwitcher />
</GTProvider>
// ❌ 错误 - 在 GTProvider 外部
<LanguageSwitcher />下一步
- Middleware 指南 - 基于 URL 的语言路由
- 动态内容指南 - 运行时内容翻译
- API 参考：
本指南如何?