Lingo.dev - Automated AI localization for web & mobile apps

はじめに

Lingo.dev Compilerは、既存のコンポーネントに変更を加えることなくReactベースのアプリをローカライズできるAI駆動ツールです。いくつかの設定を行い、アプリをコンテキストプロバイダーでラップするだけで、アプリのローカライズが完了します。

このガイドでは、Kent C. Doddsが開発したRemix上に構築されたフルスタックWebアプリフレームワークThe Epic StackでLingo.dev Compilerをセットアップする方法を説明します。

学習内容

The Epic StackでLingo.dev Compilerを初期化する方法
The Epic Stackとの互換性のためにコンパイラーを設定する方法
ロケールを切り替えるためのロケールスイッチャーをセットアップする方法

ステップ1. APIキーの設定

Lingo.dev Compilerは大規模言語モデル（LLM）を使用してAIでアプリをローカライズします。これらのモデルを使用するには、サポートされているプロバイダーからAPIキーが必要です。

可能な限り早く始めるために、毎月10,000トークンの無料使用量を提供する当社独自のホスト型プラットフォームLingo.dev Engineの使用をお勧めします。

APIキーを設定するには：

Lingo.dev Engineにログインします。
Projectsページに移動します。
API key > Copyをクリックします。
APIキーを環境変数に保存します：
```
export LINGODOTDEV_API_KEY="<your_api_key>"
```

代替手段：カスタムLLMプロバイダー

Lingo.dev Engineを使用する必要はありません。コンパイラーを設定して、以下を含む多数のカスタムLLMプロバイダーと統合することができます：

Groq
Google
Mistral
Ollama
OpenRouter

ステップ2. パッケージのインストール

Lingo.dev Compilerはlingo.dev npmパッケージの一部として配布されています。インストールするには、お好みのパッケージマネージャーを使用してください：

npm install lingo.dev

ステップ 3. コンパイラの初期化

Lingo.dev コンパイラはViteと統合され、ビルド時に実行されます。Viteのビルドプロセスに連携するために、vite.config.tsファイルに以下の変更を加えてください：

コンパイラをインポートします：

import lingoCompiler from "lingo.dev/compiler";

viteメソッドでコンパイラを初期化します：
```
const withLingo = lingoCompiler.vite({
  sourceRoot: "app",
  lingoDir: "lingo",
  sourceLocale: "en",
  targetLocales: ["es"],
  rsc: false,
  useDirective: false,
  debug: false,
  models: "lingo.dev",
});
```
Epic Stackとの互換性を確保するために、以下を確認してください：
- sourceRootが"app"に設定されていること
- rscがfalseに設定されていること
利用可能なオプションについて詳しく知るには、コンパイラオプションをご覧ください。

コンパイラの設定を既存の設定とマージして、エクスポートします：

export default defineConfig((config) => {
  const configWithSentry = {
    ...viteConfig,
    plugins: [
      ...viteConfig.plugins!.filter(Boolean),
      MODE === "production" && process.env.SENTRY_AUTH_TOKEN
        ? sentryReactRouter(sentryConfig, config)
        : null,
    ].filter(Boolean),
  };

  return withLingo(configWithSentry);
});

この設定を行うことで、Lingo.dev コンパイラは以下を実行します：

コードベースの抽象構文木（AST）を走査する
ローカライズ可能なコンテンツ（JSX要素内のテキストや特定の属性値など）を検出する
設定されたAIモデルを使用して翻訳を生成する
元のコンテンツと翻訳されたコンテンツをdictionary.jsファイルに保存する
ローカライズされたコンテンツをプレースホルダに置き換える

ステップ 4. ローカライズされたコンテンツの読み込み

コンパイラがアプリを処理して翻訳を生成した後、このローカライズされたコンテンツをユーザーに提供するために読み込む必要があります。これには以下が含まれます：

ユーザーのロケール設定に基づいて適切な辞書を読み込む
読み込まれた翻訳をコンテキストプロバイダーを通じてアプリに提供する

辞書の読み込み

「app/root.tsx」ファイルで：

