Localizeflowで自分の多言語ドキュメントを自動化した方法

問題点：翻訳は難しくなかった。課題は同期だった。

ここ3ヶ月間、ドキュメントとブログコンテンツを韓国語と英語の両方で運用してきました。

私のワークフローはシンプルでした：

1. 韓国語で草案作成。
2. 英語版を作成。
3. 両方を継続的に維持。

最初は問題なく感じられました。
多くの場合、AIにもう一つの言語の更新をお願いするだけで、意外とうまくいきました。

しばらくは効率的だと思えました。

しかし、ドキュメントが急速に進化し始めると — 新機能、更新されたスクリーンショット、APIの変更 — 徐々に問題が起き始めました。

英語版を更新するたびに、

• 韓国語の更新も必要であることを覚えておく必要があった。
• どこが変わったかを手動で探し出す必要があった。
• 見落としがないか二重にチェックする必要があった。

最初は両方のバージョンをしっかり同期させていました。

しかし、ある時期から不快なことに気づきました：

私は英語のドキュメントをすぐに更新していて、
「あとで韓国語を更新する」と自分に言い聞かせていたのです。

しかし、「あとで」はほとんど来ませんでした。

翻訳自体が難しいわけではありませんでした。

本当に難しかったのは、二言語の同期を保つことでした。

そして、創業者として私の集中すべきことは、言語間で古くなった段落を追いかけることではありません。

ある時、少し皮肉なことに気づきました：

私はローカリゼーション自動化製品を作っていて、
自分の多言語ドキュメントを手動で維持している。

それは不合理でした。

そこで、Localizeflowを自社のドキュメントとブログに導入してみることに決めました。

---

決断：自動化するか、言語を削減するか

現実的な選択肢は2つだけでした：

• 韓国語のメンテナンスをやめる。
• もしくはワークフローを自動化する。

言語を減らすのは違うと感じました。
でも手動で続けるのは非効率的に思えました。

多言語ドキュメントが規律と継続的な注意を必要とするなら、
それはスピード感のあるスタートアップでは続かないでしょう。

だから言語を減らす代わりに、
私は摩擦を取り除くことにしました。

Localizeflowをドキュメントリポジトリにインストールしました。

YAMLも、
追加の設定も不要。
ただGitHub Appをインストールするだけ。

それだけでした。

私は別のダッシュボードが欲しいわけでも、
別の翻訳ポータルが欲しいわけでもありませんでした。

既存のGitHubワークフローをそのまま維持したかったのです。

そして、それは実現しました。

---

---

セットアップの実態

サインアップ時にGitHub Appをインストールした後、「Connect repositories」ボタンをクリックしてドキュメントリポジトリを紐付けました。

リポジトリを接続すると、オンボーディングフローへ案内されます。

長い設定プロセスはなく、以下の3つの決定にまとめられました：

1. 言語
2. 出力構造
3. 用語集ルール

このプロセスは数分で完了しました。

私が特に驚いたのはスピードだけでなく、
自分のインフラを変更する必要がなかったことです。

CIスクリプトを追加するわけでもなく、
フォルダ構成を再編成するわけでもありませんでした。

基本的には、既存のリポジトリがどう動いているかを確認し、承認しただけでした。

これが重要だと感じました。

私の経験上、「自動化」ツールの多くはシステム変更を要求します。

しかし、このツールは違いました。

1. 対象言語の選択

最初の決定は対象言語の選択でした。

それぞれの言語は独立した翻訳Pull Requestのストリームになります。
この設計により、変更は隠れず目に見える形で管理されます。

GitHubのワークフローに自然にフィットします。

2. 翻訳ファイル配置場所の定義

出力パスにはリポジトリ解析機能を使いました。

リポジトリをスキャンして、ソースとターゲットのパスを提案してくれます。

提案を確認し、承認しました。

続ける前に、翻訳ファイル生成後のフォルダ構造のプレビューも確認しました。

このプレビューは重要でした。

翻訳されたファイルが正確にどこに置かれるのかが示されており、まだ何も変更されていません。

フォルダマッピングを一から考える必要はなく、
システムが既存の構成から推測したものを確認するだけでした。

---

3. 用語集ルール

セットアップ完了前に、簡単な用語集を追加しました。

例えば：

• Localizeflow
• GitHub App
• Co-op Translator

