# gt-next: General Translation Next.js SDK: 切换语言
URL: https://generaltranslation.com/zh/docs/next/guides/languages.mdx
---
title: 切换语言
description: 如何在 Next.js 应用中配置和切换语言
---

语言切换功能允许用户更改应用内容的首选区域设置。GT Next 提供了多种实现方式，从简单的编程式切换，到结合中间件的完整 URL 路由方案。

## 可用方法

* **编程方式**：用于自定义控件的 [`useSetLocale`](/docs/next/api/helpers/use-set-locale) Hook
* **预置 UI**：带下拉菜单的 [`<LocaleSelector>`](/docs/next/api/components/locale-selector) 组件
* **自定义 UI**：用于构建自定义选择器的 [`useLocaleSelector`](/docs/next/api/helpers/use-locale-selector) Hook
* **基于 URL**：通过 [中间件路由](/docs/next/guides/middleware) 处理 URL 路径中的区域设置

## 使用 `useSetLocale` Hook

[`useSetLocale`](/docs/next/api/helpers/use-set-locale) 是一个客户端 Hook，可让你更改应用的语言：

```tsx
import { useSetLocale } from 'gt-next/client';

export default function MyComponent() {
  const setLocale = useSetLocale();

  return <button onClick={() => setLocale('en')}>设置区域设置</button>;
}
```

只需把你要切换到的区域设置作为参数传给该 hook 返回的函数即可。


## 使用 `<LocaleSelector>` 组件

[`<LocaleSelector>`](/docs/next/api/components/locale-selector) 组件提供了一个可直接使用的下拉菜单，会自动显示所有已配置的区域设置：

```tsx
import { LocaleSelector } from 'gt-next/client';

export default function MyComponent() {
  return <LocaleSelector />;
}
```

此组件会自动：

* 显示项目中已配置的所有区域设置
* 以各自的母语名称显示区域设置
* 处理切换逻辑
* 保持当前的选中状态


## 使用 `useLocaleSelector` Hook

如果你想构建自己的自定义区域设置选择器组件，可以使用 [`useLocaleSelector`](/docs/next/api/helpers/use-locale-selector)：

```tsx
import { useLocaleSelector } from 'gt-next/client';

function CustomLocaleSelector() {
  const { 
    locale,              // 当前活动的区域设置（例如 'en'、'es'）
    locales,             // 项目支持的区域设置数组 ['en', 'es', 'fr']
    setLocale,           // 用于切换区域设置的函数：setLocale('es')
    getLocaleProperties  // 用于获取某个区域设置显示信息的函数
  } = 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。有关这种方法的更多信息，请参阅 [Middleware 指南](/docs/next/guides/middleware)：

```
/en/products  → English products page  
/es/products  → Spanish products page
/fr/products  → French products page
```

这种方法可带来 SEO 优势、各语言版本的直达链接，以及便于分享的本地化链接。


## 重要说明

### 仅适用于客户端组件

所有语言切换 Hook 和组件都必须在标有 `'use client'` 的客户端组件中使用：

```tsx
'use client';
import { useSetLocale } from 'gt-next/client';

function LanguageSwitcher() {
  const setLocale = useSetLocale();
  // ... 组件逻辑
}
```


### GTProvider 要求

语言切换组件必须在 [`<GTProvider>`](/docs/next/api/components/gtprovider) 中使用：

```tsx
// ✅ 正确
<GTProvider>
  <LanguageSwitcher />
</GTProvider>

// ❌ 错误 - 在 provider 外部
<LanguageSwitcher />
```


## 后续步骤

* [Middleware 指南](/docs/next/guides/middleware) - 基于 URL 的语言路由
* [动态内容指南](/docs/next/guides/dynamic-content) - runtime 内容翻译
* API 参考：
  * [`useSetLocale` Hook](/docs/next/api/helpers/use-set-locale)
  * [`<LocaleSelector>` 组件](/docs/next/api/components/locale-selector)