クイックスタート

Lingo.dev CLIの主な強みは、単一のCLIコマンドを使用してアプリケーションやマークダウンコンテンツを対象言語に効率的にローカライズすることです。

このクイックスタートガイドは、あなたがアプリを多言語対応にしようとしているか、すでに2つ以上の言語を処理するように構成している場合を想定しています。そのため、このガイドは10分以内に完了できるほど短くなっていますが、内部の仕組みを理解するのに十分な詳細さを備えています。

このガイドを完了すると、以下のことができるようになります：

  1. AI翻訳エンジンを使用してアプリコンテンツをスペイン語と日本語にローカライズする；
  2. ソースファイル、ターゲットファイル、および設定がどのように連携するかを理解する；
  3. アプリケーションとマークダウンコンテンツを数十の言語と数万の単語にスケールできるローカライゼーションワークフローを設定する。

さあ、始めましょう！

前提条件

マークダウン

マークダウンファイルは構造化されたドキュメントであるため、事前のセットアップは必要ありません。Lingo.dev CLIは.mdファイルを直接処理し、コンテンツをローカライズしながらフォーマットを維持するので、ステップ1に進むことができます。

アプリケーション

アプリを多言語対応にするには、最新のWebおよびモバイルアプリケーションでは、開発者がまず国際化（i18n）設定を行う必要があります。

このクイックスタートでは、Lingo.dev CLIがアプリケーションコンテンツをどのようにローカライズするかを示すために、スタンドアロンのJSONファイルを作成します。

実際のアプリケーションと統合する場合は、推奨するフレームワークガイドに従ってください：

Windows のみ: npx による実行

初めてnpxを実行する場合、BashまたはBashと互換性のあるシェルが必要です。Windowsでは、Git for Windowsをインストールできます。

インストール後、初めてnpxを実行する前に、ターミナルで以下のコマンドのいずれかを実行してnpxのシェルを設定してください（Git Bashのインストール場所によって異なります）：

npm config set script-shell "C:\\Program Files\\git\\bin\\bash.exe"

または

npm config set script-shell "C:\\Program Files (x86)\\git\\bin\\bash.exe"

これはWindowsでlingo.devパッケージを正しく実行するために必要です。

ステップ 1. プロジェクトの初期化

Lingo.dev CLI は、ローカリゼーション設定を宣言するために標準の i18n.json 設定ファイルを使用します。対話形式で作成するには、次のコマンドを実行します：

npx lingo.dev@latest init

プロジェクトに関する質問が表示され、プロジェクトのルートに i18n.json ファイルが作成されます。

ファイルは次のようになります：

{
  "locale": {
    "source": "en",
    "targets": ["es", "ja"]
  },
  "buckets": {
    "json": {
      "include": ["locales/[locale].json"]
    }
  }
}

各設定要素を詳しく見てみましょう：

  • locale.source — チームが記述する言語。この設定は、信頼できるコンテンツを含むファイルを識別します。すべてのローカリゼーションはソースからターゲットへと流れます。

  • locale.targets — ターゲット市場を表す ISO 639-1 言語コードの配列。各コードは個別のファイル（またはフォーマットによってはファイル内のセクション）に対応します。1つか2つの言語から始めて、拡張するにつれて追加できます。

  • buckets.json.include — CLI にロケールファイルの検索と作成場所を指示する glob 風のパターン。特殊な [locale] トークンは各言語コードに展開されます。パターン locales/[locale].json では、CLI はソースとして locales/en.json を探し、ターゲットとして locales/es.json と locales/ja.json を生成します。複数のパターンを指定したり、単一の設定内で異なるフォーマットを混在させたりすることもできます。

プロジェクトの成長に伴って発見する高度な機能：

  • アプリの異なるファイルタイプやセクション用の複数のバケット
  • 特定のファイルをスキップするための exclude パターン
  • 特定の値を翻訳から保護するための lockedKeys

英語のソースファイルを作成する

このクイックスタートでは、ロケールファイルを作成します：

mkdir -p locales
echo '{"greeting":"Hello, world!","button.submit":"Submit"}' > locales/en.json

これにより、localesディレクトリと2つの翻訳キーを持つ英語のソースファイルが作成されます。greetingのようなキーはフラット構造に適しており、button.submitのような名前空間付きキーは大規模なアプリケーションの整理に役立ちます。

ネストされたオブジェクトもサポートされています。さまざまなファイル形式の詳細はドキュメントの残りの部分で確認できます。

ステップ2. 認証

Lingo.dev CLIはコンテンツをAI翻訳エンジンにローカライゼーションのために送信するため、最初に認証が必要です。

オプション1. 生のLLM APIアクセス

Lingo.dev CLIはOpenAIやAnthropicなどのLLMモデルをローカライゼーションと翻訳に使用するのに役立ちます。