は翻訳しない設定にしました。

これにより、後から繰り返しPR修正する手間が省けます。

---

合計セットアップ時間

5分以内。

しかしより重要なのは：

CIの再設定不要。
新たなパイプライン不要。
フォルダ移動不要。

セットアップは新システム導入のように感じることはありませんでした。

既存システムに機能を追加するような感覚でした。

---

今英語を編集するとどうなるか

実際にどう変わったかを示します。

以前：

• 英語のドキュメントを編集。
• 韓国語のドキュメントを手動で開く。
• 変更箇所を探す。
• 更新する。
• 両方をコミット。

今：

1. 英語Markdownファイルを更新。
2. Localizeflowがハッシュ比較で変更を検知。
3. 自動で翻訳Pull Requestを生成。
4. それを確認してマージ。

それだけです。

もう自分で「翻訳する」必要はありません。
PRをレビューするだけです。

この心理的な違いは大きいです。

セットアップ後、Localizeflowのダッシュボードを積極的に監視することはありません。

ジョブの進捗はPull Request上に構造化されたステータス更新として投稿されます。

PRを開けば即座に：

• 現在の進行状況
• 完了した言語
• 残りのジョブ
• 失敗の有無

が分かります。

これは単なる翻訳ツールというより、CIのステータスのように振る舞い、

GitHubに「ネイティブ」に感じられます。

---

実際に改善したこと

1. 考える言語が一つになった

私は英語のソースのみを更新します。

「韓国語も更新したか？」と考える必要がなくなりました。

その認知負荷が消えました。

---

2. 変更が蓄積されなくなった

以前は、両言語更新の面倒さから小さな更新が溜まりがちでした。

今は、細かい文書修正も手軽に感じられます。

結果として、ドキュメントの質が間接的に向上します。

---

3. ワークフロー内に収まる

すべてPull Requestで完結します。

別のダッシュボードは不要。
ただレビューしてマージするだけ。

---

4. 更新時間が数分に短縮

以前は小さな変更でも2つのファイルに手を入れる必要がありました。

今は言語数に関わらずページの更新は同じ時間で済みます。

言語を増やす際の追加コストは事実上ゼロです。

---

課題として残っていること

実際に使う中で明らかになった制限もあります：

• Astroを使っているため、翻訳生成後に一部のURLを手動で調整し、ローカライズされたルートを正しく参照させる必要がありました。より強力なi18nルーティングを提供する静的サイトジェネレーターであれば、この問題は起きないかもしれません。

• ナビゲーションを簡単にするために、ヘッダーにシンプルな言語切替ボタンを実装しました。

  

こうした小さな手動作業があっても、全体のメンテナンス工数は劇的に減少しました。

---

本当の成果

以前：

二言語の維持が負担に感じられました。

今：

複数言語の維持が持続可能に感じられます。

これが戦略的な方程式を変えます。

ローカリゼーションが苦痛でなくなれば、
グローバル展開が負担ではなくデフォルトになるのです。

---

最後に振り返って

これは製品が機能することを証明する話ではありません。

実際の創業者としてのプレッシャー下でワークフローが機能することを証明する話です。

機能を作り、ユーザーと話し、運用をこなす中で —
ドキュメントは最初に疎かになりがちです。

多言語ドキュメントが厳格さを要求するなら、
続かないでしょう。

PRレビューだけで済むなら、
続く可能性があります。

Localizeflowを社内で使ってわかったことはひとつ：

翻訳は簡単。
真の問題は同期にある。

そしてこの同期は自動化できるのです。

---

誰に向いているか

こんな方に響くかもしれません：

• 多言語READMEを維持している
• スピード感のあるOSSプロジェクトを運営している
• MDXを多用するドキュメントを管理している
• 例やスクリーンショット、API参照を頻繁に更新している
• ソース変更後に翻訳を更新し忘れがちな方

多言語ドキュメントが「遅い時だけ維持可能」と感じるなら、
プロジェクトが速く動き始めると続かないでしょう。

自動化は責任を減らしません。
摩擦を取り除きます。

そしてスピード感ある環境では、
摩擦を取り除くことが一貫性を可能にすることが多いです。

多言語ドキュメントを維持していて、この方法が自分のリポジトリでどう見えるか試したい方は、ライブの例を案内しますのでお気軽にどうぞ。