以下のサンプルはすべて、.lingo/config.json がコミット済みで、翻訳もあらかじめ入っている実在のリポジトリです。生成された出力と並べて設定内容を確認できます。ほとんどはそのまま動かせるアプリケーションで、一部はファイル形式だけを示すためのものです。気になるものをクローンまたはフォークして、lingo link を実行して自分のエンジンを紐づけ、そのまま push できます。
まず、進め方を選びましょう#
CLI でのローカライズには 2 つのやり方があり、どちらを選ぶかで見るべき例が変わります。
今あるファイルをそのまま翻訳する。 フレームワークが翻訳を独自形式で管理している場合 — Rails YAML、Android XML、Laravel PHP、ARB、Markdown など — CLI がそのファイルをその場で翻訳します。コードは一切変える必要がありません。以下の 11 個の例のうち、9 個がこの方法です。
キーなしで書く。 文字列を使う場所で l.text(...) で囲むと、lingo extract がハッシュキー付きのカタログを生成します。翻訳キーを名前付けしたり保守したりする必要はありません。その代わり、ビルドステップとランタイムパッケージが必要になります。Web アプリの 2 つの例で紹介しているのがこの方法です。
モバイルアプリ#
| 例 | 形式 | この形式を選ぶ理由 |
|---|---|---|
| iOS | xcode-xcstrings | String Catalog にすべてのロケールが入るため、ターゲットパスはソースパスと同じです。 |
| Android | android | ソースはプレーンなvalues/で、Android標準の修飾子（values-pt-rBR/）をそのまま使える |
| Flutter | flutter | @メタデータとICUプレースホルダーは保持したまま、@@localeはファイルごとに書き換え |
Web アプリ#
キーを使わない2つのサンプルです。どちらも文字列を l.text(...) で囲み、lingo extract でカタログを生成するため、中央の列にはファイル形式ではなくランタイムパッケージ名が表示されます。
| 例 | パッケージ | この形式を選ぶ理由 |
|---|---|---|
| React + Vite | @lingo.dev/react | キー不要で記述でき、生成される宣言によってl.text()を抽出済み文字列だけに絞り込める |
| Next.js | @lingo.dev/react-next | キーなしオーサリングに、ロケールルーティング、hreflang、スイッチャーを組み合わせた Pages Router |
本番環境でのhreflang
LingoHeadはhreflang URLを、デフォルトでは空のbaseUrl propをもとに組み立てるため、そのままだとタグは相対URLになります。検索エンジンが期待するのは絶対URLです。運用で使う前に、サイトのオリジン（<LingoHead baseUrl="https://example.com" />）を渡してください。
コンテンツと仕様#
| 例 | 形式 | この形式を選ぶ理由 |
|---|---|---|
| Markdown docs | md, mdx | 基本は本文が対象で、frontmatterフィールドとMDX propsは必要に応じて含められる |
| Markdoc | markdoc, json | Next.js のコンテンツと UI 文字列を1回の push でまとめて反映 — 3つのエントリにそれぞれ異なるオプションを設定 |
| OpenAPI | yaml-openapi | 対象は要約と説明のみ。パス、operation IDs、enumはそのまま |
フレームワークのカタログ#
| 例 | 形式 | この形式を選ぶ理由 |
|---|---|---|
| Rails | yaml-root-key | ロケールがYAMLのルートキーに入るため、ルートキー自体も書き換えられる |
| Laravel | php, po | Laravelのカタログに加えてgettextファイルにも対応し、:nameプレースホルダーはどちらでも保持される |
| TypeScript modules | typescript | JSON ではなく TypeScript モジュールとして使うカタログです。ファイル形式のみを示す例で、これを利用するアプリはありません。 |
TypeScript カタログには default export が必要です
typescript形式が読み取るのはdefault export、つまりexport default { … }です。as constの有無は問いません。named exportでは翻訳対象のコンテンツは生成されず、実行はソースをそのままコピーして終了します。pushで「ファイルはローカライズされた」と出ているのに出力トークンがほぼゼロなら、まずexportの形を確認してください。
これらを使うには#
npm install -g @lingo.dev/cli
lingo login
lingo link # writes your own orgId and engineId into .lingo/config.json
lingo push --waitどのサンプルにも orgId と engineId はコミットされていません。これは、フォークしたリポジトリから他人のエンジン経由で push できないようにするためです。lingo link を使えば、その両方をローカルで補えます。
CLI ではなく GitHub App を使う場合
GitHub Appは、リポジトリにコミットされたengineIdから.lingo/config.jsonを読み取ります。組織はAppのインストール情報から解決されますが、エンジンはそのファイル内に書かれている必要があります。forkしたら、先にlingo linkを実行して更新後の設定をコミットし、そのうえでAppをインストールしてください。
すべての形式にサンプルがあるわけではありません#
この11件で、特によく問い合わせの多いフレームワークはひと通りカバーしていますが、CLIが翻訳できる形式は18種類あります。xliff、srt、Xcodeの.stringsと.stringsdict、汎用のyaml、そして単体のJSON/JSONCは、ここにリポジトリがなくても問題なく使えます。完全な一覧と各形式で必要な設定は、Formatsで確認できます。