lingo.dev/react/react-routerからloadDictionary関数をインポートします：
```
import { loadDictionary } from "lingo.dev/react/react-router";
```
この関数は以下を行います：
- lingo-localeクッキーから現在のロケールを取得します
- ロケールが定義されていない場合は"en"にフォールバックします
- dictionary.jsファイルからローカライズされたコンテンツを読み込みます
loader関数からloadDictionary関数を呼び出します：
```
const lingoDictionary = await loadDictionary(request);
```

ローダーデータの一部として辞書を返します：

return data(
  {
    user,
    requestInfo: {
      hints: getHints(request),
      origin: getDomainUrl(request),
      path: new URL(request.url).pathname,
      userPrefs: {
        theme: getTheme(request),
      },
    },
    ENV: getEnv(),
    toast,
    honeyProps,
    lingoDictionary,
  },
  {
    headers: combineHeaders(
      { "Server-Timing": timings.toString() },
      toastHeaders,
    ),
  },
);

翻訳の提供

「app/root.tsx」ファイルで：

lingo.dev/react/clientからLingoProviderコンポーネントをインポートします：
```
import { LingoProvider } from "lingo.dev/react/client";
```
このコンポーネントはReactコンテキストプロバイダーで、コンパイラーによって作成されたプレースホルダーをローカライズされたコンテンツに置き換えます。
Layoutコンポーネントで、データローダーからデータを取得します：
```
const data = useLoaderData<typeof loader | null>();
```
アプリをLingoProviderコンポーネントでラップします：
```
<LingoProvider>{/* 既存のアプリコード */}</LingoProvider>
```

読み込まれた辞書をコンポーネントに渡します：

<LingoProvider dictionary={data?.lingoDictionary}>
  {/* 既存のアプリコード */}
</LingoProvider>

ステップ5. ロケールスイッチャーの設定

ユーザーがロケールを切り替えられるようにするには、lingo.devパッケージからLocaleSwitcherをインポートします。これはスタイルが適用されていないコンポーネントで、以下の機能を提供します：

利用可能なロケールのドロップダウンをレンダリングします
ユーザーがロケールを選択できるようにします
選択されたロケールを再訪問時のために記憶します

このコンポーネントを使用するには、アプリのどこにでも埋め込み、localesプロパティに設定されたソースロケールとターゲットロケールを含む配列を設定します：

import { LocaleSwitcher } from "lingo.dev/react/client";

<LocaleSwitcher locales={["en", "es"]} />;

代替手段：カスタムロケールスイッチャー

必ずしもLocaleSwitcherコンポーネントを使用する必要はありません。カスタムのロケール切り替えロジックとUIを実装することも可能です。唯一の要件は、アクティブなロケールをlingo-localeクッキーから読み取り、書き込むことです。

ステップ6. アプリを実行する

Lingo.dev Compilerが正しく設定されていることを確認するには：

開発サーバーを起動します：
```
npm run dev
```
localhost:3000にアクセスします。
LocaleSwitcherコンポーネントを使用してロケールを切り替えます。

ページが再読み込みされ、ローカライズされたコンテンツが表示されるはずです。

代替手段：手動でクッキーを設定する

もしLocaleSwitcherコンポーネントを使用していない場合、ローカライゼーションが機能していることを確認する別の方法として、手動でlingo-localeクッキーを設定することができます。

Google Chromeを使用している場合は、以下の手順に従ってください：

表示 > 開発者 > デベロッパーツールに移動します。
アプリケーションタブに移動します。
左側のサイドバーのストレージの下にあるクッキーを展開し、サイトのURLを選択します。
クッキーテーブル内で右クリックし、追加を選択します。
名前列にlingo-localeと入力します。
値列に希望するロケール（例：es）を入力します。
Enterキーを押してクッキーを保存します。
ページを更新してクッキーを適用します。

参考資料

コンパイラーの仕組みを理解するには、仕組みをご覧ください。
コンパイラーの設定方法については、コンパイラーオプションをご覧ください。

The Epic Stackのクイックスタート