これは、処理されたトークンごとに課金され、モデル選択、システムプロンプト、およびすべてのモデルパラメータを制御できることを意味します。

認証するには、プロジェクトのルートに.envファイルを作成し、APIキーを追加します：


# OpenAIを使用する場合

OPENAI_API_KEY=sk-...

# Anthropicを使用する場合

ANTHROPIC_API_KEY=sk-...

代わりに、.envを使用せずに、現在のシェルセッションで変数をエクスポートすることもできます：

export ANTHROPIC_API_KEY=sk-ant-...

別のプロバイダーのサポートを追加したいですか？Lingo.dev CLIはオープンソースであり、貢献を歓迎します！リポジトリをフォークしてプルリクエストを送信してください：github.com/lingodotdev/lingo.dev。

オプション2. Lingo.devエンジン

または、無料のLingo.devエンジンアカウントを作成し、AIの翻訳エンジンとして使用することもできます。

これは、動的なモデル選択、各言語ペアに対する異なるモデルへの自動ルーティング、自動モデルフォールバック、過去の翻訳を考慮する翻訳メモリ、およびプロジェクトのドメイン固有の用語集のサポートを提供します。無料と有料のオプションがあり、無料のHobbyティアはこのチュートリアルに十分です。

認証するには、次を実行します：

npx lingo.dev@latest login

重要な詳細。 Braveブラウザを使用している場合、またはブラウザの拡張機能が認証フローをブロックしている場合は、.envファイルにLINGODOTDEV_API_KEY環境変数を追加して手動で認証できます：

LINGODOTDEV_API_KEY=...

トークンはLingo.devエンジンのプロジェクト設定で見つけることができます。

ステップ3. AI翻訳エンジンの設定

認証が完了したら、使用するAI翻訳エンジンを設定する必要があります。

オプション1. 直接LLM APIアクセス

OpenAIを使用するには、i18n.json設定を更新してopenaiプロバイダーを使用します：

{
  "locale": {
    "source": "en",
    "targets": ["es", "ja"]
  },
  "buckets": {
    "json": {
      "include": ["locales/[locale].json"]
    }
  },
  "provider": {
    "id": "openai",
    "model": "gpt-4o-mini",
    "prompt": "Act as a professional software localization expert. Translate each key from {source} to {target}. Preserve ICU message format placeholders like {name} and {{count}}. Maintain Markdown formatting including links and code blocks. Match the tone and formality of the source text. Technical terms that are typically untranslated in the industry should remain in English."
  }
}

異なるプロンプトを試して翻訳動作をカスタマイズすることができますが、このプロンプトが良い出発点であることがわかっています！

**provider**設定は直接LLMアクセスを制御します：

  • id — openaiまたはanthropicのいずれか
  • model — 使用する特定のモデルバージョン。例：gpt-4o-mini、gpt-4o（OpenAI）、またはclaude-3-haiku、claude-3-sonnet（Anthropic）。
  • prompt — 翻訳動作を導くシステムプロンプト。{source}と{target}プレースホルダーは実行時に実際の言語コードに置き換えられます。このプロンプトは、用語、スタイル、ドメイン固有のルールを適用する機会です。

オプション2. Lingo.devエンジン

Lingo.devエンジンをAI翻訳エンジンとして使用する場合は、providerノードを完全にスキップできます。

エンジンはLingo.devチームの研究とエンジンの設定に基づいて、モデルとプロンプトを自動的に選択します。

i18n.jsonの設定：

{
  "locale": {
    "source": "en",
    "targets": ["es", "ja"]
  },
  "buckets": {
    "json": {
      "include": ["locales/[locale].json"]
    }
  }
}

注：Lingo.devエンジンを使用する場合は、providerノードを完全に省略してください。エンジンが自動的にモデルとプロンプトを選択します。

ステップ4. 翻訳

アプリをローカライズするには、次のコマンドを実行します：

npx lingo.dev@latest i18n

CLIは対象ファイルを作成し、コンテンツのフィンガープリントを追跡するi18n.lockファイルを更新します。これにより、後続の実行時に増分更新が確実に行われます。

これでアプリのコンテンツがローカライズされました！

次のステップ

これでコアとなるローカライズワークフローが完了しました。リポジトリには、他のコード成果物と同様にコミット、レビュー、デプロイできるローカライズされたファイルが含まれるようになりました。

ここから以下のことができます：

  • ワークフローの自動化: CI/CD統合 — CI/CD統合を設定して、プッシュごとにローカライズを実行し、プルリクエストや直接コミットを通じて変更を自動的にリポジトリにコミットします。
  • 内部の仕組みを理解する: 仕組み — アルゴリズム、パフォーマンス最適化、アーキテクチャの決定について学びます。