Alpha
Lingo.dev Compiler 目前处于 Alpha 阶段。它还不稳定，不建议用于生产环境，且 API 可能会在不同版本之间发生变化。
自定义 locale 解析器可让你改写 Lingo.dev Compiler 检测和持久化用户 locale 的方式。默认情况下，Compiler 会使用通过 localePersistence 选项配置的 cookie 持久化方案。若你需要更细粒度的控制——例如基于 URL 的路由、请求头检测、localStorage，或任意自定义逻辑——可以在 .lingo/ 目录下创建解析器文件。
解析器文件#
Compiler 会查找以下两个可选文件：
| 文件 | 运行环境 | 导出项 |
|---|---|---|
.lingo/locale-resolver.server.ts | 服务端（SSR、RSC） | resolveLocale(request: Request): string |
.lingo/locale-resolver.client.ts | 客户端（浏览器） | resolveLocale(): string and persistLocale(locale: string): void |
如果存在解析器文件，Compiler 就会优先使用它，而不是默认的 cookie 方案。如果只存在其中一个文件，另一个环境则会回退到默认行为。
服务端解析器#
服务端解析器会接收传入的 Request 对象，并返回一个 locale 代码字符串：
ts
// .lingo/locale-resolver.server.ts
export function resolveLocale(request: Request): string {
const url = new URL(request.url);
// Check URL path prefix: /es/about -> "es"
const pathLocale = url.pathname.split("/")[1];
const supportedLocales = ["en", "es", "de", "fr", "ja"];
if (supportedLocales.includes(pathLocale)) {
return pathLocale;
}
// Fall back to Accept-Language header
const acceptLanguage = request.headers.get("Accept-Language");
if (acceptLanguage) {
const preferred = acceptLanguage.split(",")[0].split("-")[0];
if (supportedLocales.includes(preferred)) {
return preferred;
}
}
return "en";
}客户端解析器#
客户端解析器包含两个函数：一个用于读取当前 locale，另一个用于持久化 locale 变更：
ts
// .lingo/locale-resolver.client.ts
export function resolveLocale(): string {
// Check URL path prefix
const pathLocale = window.location.pathname.split("/")[1];
const supportedLocales = ["en", "es", "de", "fr", "ja"];
if (supportedLocales.includes(pathLocale)) {
return pathLocale;
}
// Fall back to localStorage
const stored = localStorage.getItem("locale");
if (stored && supportedLocales.includes(stored)) {
return stored;
}
return "en";
}
export function persistLocale(locale: string): void {
localStorage.setItem("locale", locale);
// Navigate to the locale-prefixed URL
const path = window.location.pathname.replace(/^\/[a-z]{2}/, "");
window.location.href = `/${locale}${path}`;
}常见解析器模式#
按 URL 路径前缀路由（/es/about、/de/pricing）：
ts
// .lingo/locale-resolver.server.ts
export function resolveLocale(request: Request): string {
const url = new URL(request.url);
const locale = url.pathname.split("/")[1];
const supported = ["en", "es", "de", "fr"];
return supported.includes(locale) ? locale : "en";
}ts
// .lingo/locale-resolver.client.ts
export function resolveLocale(): string {
const locale = window.location.pathname.split("/")[1];
const supported = ["en", "es", "de", "fr"];
return supported.includes(locale) ? locale : "en";
}
export function persistLocale(locale: string): void {
const path = window.location.pathname.replace(/^\/[a-z]{2}/, "");
window.location.href = `/${locale}${path}`;
}resolveLocale 函数必须返回一个 locale 代码，并且该代码必须与你配置的 targetLocales 或 sourceLocale 之一匹配。若返回了不受支持的 locale 代码，Compiler 会回退到 source locale。
