create-t3-app 的快速入门
如何使用 create-t3-app 设置 Lingo.dev 编译器
简介
Lingo.dev Compiler 是一款由 AI 驱动的工具，可以在不更改现有组件的情况下实现基于 React 的应用程序的本地化。您只需配置一些内容，将您的应用程序包裹在一个上下文提供器中，就完成了——您的应用程序已实现本地化。
本指南将解释如何使用 create-t3-app 设置 Lingo.dev Compiler。create-t3-app 是一个全栈 Web 应用框架，结合了 Next.js、TypeScript、Tailwind CSS 和 tRPC。
您将学习到的内容
- 如何在 create-t3-app 项目中初始化 Lingo.dev Compiler
- 如何配置编译器以兼容 create-t3-app
- 如何设置语言切换器以在不同语言环境之间切换
第 1 步：设置 API 密钥
Lingo.dev Compiler 使用大型语言模型（LLMs）通过 AI 实现应用程序的本地化。要使用这些模型之一，您需要从支持的提供商处获取 API 密钥。
为了尽快开始使用，我们推荐使用 Lingo.dev Engine——我们自己的托管平台，每月提供 10,000 个免费使用的令牌。
设置 API 密钥的步骤：
-
导航到 Projects 页面。
-
点击 API key > Copy。
-
将 API 密钥存储在环境变量中：
export LINGODOTDEV_API_KEY="<your_api_key>"
替代方案：自定义 LLM 提供商
您不必使用 Lingo.dev Engine。您可以配置编译器与多个自定义 LLM 提供商集成，包括：
- Groq
- Mistral
- Ollama
- OpenRouter
第 2 步：安装软件包
Lingo.dev Compiler 作为 lingo.dev npm 软件包的一部分分发。要安装它，请使用您喜欢的包管理器：
npm install lingo.dev第 3 步：禁用 Turbopack
在使用 create-t3-app 时，Lingo.dev 编译器与 Turbopack 不兼容。如果启用了 Turbopack，编译过程将会失败。
要禁用 Turbopack，请从 dev 脚本中移除 --turbopack 标志：
{
"scripts": {
"dev": "next dev"
}
}第 4 步：初始化编译器
Lingo.dev 编译器与 Next.js 集成，并在构建时运行。要将其挂接到构建过程中，请对 next.config.ts 文件进行以下更改：
-
导入编译器：
import lingoCompiler from "lingo.dev/compiler"; -
使用
next方法初始化编译器：const withLingo = lingoCompiler.next({ sourceRoot: "src", lingoDir: "lingo", sourceLocale: "en", targetLocales: ["es"], rsc: true, useDirective: false, debug: false, models: "lingo.dev", });为了与 create-t3-app 兼容，请确保：
sourceRoot设置为"src"rsc设置为true
要了解更多可用选项，请参阅 编译器选项。
-
将编译器配置与现有配置合并并导出：
export default withLingo(config);
完成此配置后，Lingo.dev 编译器将会：
- 遍历代码库的抽象语法树 (AST)
- 查找可本地化的内容（例如 JSX 元素中的文本和某些属性值）
- 使用配置的 AI 模型生成翻译
- 将原始内容和翻译内容存储在
dictionary.js文件中 - 用占位符替换本地化内容
第 5 步：加载本地化内容
在编译器处理您的应用并生成翻译后，您需要加载这些本地化内容并将其提供给用户。这包括：
- 根据用户的语言偏好加载相应的字典
- 通过上下文提供器将加载的翻译提供给您的应用
在 src/app/layout.tsx 文件中，将应用包裹在 LingoProvider 组件中，并传递 loadDictionary 函数：
import { LingoProvider, loadDictionary } from "lingo.dev/react/rsc";
export default function RootLayout({
children,
}: Readonly<{ children: React.ReactNode }>) {
return (
<LingoProvider loadDictionary={(locale) => loadDictionary(locale)}>
<html lang="en" className={`${geist.variable}`}>
<body>
<TRPCReactProvider>{children}</TRPCReactProvider>
</body>
</html>
</LingoProvider>
);
}loadDictionary 函数：
- 从
lingo-localecookie 中检索当前语言（默认为"en"） - 从
dictionary.js文件中加载本地化内容
LingoProvider 组件是一个 React 上下文提供器，用于将编译器创建的占位符替换为本地化内容。
第 6 步：设置语言切换器
为了让用户能够在不同语言环境之间切换，从 lingo.dev 包中导入 LocaleSwitcher。这是一个未添加样式的组件，其功能包括：
- 渲染一个可用语言环境的下拉菜单
- 允许用户选择语言环境
- 记住用户选择的语言环境以便下次访问
要使用该组件，只需将其嵌入到应用程序中的任意位置，并将 locales 属性设置为包含已配置的源语言和目标语言的数组：
import { LocaleSwitcher } from "lingo.dev/react/client";
<LocaleSwitcher locales={["en", "es"]} />;替代方案：自定义语言切换器
您不必使用 LocaleSwitcher 组件。您可以实现自定义的语言切换逻辑和用户界面。唯一的要求是将当前语言环境读写到 lingo-locale cookie 中。
第 7 步：运行应用程序
要验证 Lingo.dev Compiler 是否已正确设置：
-
启动开发服务器：
npm run dev -
访问 localhost:3000。
-
使用
LocaleSwitcher组件在不同语言环境之间切换。
页面应重新加载并显示本地化内容。
替代方案：手动设置 Cookie
如果您未使用 LocaleSwitcher 组件，另一种验证本地化是否正常工作的方式是手动设置 lingo-locale cookie。
如果您使用的是 Google Chrome，请按照以下步骤操作：
- 导航到 查看 > 开发者 > 开发者工具。
- 转到 应用程序 选项卡。
- 在左侧边栏的 存储 下，展开 Cookie 并选择站点的 URL。
- 在 Cookie 表格中，右键单击任意位置并选择 添加。
- 在 名称 列中，输入
lingo-locale。 - 在 值 列中，输入所需的语言环境（例如，
es）。 - 按 Enter 保存 Cookie。
- 刷新页面以应用 Cookie。