クイックスタート

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

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

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

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

さあ、始めましょう！

前提条件

マークダウン

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

アプリケーション

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

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

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

React: react-intl
Vue: vue-i18n
Svelte: svelte-i18n
Angular: ngx-translate
iOS: Localizable.xcstrings
Android: strings.xml

ステップ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にロケールファイルの検索場所と作成場所を指示するグロブのようなパターン。特殊な[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_TOKEN環境変数を追加して手動で認証できます：

LINGODOTDEV_API_TOKEN=...

トークンは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統合をセットアップします；
内部構造の理解: 動作原理 — アルゴリズム、パフォーマンス最適化、およびアーキテクチャ上の決定について学びます。