Bolt
Bolt 是由 StackBlitz 提供的基于浏览器的 AI 驱动开发平台。本指南解释了如何在 Bolt 中使用 Lingo.dev Compiler 本地化基于 React 的应用程序。
已知限制
Bolt 使用 web containers 在浏览器中运行 Web 应用程序。这是一项强大的技术，但与 Lingo.dev 存在一些兼容性问题：
- 您只能使用 API 密钥来通过 Lingo.dev Engine 进行身份验证，而不能使用 CLI 的
login命令。 - 在 Bolt 中，Lingo.dev Compiler 仅与基于 Vite 的应用程序兼容。您无法使用 Next.js。
<LocaleSwitcher />组件无法在 Bolt 的嵌入式 预览 窗口中工作。- Bolt 不支持 Ollama，因为 Ollama 需要在本地运行。
第 1 步：获取 API 密钥
Lingo.dev Compiler 使用大型语言模型（LLM）通过 AI 本地化应用程序。要使用这些模型之一，您需要从支持的提供商处获取 API 密钥。您可以使用 Lingo.dev Engine 或自定义 LLM 提供商。
Lingo.dev Engine
Lingo.dev Engine 是我们自己的托管平台，提供动态模型选择、自动路由、翻译记忆和术语表支持。注册是免费的，所有用户每月可获得 10,000 个免费使用的令牌。
获取 API 密钥的步骤：
- 登录 Lingo.dev Engine。
- 导航到 Projects 页面。
- 点击 API key > Copy。
自定义 LLM 提供商
Lingo.dev 编译器还支持与多种第三方提供商集成，包括：
- Google AI
- GROQ
- Mistral
- Ollama（不支持 Bolt）
- OpenRouter
设置 API 密钥的具体说明取决于提供商。
注意： 在编译器中使用之前，请确保已激活您的 LLM 提供商账户并接受其服务条款。
第 2 步. 安装 lingo.dev
lingo.dev 包包含编译器。
要安装该包：
-
创建或打开一个 Bolt 项目。
-
切换到 Code 标签。
-
点击 Terminal。
-
运行以下命令：
npm install lingo.dev
第 3 步. 配置 Vite
在使用 Vite 时，必须在项目的配置文件中初始化 Lingo.dev Compiler：
- 如果您使用的是 TypeScript，配置文件是
vite.config.ts。 - 如果您使用的是 JavaScript，配置文件是
vite.config.js。
您可以在初始化时配置编译器的行为。此配置决定了要翻译的语言环境以及用于本地化的模型。
有关可用选项的完整列表，请参阅 Compiler Options。
Lingo.dev Engine
如果您使用的是 Lingo.dev Engine，请将 models 设置为 "lingo.dev"：
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import lingoCompiler from "lingo.dev/compiler";
const viteConfig = {
plugins: [react()],
};
export default defineConfig(() =>
lingoCompiler.vite({
sourceRoot: "src",
lingoDir: "lingo",
sourceLocale: "en",
targetLocales: ["es"],
rsc: false,
useDirective: false,
debug: false,
models: "lingo.dev",
})(viteConfig),
);
自定义 LLM 提供商
如果您使用的是自定义 LLM 提供商，请将 models 设置为一个对象，该对象将源语言环境和目标语言环境映射到应本地化它们的模型。例如，此配置使用 "groq:qwen/qwen3-32b" 本地化所有字符串：
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import lingoCompiler from "lingo.dev/compiler";
const viteConfig = {
plugins: [react()],
};
export default defineConfig(() =>
lingoCompiler.vite({
sourceRoot: "src",
lingoDir: "lingo",
sourceLocale: "en",
targetLocales: ["es"],
rsc: false,
useDirective: false,
debug: false,
models: {
"*:*": "groq:qwen/qwen3-32b",
},
})(viteConfig),
);
步骤 4. 设置环境变量
为了确保 Lingo.dev 编译器 能够访问已配置模型的 API 密钥，这些 API 密钥需要作为环境变量提供。
在 Bolt 中设置环境变量的步骤如下：
-
创建一个
.env文件。- 右键单击文件窗格。
- 选择 New file（新建文件）。
- 输入
.env。
-
将相关的环境变量添加到文件中：
# Lingo.dev 引擎 LINGODOTDEV_API_KEY="YOUR_API_KEY_GOES_HERE" # Google AI GOOGLE_API_KEY="YOUR_API_KEY_GOES_HERE" # GROQ GROQ_API_KEY="YOUR_API_KEY_GOES_HERE" # Mistral MISTRAL_API_KEY="YOUR_API_KEY_GOES_HERE" # OpenRouter OPENROUTER_API_KEY="YOUR_API_KEY_GOES_HERE"
注意： Bolt 会自动加密环境变量。要了解更多信息，请参阅 环境变量 (developer.stackblitz.com)。
步骤 4. 添加提供者
lingo.dev 包导出了一个 <LingoProviderWrapper /> 组件。此组件负责加载翻译并使其在整个应用中可用。
要使用该组件，请将其导入到 src/main.tsx 文件中，并将其包裹在 <App /> 组件周围：
import React from "react";
import ReactDOM from "react-dom/client";
import App from "./App.tsx";
import { LingoProviderWrapper, loadDictionary } from "lingo.dev/react/client";
ReactDOM.createRoot(document.getElementById("root")!).render(
<React.StrictMode>
<LingoProviderWrapper loadDictionary={(locale) => loadDictionary(locale)}>
<App />
</LingoProviderWrapper>
</React.StrictMode>,
);
（可选）步骤 5. 添加语言切换器
lingo.dev 包导出了一个未添加样式的 <LocaleSwitcher /> 组件。此组件会渲染一个下拉菜单，允许用户设置其首选语言，并在返回时记住该选择。
要使用该组件，请将其作为 <LingoProviderWrapper /> 组件的子组件，并将 locales 属性设置为包含源语言和目标语言的数组：
import { LocaleSwitcher } from "lingo.dev/react/client";
function App() {
return (
<div className="App">
<header>
<LocaleSwitcher locales={["en", "es"]} />
</header>
<main>
<h1>欢迎使用您的应用</h1>
<p>此内容是自动翻译的</p>
</main>
</div>
);
}
export default App;
警告： <LocaleSwitcher /> 组件无法在 Bolt 的嵌入式 预览 窗口中工作。要查看该组件的实际效果，请点击 在单独的标签页中打开预览 图标。
第 6 步. 构建和测试
如果开发服务器尚未运行，请使用以下命令启动它：
npm run dev
编译器将自动完成以下操作：
- 扫描您的 React 组件以查找可翻译内容
- 提取翻译键
- 生成 AI 驱动的翻译
- 在
lingo/目录中创建优化的翻译文件