アルファ
Lingo.dev Compiler はアルファ版です。動作は不安定で、本番環境での利用は推奨されません。また、API はリリース間で変更される可能性があります。
カスタムロケールリゾルバーを使うと、Lingo.dev Compiler によるユーザーのロケール検出と永続化の仕組みを上書きできます。デフォルトでは、Compiler は localePersistence オプションで設定された cookie ベースの永続化を使用します。URLベースのルーティング、ヘッダー検出、localStorage、あるいは独自のロジックなど、より柔軟に制御したい場合は、.lingo/ ディレクトリにリゾルバーファイルを作成してください。
リゾルバーファイル#
Compiler は、次の2つのオプションファイルを探します。
| ファイル | 環境 | エクスポート |
|---|---|---|
.lingo/locale-resolver.server.ts | サーバー側（SSR、RSC） | resolveLocale(request: Request): string |
.lingo/locale-resolver.client.ts | クライアント側（ブラウザ） | resolveLocale(): string と persistLocale(locale: string): void |
リゾルバーファイルが存在する場合、Compiler はデフォルトの cookie ベースの動作の代わりにそのファイルを使用します。どちらか一方のファイルしか存在しない場合、もう一方の環境ではデフォルトの動作にフォールバックします。
サーバー側リゾルバー#
サーバー側リゾルバーは、受信した Request オブジェクトを受け取り、ロケールコードの文字列を返します。
// .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";
}クライアント側リゾルバー#
クライアント側リゾルバーには2つの関数があります。1つは現在のロケールを読み取り、もう1つはロケールの変更を永続化します。
// .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）：
// .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";
}// .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 関数は、設定済みの targetLocales または sourceLocale のいずれかに一致するロケールコードを返す必要があります。サポートされていないロケールコードを返した場合、Compiler はソースロケールにフォールバックします。
