返回

gt-tanstack-start@0.1.0

Ernest McCarter avatarErnest McCarter
gt-tanstack-startv0.1.0tanstack-starttanstacki18ntranslationvite

概览

gt-tanstack-start 是为 TanStack Start 提供专门 i18n 支持的初次尝试。

这个库目前是实验性的。 它仍处于起步阶段，我们非常欢迎反馈。如果你在基于 TanStack 的生产环境中需要 i18n 支持，目前推荐先使用 gt-react。

包含内容

  • initializeGT() — 为 TanStack Start 配置 i18n 管理器。在根路由文件顶部调用一次即可。
  • GTProvider — 使用翻译上下文包裹你的应用，内置 SSR 检测和针对 TanStack Start 定制的 locale 解析。
  • getTranslations() — 一个异步函数，供在根级 loader 中调用，将翻译数据传入 Provider。
  • getLocale() — 返回当前请求解析得到的语言环境（locale）。
  • <T>, <Var>, <LocaleSelector> — 从 gt-react 重新导出，便于你从单个包中导入所有内容。

快速上手

安装

npm install gt-tanstack-start

配置 gt.config.json 文件

{
  "defaultLocale": "en",
  "locales": ["fr", "zh"],
  "files": {
    "gt": {
      "output": "src/_gt/[locale].json"
    }
  }
}

设置环境变量

VITE_GT_PROJECT_ID=your-project-id
VITE_GT_DEV_API_KEY=your-dev-api-key

创建翻译加载器

// loadTranslations.ts
export async function loadTranslations(locale: string) {
  const translations = await import(`./src/_gt/${locale}.json`);
  return translations.default;
}

配置根路由

// __root.tsx
import { HeadContent, Scripts, createRootRoute } from '@tanstack/react-router';
import {
  initializeGT,
  GTProvider,
  getTranslations,
  getLocale,
} from 'gt-tanstack-start';
import gtConfig from '../../gt.config.json';
import { loadTranslations } from '../../loadTranslations';

initializeGT({
  ...gtConfig,
  projectId: import.meta.env.VITE_GT_PROJECT_ID,
  devApiKey: import.meta.env.VITE_GT_DEV_API_KEY,
  loadTranslations,
});

export const Route = createRootRoute({
  loader: async () => ({
    translations: await getTranslations(),
    locale: getLocale(),
  }),
  shellComponent: RootDocument,
});

function RootDocument({ children }: { children: React.ReactNode }) {
  const { translations, locale } = Route.useLoaderData();
  return (
    <html lang={locale}>
      <head>
        <HeadContent />
      </head>
      <body>
        <GTProvider translations={translations}>
          {children}
        </GTProvider>
        <Scripts />
      </body>
    </html>
  );
}

内容翻译

import { T } from 'gt-tanstack-start';

export default function Page() {
  return (
    <T>
      <p>这会自动翻译。</p>
    </T>
  );
}

展望未来

当前版本为 v0.1.0 —— 基础能力已经具备，但还有很多功能有待完善和扩展。 SSG 和 locale 路由是我们计划在后续版本中加入的一些下一步特性。

如果你有兴趣尝试使用，我们非常欢迎你的反馈。 欢迎加入我们的 Discord 或在 GitHub 上提交 issue。