HTML - Lingo.dev CLI

HTMLとは？

HTML（HyperText Markup Language）は、ウェブページやウェブアプリケーションを作成するための標準マークアップ言語です。タグを使用してコンテンツを構造化し、見出し、段落、リンク、画像、フォームなどの要素を定義します。

Lingo.dev CLIとは？

Lingo.dev CLIは、AIでアプリやコンテンツを翻訳するための無料のオープンソースCLIです。既存のパイプラインと統合しながら、従来の翻訳管理ソフトウェアに代わるものとして設計されています。

詳細については、概要をご覧ください。

このガイドについて

このガイドでは、Lingo.dev CLIを使用してHTMLファイルを翻訳する方法を説明します。

以下の方法を学びます：

ゼロからプロジェクトを作成する
翻訳パイプラインを設定する
AIで翻訳を生成する

前提条件

Lingo.dev CLIを使用するには、Node.js v18以上がインストールされていることを確認してください：

❯ node -v
v22.17.0

ステップ 1. プロジェクトのセットアップ

プロジェクトのディレクトリにi18n.jsonファイルを作成します：

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {}
}

このファイルは、翻訳パイプラインの動作を定義し、どの言語間で翻訳するか、ローカライズ可能なコンテンツがファイルシステム上のどこに存在するかを含みます。

利用可能なプロパティの詳細については、i18n.jsonをご覧ください。

ステップ 2. ソースロケールの設定

_ソースロケール_は、コンテンツが最初に書かれた元の言語と地域です。ソースロケールを設定するには、i18n.jsonファイルのlocale.sourceプロパティを設定します：

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {}
}

ソースロケールはBCP 47言語タグとして提供する必要があります。

Lingo.dev CLIがサポートするロケールコードの完全なリストについては、サポートされているロケールコードをご覧ください。

ステップ3. ターゲットロケールの設定

_ターゲットロケール_とは、コンテンツを翻訳したい言語や地域のことです。ターゲットロケールを設定するには、i18n.jsonファイルのlocale.targetsプロパティを設定します：

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {}
}

ステップ4. ソースコンテンツの作成

まだ作成していない場合は、翻訳するコンテンツを含むHTMLファイルを1つ以上作成してください。これらのファイルは、パスのどこかにソースロケールを含む場所に配置する必要があります（例：ディレクトリ名としてen/や、ファイル名の一部としてmessages.en.htmlなど）。

HTMLファイルの場合、翻訳可能なコンテンツには以下が含まれます：

HTML要素内のテキストコンテンツ
以下を含む属性値：
- alt属性（画像の説明）
- title属性（ツールチップ）
- placeholder属性（入力ヒント）
- value属性（ボタンと入力値）
- メタタグのcontent属性
lang属性は自動的にターゲットロケールに合わせて更新されます

スクリプトタグ、スタイルタグ、翻訳不要な属性は保持されます。

例：

<!DOCTYPE html>
<html lang="en">
  <head>
    <title>MyApp - Hello World</title>
    <meta name="description" content="A simple demo app" />
  </head>
  <body>
    <h1>Welcome to MyApp</h1>
    <p>Hello, world! This is a simple demo with <strong>bold text</strong>.</p>
    <img src="example.jpg" alt="Example image" />
  </body>
</html>

ステップ5. バケットの作成

i18n.jsonファイルで、bucketsオブジェクトに"html"オブジェクトを追加します：

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {
    "html": {}
  }
}

"html"オブジェクト内で、1つ以上のincludeパターンの配列を定義します：
```
{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {
    "html": {
      "include": ["./[locale]/example.html"]
    }
  }
}
```
これらのパターンは、翻訳するファイルを定義します。

