Blog

Lingo.dev の使い方：初心者向けチュートリアル

Mark Ponomarev

Mark Ponomarev

10 6月 2025

Lingo.dev の使い方：初心者向けチュートリアル

多言語対応アプリケーションの作成は、国際的なオーディエンスにリーチするために不可欠となっています。しかし、従来の国際化（i18n）アプローチでは、大幅なコードのリファクタリング、複雑な設定、継続的なメンテナンスのオーバーヘッドがしばしば必要でした。ここで、Lingo.devがローカリゼーションプロセスに革命をもたらします。

Lingo.devは、AIを活用したオープンソースの国際化ツールキットであり、開発者が多言語対応アプリケーションに取り組む方法を変革します。高度な言語モデルとインテリジェントな自動化を活用することで、ローカリゼーションの従来の課題を排除し、最小限の労力と最大限の精度でアプリケーション全体を翻訳することを可能にします。

この包括的なチュートリアルでは、初期セットアップから高度な実装戦略まで、Lingo.devエコシステム全体をガイドします。シンプルなウェブサイトを構築している場合でも、複雑なエンタープライズアプリケーションを構築している場合でも、AI駆動のローカリゼーションの力を活用して、真にグローバルなソフトウェアを作成する方法を学ぶことができます。

💡
美しいAPIドキュメントを生成する優れたAPIテストツールをお探しですか？

最大限の生産性で開発チームが連携するための統合されたオールインワンプラットフォームをお探しですか？

Apidogは、お客様のあらゆる要求に応え、Postmanをはるかに手頃な価格で置き換えます！
button

Lingo.devを始める

前提条件と環境設定

Lingo.devを始める前に、開発環境が以下の要件を満たしていることを確認してください。

  1. Node.js: 最適な互換性のためにバージョン16.0以上が必要です。
  2. パッケージマネージャー: npm、yarn、またはpnpm（モノレポ設定にはpnpmが推奨されます）
  3. Reactアプリケーション: コンパイラを使用するには、既存のReactプロジェクトが必要です。
  4. APIキー: 多くの機能はオフラインで動作しますが、高度なAIモデルにはAPIキーが必要です。

インストールプロセス

Lingo.devの魅力は、その簡単なインストールプロセスにあります。ほとんどのユースケースでは、単一のコマンドで開始できます。

npm install lingo.dev

このコマンドは、4つのコンポーネントすべてを含むコアパッケージをインストールします。特定のニーズに応じて、追加のパッケージをインストールすることもできます。

# TypeScriptのサポートのため
npm install --save-dev @types/lingo.dev

# 特定のフレームワーク統合のため
npm install lingo.dev-next  # Next.js固有の機能
npm install lingo.dev-vite  # Vite固有の機能

初期設定

インストール後、ローカリゼーション設定を定義するための構成ファイルを作成します。構成アプローチは使用しているコンポーネントによって異なりますが、コアコンセプトは一貫しています。

コンパイラを使用する典型的なReactアプリケーションの場合、プロジェクトルートにlingo.config.jsファイルを作成します。

module.exports = {
  // ソース言語を定義
  sourceLocale: "en",

  // 翻訳のターゲット言語を指定
  targetLocales: ["es", "fr", "de", "ja", "zh"],

  // 翻訳のためのAIモデルを設定
  models: {
    // 言語ペアに特定のモデルを使用
    "en:es": "gpt-4",
    "en:fr": "claude-3",
    // その他のすべてのペアのデフォルトモデル
    "*:*": "groq:mistral-saba-24b",
  },

  // 高度なオプション
  caching: {
    enabled: true,
    directory: ".lingo-cache",
  },

  // 品質保証設定
  validation: {
    checkPlurals: true,
    validateVariables: true,
    ensureCompleteness: true,
  },
};

コンパイラの実装

Next.js統合

Next.jsアプリケーションの場合、コンパイラの統合は非常にエレガントです。next.config.jsまたはnext.config.tsファイルを変更します。

