AdonisJSクイックスタート

Lingo.devコンパイラをAdonisJSで設定する方法

はじめに

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

このガイドでは、サーバーサイドアプリケーションを構築するための機能豊富なNode.jsウェブフレームワークであるAdonisJSでLingo.dev Compilerをセットアップする方法を説明します。

前提条件

  • AdonisJSプロジェクトがInertia.jsを使用していること。

学習内容

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

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

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

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

APIキーを設定するには：

  1. Lingo.dev Engineにログインします。

  2. Projectsページに移動します。

  3. API key > Copyをクリックします。

  4. 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ファイルに以下の変更を加えてください：

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

    import lingoCompiler from "lingo.dev/compiler";

  2. viteメソッドでコンパイラを初期化します：

    const withLingo = lingoCompiler.vite({
  sourceRoot: "inertia",
  lingoDir: "lingo",
  sourceLocale: "en",
  targetLocales: ["es"],
  rsc: false,
  useDirective: false,
  debug: false,
  models: "lingo.dev",
});

    AdonisJSとの互換性を確保するために、以下を確認してください：

    • sourceRootが"inertia"に設定されていること
    • rscがfalseに設定されていること

    利用可能なオプションについて詳しくは、コンパイラオプションをご覧ください。

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

    export default withLingo(viteConfig);

この設定により、Lingo.dev コンパイラは以下を実行します：

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

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

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

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

クライアントサイド

inertia/app/app.tsxファイルで：

  1. lingo.dev/react/clientからLingoProviderWrapperコンポーネントとloadDictionary関数をインポートします：

    import {
  LingoProviderWrapper,
  loadDictionary,
} from "lingo.dev/react/client";

    LingoProviderWrapperコンポーネントは、コンパイラが作成したプレースホルダーをローカライズされたコンテンツに置き換えるコンテキストプロバイダーです。

    loadDictionary関数は：

    • lingo-localeクッキーから現在のロケールを取得します
    • ロケールが定義されていない場合は"en"にフォールバックします
    • dictionary.jsファイルからローカライズされたコンテンツを読み込みます

  2. AppコンポーネントをLingoProviderWrapperコンポーネントでラップし、loadDictionary関数を渡します：

    <LingoProviderWrapper loadDictionary={(locale) => loadDictionary(locale)}>
  <App {...props} />
</LingoProviderWrapper>

サーバーサイド

inertia/app/ssr.tsxファイルで、ハイドレーションの不一致を避けるために同じ手順を繰り返します：

import { LingoProviderWrapper, loadDictionary } from "lingo.dev/react/client";

<LingoProviderWrapper loadDictionary={(locale) => loadDictionary(locale)}>
  <App {...props} />
</LingoProviderWrapper>;

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

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

  • 利用可能なロケールのドロップダウンを表示する
  • ユーザーが希望するロケールを選択できるようにする
  • ユーザーのロケール設定を再訪問時のために記憶する

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

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

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

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

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

ステップ6. アプリの実行

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

  1. 開発サーバーを起動します：

    npm run dev

  2. localhost:3333にアクセスします。

  3. LocaleSwitcherコンポーネントを使用してロケールを切り替えます。

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

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

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

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

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

参考資料