パターン自体は：
- 設定されたロケールのプレースホルダーとして[locale]を含む必要があります
- ファイルパスを指定できます（例："[locale]/config.html"）
- ワイルドカードプレースホルダーとしてアスタリスクを使用できます（例："[locale]/*.html"）
再帰的なグロブパターン（例：**/*.html）はサポートされていません。

ステップ 6. LLMを設定する

Lingo.dev CLIは大規模言語モデル（LLM）を使用してAIでコンテンツを翻訳します。これらのモデルを使用するには、サポートされているプロバイダーからAPIキーが必要です。

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

Lingo.devアカウントにサインアップする。
次のコマンドを実行します：
```
npx lingo.dev@latest login
```
これによりデフォルトのブラウザが開き、認証を求められます。
画面の指示に従ってください。

ステップ 7. 翻訳を生成する

i18n.jsonファイルが含まれているディレクトリで、次のコマンドを実行します：

npx lingo.dev@latest run

このコマンドは以下を実行します：

i18n.jsonファイルを読み込みます。
翻訳が必要なファイルを見つけます。
ファイルから翻訳可能なコンテンツを抽出します。
設定されたLLMを使用して抽出されたコンテンツを翻訳します。
翻訳されたコンテンツをファイルシステムに書き戻します。

翻訳が初めて生成されるとき、i18n.lockファイルが作成されます。このファイルは翻訳済みのコンテンツを追跡し、後続の実行時に不要な再翻訳を防ぎます。

例

en/example.html

<!DOCTYPE html>
<html lang="en">
  <head>
    <title>MyApp - Hello World</title>
    <meta name="description" content="A simple demo app" />
  </head>
  <body>
    <h1>Welcome to MyApp</h1>
    <p>Hello, world! This is a simple demo with <strong>bold text</strong>.</p>
    <img src="example.jpg" alt="Example image" />
    <input type="text" placeholder="Enter text here" />
    <a href="#" title="Click for more">Learn more</a>
  </body>
</html>

es/example.html

<!DOCTYPE html>
<html lang="es">
  <head>
    <title>MyApp - Hola Mundo</title>
    <meta name="description" content="Una aplicación de demostración simple" />
  </head>
  <body>
    <h1>Bienvenido a MyApp</h1>
    <p>¡Hola, mundo! Esta es una demostración simple con <strong>texto en negrita</strong>.</p>
    <img src="example.jpg" alt="Imagen de ejemplo" />
    <input type="text" placeholder="Ingresa texto aquí" />
    <a href="#" title="Haz clic para más">Saber más</a>
  </body>
</html>

i18n.json

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {
    "html": {
      "include": ["./[locale]/example.html"]
    }
  }
}

i18n.lock

version: 1
checksums:
  ab95e8c959a889717f02a05af5c5b1e6:
    head/0/0: 7d39787547365ee4194f29f3f54e5c05
    head/1#content: 49f8864eb0e53903f04532bf33e1e4fa
    head/2#content: c2a1da93efb7e744d100df705e5fcbfd
    head/3#content: d94b318cb327f61f1aea44a6cb1fdcad
    body/0/0: d1c3a9f35e377554a4ccaa467ca26614
    body/1/0: e19afd1952881bdf10063f9478980147
    body/1/1/0: 7cd9256312384858ecba6c29d3c2e550
    body/1/2: ce8b9bb44f031705708a70e068bb73c8
    body/1/3/0: 037d114f19b882f08994712b8d9c1e37
    body/1/4: f05f450fffcb17520c441ab9789f40ce
    body/2/0/0/0: 57d373bcffe2d376cbf9919da30ca30b
    body/3#alt: 68f95fca639f8bf72a4796b6734b02d5
    body/4#alt: cb7d920c3bbcade1c8e0307093f58573
    body/5#placeholder: a05ce3b4578f55e41bd2ad4964f966b4
    body/6#placeholder: a4554ed67c02872e302b0042724f859d
    body/7#title: c903c6985a40ce02d65c90229de35a4e
    body/7/0: e598091d132f890c37a6d4ed94f6d794
    body/8#title: d656021ba5f485fa1a82f8aac6ecc5de
    body/8/0: 1c6856488bd34ad87fcacce2d8e66a0b
    body/9/0: 862964e6cd73cdffdcac622406c6bac9