import lingoCompiler from "lingo.dev/compiler";

const nextConfig = {
  // 既存のNext.js構成
  reactStrictMode: true,
  images: {
    domains: ["example.com"],
  },
};

// Lingoコンパイラで構成をラップ
export default lingoCompiler.next({
  sourceLocale: "en",
  targetLocales: ["es", "fr", "de", "ja"],
  models: {
    "*:*": "groq:mistral-saba-24b",
  },
  useDirective: true,
})(nextConfig);

コンパイルプロセスの理解

この構成でnext buildを実行すると、コンパイラはいくつかの洗練された操作を実行します。

  1. 静的解析: Reactコンポーネントツリー全体を解析し、すべてのテキストコンテンツを識別します。
  2. コンテキスト抽出: AIは周囲のコードを分析し、正確な翻訳のためのコンテキストを理解します。
  3. 翻訳生成: 識別された各文字列は、指定されたAIモデルを使用して翻訳されます。
  4. バンドル作成: 各ターゲット言語に対して個別のバンドルが生成されます。
  5. 最適化: 翻訳は重複排除され、最小限のバンドルサイズに最適化されます。

翻訳対応コンポーネントの記述

コンパイラは特別な構文を必要としませんが、特定のパターンに従うことで最適な翻訳品質が保証されます。

// 良い例: 明確で完全な文
function WelcomeMessage() {
  return (
    <div>
      <h1>Welcome to Our Platform</h1>
      <p>Start your journey by exploring our features.</p>
    </div>
  );
}

// より良い例: コンテキストのためのセマンティックHTMLの使用
function ProductCard({ product }) {
  return (
    <article>
      <h2>{product.name}</h2>
      <p className="price">${product.price}</p>
      <button>Add to Cart</button>
    </article>
  );
}

// 最良の例: アクセシビリティのためのaria-labelsを含める
function Navigation() {
  return (
    <nav aria-label="Main navigation">
      <a href="/home">Home</a>
      <a href="/products">Products</a>
      <a href="/about">About Us</a>
    </nav>
  );
}

CLIを使いこなす

基本的な翻訳コマンド

CLIは、アプリケーションコード外のファイルを翻訳するための強力な機能を提供します。効果的に使用する方法は以下の通りです。

# 単一ファイルの翻訳
npx lingo.dev translate data/content.json --to es,fr,de

# ディレクトリ全体の翻訳
npx lingo.dev translate content/ --to ja --recursive

# 特定のモデルでの翻訳
npx lingo.dev translate README.md --to zh --model gpt-4

高度なCLI機能

CLIのインテリジェントなキャッシュシステムは、変更されたコンテンツのみを翻訳することで効率を保証します。

# 初回実行: すべてを翻訳
npx lingo.dev run

# 後続の実行: 変更のみを翻訳
npx lingo.dev run --cache-dir .lingo-cache

構成ファイルを使用して翻訳ワークフローを作成することもできます。

# .lingo-cli.yml
version: 1
projects:
  - name: documentation
    source: ./docs
    include: "**/*.md"
    exclude: "**/drafts/**"
    targetLocales: [es, fr, de, ja]

  - name: content
    source: ./content
    include: "**/*.json"
    targetLocales: [es, fr, de, ja, zh, ko]
    model: claude-3

異なるファイルタイプの処理

CLIは様々なファイル形式をインテリジェントに処理します。

JSONファイル: 値を翻訳しながら構造を維持します。

// オリジナル
{
  "welcome": "Welcome",
  "features": {
    "title": "Our Features",
    "description": "Discover what we offer"
  }
}

// 翻訳済み (スペイン語)
{
  "welcome": "Bienvenido",
  "features": {
    "title": "Nuestras Características",
    "description": "Descubre lo que ofrecemos"
  }
}

Markdownファイル: コンテンツを翻訳しながら書式を維持します。

# オリジナル
## Getting Started
Follow these steps to begin.

