跳转至主要内容
TanStack Start i18n

TanStack Start i18n — 全栈本地化

为你的 TanStack Start 应用添加国际化:支持 SSR、自动语言检测,以及在客户端和服务端都可用的类型安全翻译。

Setup

Set up in 4 steps

Install packages

安装 @better-i18n/use-intl 和 use-intl。无需额外的构建插件或 Babel 转换。

terminal
npm install @better-i18n/use-intl use-intl

Load messages server-side

在根 loader 中获取翻译,使其在首次服务端渲染时便已就绪。客户端无需另外调用 API。

app/routes/__root.tsx
// app/routes/__root.tsx
import { getMessages } from '@better-i18n/use-intl/server';

export const Route = createRootRoute({
  loader: async ({ context }) => {
    const messages = await getMessages({
      projectId: 'your-org/your-project',
      locale: context.locale ?? 'en',
    });
    return { messages, locale: context.locale ?? 'en' };
  },
});

用 BetterI18nProvider 包裹

把 loader 数据传给 BetterI18nProvider。provider 会用服务端加载的同一份文案水合客户端。

app/routes/__root.tsx
// app/routes/__root.tsx (continued)
import { BetterI18nProvider } from '@better-i18n/use-intl';

export function RootComponent() {
  const { messages, locale } = Route.useLoaderData();
  return (
    <BetterI18nProvider
      messages={messages}
      locale={locale}
      project="your-org/your-project"
    >
      <Outlet />
    </BetterI18nProvider>
  );
}

Use in routes

在任意路由组件中调用 useTranslations()。同一个 hook 在客户端组件和服务端组件中都可用。

app/routes/about.tsx
// app/routes/about.tsx
import { useTranslations } from '@better-i18n/use-intl';

export default function AboutPage() {
  const t = useTranslations('pages');
  return (
    <main>
      <h1>{t('about.title')}</h1>
      <p>{t('about.description')}</p>
    </main>
  );
}
Capabilities

为什么在 TanStack Start 中使用 Better I18N?

SSR 水合 — 服务端加载的文案直接水合客户端,无需重新请求
没有内容闪烁 — 首次渲染即为翻译后的内容
动态语言 — 语言列表来自 CDN manifest,无需写死在代码中
基于路径的路由 — /tr/about、/de/about 这样的 URL 结构
全栈类型安全 — loader 与组件共用同一套类型系统
Cookie 与请求头检测 — URL → cookie → Accept-Language 回退链

Other frameworks

Get started

构建多语言的 TanStack Start 应用

在一个控制台中管理全部翻译,配合 AI 建议、上下文感知翻译和 CDN 分发。