语言切换 - Lingo.dev

Alpha

Lingo.dev Compiler 目前处于 alpha 阶段，尚不稳定，不建议用于生产环境，且 API 可能会在不同版本之间发生变化。

Lingo.dev Compiler 提供了 useLingoContext() hook，用于在运行时读取和切换当前 locale。你可以用它构建语言切换器、具备 locale 感知能力的组件，或任何会根据用户语言偏好动态响应的 UI。

useLingoContext() hook#

这个 hook 会返回一个对象，其中包含当前 locale，以及一个用于切换 locale 的函数：

tsx

import { useLingoContext } from "@lingo.dev/compiler/react";

const { locale, setLocale } = useLingoContext();

属性	类型	说明
`locale`	`string`	当前生效的 locale 代码（例如 `"en"`、`"es"`）。
`setLocale`	`(locale: string) => void`	设置新的 locale。默认会触发持久化并重新加载页面。

语言切换器示例#

一个下拉式语言切换器组件示例：

tsx

"use client"; // Required for Next.js App Router

import { useLingoContext } from "@lingo.dev/compiler/react";

const localeLabels: Record<string, string> = {
  en: "English",
  es: "Espanol",
  de: "Deutsch",
  fr: "Francais",
  ja: "日本語",
};

export function LanguageSwitcher() {
  const { locale, setLocale } = useLingoContext();

  return (
    <select value={locale} onChange={(e) => setLocale(e.target.value)}>
      {Object.entries(localeLabels).map(([code, label]) => (
        <option key={code} value={code}>
          {label}
        </option>
      ))}
    </select>
  );
}

在 Next.js 中，语言切换器必须是 Client Component（"use client"），因为它用到了 React hook。

调用 setLocale 后会发生什么#

locale 会被持久保存

默认情况下，新的 locale 会被保存到名为 locale 的 cookie 中，最长保留 1 年。这样即使页面刷新或浏览器重启，语言偏好也能继续保留。

页面会重新加载

页面会重新加载，并使用新的 locale 重新渲染所有组件。Server Components 会在服务端获取新 locale 的翻译，Client Components 则会收到更新后的字典。

后续请求会使用新的 locale

在下一次页面加载时，Compiler 会读取已持久化的 locale，并返回对应的翻译内容。

持久化选项#

默认的持久化机制基于 cookie，并通过 localePersistence 配置：

{
  localePersistence: {
    type: "cookie",
    config: {
      name: "locale",       // Cookie name
      maxAge: 31536000,     // 1 year in seconds
    },
  },
}

选项	默认值	说明
`type`	`"cookie"`	持久化机制。
`config.name`	`"locale"`	Cookie 名称。
`config.maxAge`	`31536000`	Cookie 有效期（秒）。

自定义持久化#

如果你使用基于 URL 的 locale 路由、localStorage，或基于自定义请求头的检测方式，可以创建自定义 locale 解析器。客户端解析器中的 persistLocale 导出，决定了调用 setLocale 时会发生什么：

// .lingo/locale-resolver.client.ts
export function resolveLocale(): string {
  return localStorage.getItem("locale") || "en";
}

export function persistLocale(locale: string): void {
  localStorage.setItem("locale", locale);
  window.location.reload();
}

如需查看基于 URL、cookie 和请求头的完整示例，请参阅 Custom Locale Resolvers。

只读取 locale，不做切换#

如果你只需要读取当前 locale 用于展示或条件渲染，而不提供切换器，也可以使用同一个 hook：

tsx

"use client";

import { useLingoContext } from "@lingo.dev/compiler/react";

export function LocaleBadge() {
  const { locale } = useLingoContext();
  return <span>{locale.toUpperCase()}</span>;
}

下一步#

Custom Locale Resolvers

基于 URL、localStorage 和请求头的持久化

配置参考

localePersistence 选项

Next.js 集成

Server Component 与 Client Component 的行为

Vite + React

客户端 locale 切换