# 翻訳済み (フランス語)
## Commencer
Suivez ces étapes pour commencer.

CI/CD統合のセットアップ

GitHub Actions構成

GitHub Actionsを使用してローカリゼーションワークフローを自動化します。

name: Automated Localization
on:
  push:
    branches: [main]
    paths:
      - "src/**"
      - "content/**"
      - "i18n.json"

jobs:
  localize:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          token: ${{ secrets.GITHUB_TOKEN }}

      - uses: actions/setup-node@v4
        with:
          node-version: "18"

      - uses: lingodotdev/lingo.dev@main
        with:
          api-key: ${{ secrets.LINGODOTDEV_API_KEY }}
          source-locale: en
          target-locales: es,fr,de,ja,zh

      - name: Commit translations
        run: |
          git config --local user.email "action@github.com"
          git config --local user.name "GitHub Action"
          git add .
          git diff --staged --quiet || git commit -m "Update translations"
          git push

高度なCI/CD戦略

大規模なプロジェクトの場合、洗練されたワークフローを実装します。

name: Translation Review Process
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  translate-pr:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Detect changed files
        id: changes
        run: |
          echo "files=$(git diff --name-only ${{ github.event.before }} ${{ github.sha }})" >> $GITHUB_OUTPUT

      - uses: lingodotdev/lingo.dev@main
        with:
          api-key: ${{ secrets.LINGODOTDEV_API_KEY }}
          files: ${{ steps.changes.outputs.files }}
          create-pr: true
          pr-title: "Translations for PR #${{ github.event.number }}"

SDKの活用

リアルタイム翻訳の実装

SDKは、実行時翻訳が必要な動的コンテンツの処理に優れています。

import { LingoDotDevEngine } from "lingo.dev/sdk";

// エンジンの初期化
const translator = new LingoDotDevEngine({
  apiKey: process.env.LINGODOTDEV_API_KEY,
  defaultModel: "groq:mistral-saba-24b",
  caching: {
    enabled: true,
    ttl: 3600, // 1時間キャッシュ
  },
});

// ユーザー生成コンテンツの翻訳
async function translateUserComment(comment, targetLanguage) {
  try {
    const translated = await translator.translate(comment, {
      sourceLocale: "auto", // ソース言語を自動検出
      targetLocale: targetLanguage,
      context: "user comment on social media",
    });

    return translated;
  } catch (error) {
    console.error("Translation failed:", error);
    return comment; // 元のコンテンツにフォールバック
  }
}

// 効率のためのバッチ翻訳
async function translateMultipleItems(items, targetLanguage) {
  const translations = await translator.translateBatch(items, {
    sourceLocale: "en",
    targetLocale: targetLanguage,
    preserveFormatting: true,
  });

  return translations;
}

高度なSDKパターン

複雑なアプリケーションのために洗練された翻訳パターンを実装します。

// コンテキスト対応翻訳
class ContextualTranslator {
  constructor(apiKey) {
    this.engine = new LingoDotDevEngine({ apiKey });
    this.contextCache = new Map();
  }

  async translateWithContext(text, metadata) {
    const context = this.buildContext(metadata);

    return await this.engine.translate(text, {
      sourceLocale: metadata.sourceLanguage || "en",
      targetLocale: metadata.targetLanguage,
      context: context,
      tone: metadata.tone || "neutral",
      formality: metadata.formality || "casual",
    });
  }

  buildContext(metadata) {
    return `
      Domain: ${metadata.domain || "general"}
      User Type: ${metadata.userType || "consumer"}
      Platform: ${metadata.platform || "web"}
      Subject: ${metadata.subject || "general content"}
    `;
  }
}

// 使用例
const translator = new ContextualTranslator(apiKey);
const translated = await translator.translateWithContext(
  "Check out our latest features!",
  {
    targetLanguage: "ja",
    domain: "technology",
    userType: "developer",
    formality: "professional",
  }
);

ベストプラクティスと最適化

パフォーマンス最適化

  1. インテリジェントなキャッシュの実装: 複数レベルで翻訳をキャッシュし、API呼び出しを最小限に抑えます。
  2. バッチ操作の使用: 複数の翻訳を単一のリクエストにまとめます。
  3. CDNの活用: エッジロケーションから翻訳された静的アセットを配信します。
  4. プログレッシブローディングの実装: まず表示されるコンテンツの翻訳をロードします。

品質保証

体系的な検証を通じて翻訳品質を確保します。

// 翻訳検証ミドルウェア
function validateTranslation(original, translated, locale) {
  const checks = {
    // 変数が保持されていることを確認
    variablesPreserved: () => {
      const originalVars = original.match(/\{\{.*?\}\}/g) || [];
      const translatedVars = translated.match(/\{\{.*?\}\}/g) || [];
      return originalVars.length === translatedVars.length;
    },

    // 空の翻訳がないかチェック
    notEmpty: () => translated.trim().length > 0,

    // HTMLの保持を検証
    htmlPreserved: () => {
      const originalTags = original.match(/<[^>]+>/g) || [];
      const translatedTags = translated.match(/<[^>]+>/g) || [];
      return originalTags.length === translatedTags.length;
    },
  };

  return Object.entries(checks).every(([name, check]) => {
    const result = check();
    if (!result) {
      console.warn(`Translation validation failed: ${name}`);
    }
    return result;
  });
}

一般的な問題のトラブルシューティング

ビルド時の問題

コンパイルの問題が発生した場合:

  1. キャッシュのクリア: .lingo-cacheディレクトリを削除して再ビルドします。
  2. 構成の検証: すべてのロケールがISO標準に従っていることを確認します。
  3. 依存関係の確認: 最新のLingo.devバージョンに更新します。
  4. ログの確認: DEBUG=lingo:*で詳細ログを有効にします。

実行時の課題

SDK関連の問題の場合:

  1. APIキーの検証: キーの権限と割り当て量を確認します。
  2. ネットワークタイムアウト: 指数バックオフ付きのリトライロジックを実装します。
  3. レート制限: リクエストキューイングとスロットリングを使用します。
  4. フォールバック戦略: 常にグレースフルデグラデーションを提供します。

結論

Lingo.devは、アプリケーションのローカリゼーションへのアプローチ方法において根本的な変化をもたらします。AIを活用した翻訳と開発者向けのツールを組み合わせることで、かつて複雑で時間のかかるプロセスだったものを、自動化された効率的なワークフローに変革します。小さなウェブサイトを構築している場合でも、大規模なアプリケーションを構築している場合でも、Lingo.devのモジュラーアーキテクチャは、国際的なオーディエンスに効果的にリーチするために必要な柔軟性とパワーを提供します。

Lingo.devでの成功の鍵は、そのコンポーネントを理解し、各ローカリゼーションの課題に適切なツールを選択することにあります。静的なReactコンテンツにはコンパイラを使用し、構成やドキュメントにはCLIを活用し、CI/CD統合で自動化し、動的コンテンツはSDKで処理します。このチュートリアルで概説されているプラクティスに従うことで、世界中のユーザーに響く真の多言語対応アプリケーションを作成するための準備が整います。

Lingo.devでの旅を続けるにあたり、ローカリゼーションは単なる翻訳ではなく、ユーザーの母国語で意味のあるつながりを築くことであることを忘れないでください。Lingo.devのインテリジェントな自動化と思慮深い実装により、これまで以上に効果的にこの目標を達成できます。

💡
美しいAPIドキュメントを生成する優れたAPIテストツールをお探しですか？

最大限の生産性で開発チームが連携するための統合されたオールインワンプラットフォームをお探しですか？

Apidogは、お客様のあらゆる要求に応え、Postmanをはるかに手頃な価格で置き換えます！
button

ApidogでAPIデザイン中心のアプローチを取る

APIの開発と利用をよりシンプルなことにする方法を発見できる

無料会員登録ダウンロード