第1回：GitHub多国語READMEの自動生成

• 📂 目次：【GitHub・業務効率化・開発ツール】連載の全記事まとめ
• 第1回：GitHub Actionsで多国語版README.mdを自動生成（閲覧中）
• 第2回：GitHub Actionsでindex.htmlを自動生成
• 第3回：GitHubのMarkdownにプロフィールバッジを自動挿入
• 第4回：GitHubのMarkdown内のプロフィールバッジを自動更新
• 💡 今後も開発効率化・ツール連携に関する記事を随時追加していきます！

【GitHub Actions】READMEの英語版、もう手動で翻訳しない。Pushするだけで自動生成する仕組みを作った

この記事でわかること

• ✅ README.ja.md だけ管理すれば、英語版 README.md が自動で最新化される仕組み
• ✅ DeepL API を使った翻訳精度の高い自動化ワークフロー
• ✅ 翻訳漏れ・内容の食い違いをゼロにする運用方法
• ✅ 私が実際に運用して気づいた3つの落とし穴と対処法

---

はじめに：この悩み、ありませんか？

GitHubでOSSや業務ツールを公開していると、こんな経験ありませんか？

「日本語版READMEは更新したのに、英語版を更新し忘れて海外の人に古い情報を見られていた…」

「英語版を手動で翻訳するのが面倒で、結局日本語だけになって海外ユーザーが離れていく…」

「翻訳サービスにコピペして、Markdownの構造が崩れて手直しが大変…」

私も何度も同じ失敗を繰り返しました。そこで考えたのが、「日本語版を編集 → Push → 英語版が自動生成」 という完全自動化の仕組みです。

本記事では、実際に私のリポジトリで運用しているワークフローを公開します。

---

なぜ README.ja.md をベースにするのか

多くのプロジェクトでは README.md がメインですが、日本国内向けの開発では以下がほとんどです。

• 設計・開発の言語は日本語
• Issue・Pull Requestも日本語
• ドキュメントも日本語が起点

そのため、今回は 日本語版を「唯一の編集対象」 にし、英語版は自動生成物として扱います。

README.ja.md  ← あなたが編集する（唯一の手作業）
      │
      │ GitHub Actions（自動）
      ▼
README.md     ← 英語版（自動生成・編集不要）

これにより、翻訳漏れが物理的に発生しなくなり、ドキュメントの品質が維持されます。

---

多言語構成のメリット

今回の構成は以下の通りです。

README.ja.md   ← 編集対象（日本語）
README.md      ← 自動生成（英語）

英語版の先頭には、自動的に日本語版への導線を挿入しています。

🇯🇵 日本語ドキュメント (Japanese Documentation)は **[README.ja.md](./README.ja.md)** をご覧ください。

海外ユーザー → 英語版をそのまま閲覧
日本のユーザー → 国旗マークから日本語版へ1クリックで移動

将来的に README.zh.md（中国語）や README.ko.md（韓国語）への拡張も、同じワークフローの流用で可能です。

---

システム構成（処理の流れ）

全体の流れは極めてシンプルです。

README.ja.md を Push
        │
        ▼
GitHub Actions 起動
        │
        ▼
DeepL API で翻訳
        │
        ▼
README.md を生成
        │
        ▼
日本語版へのリンクを自動挿入
        │
        ▼
生成結果を検証
        │
        ▼
変更があれば自動 Commit & Push

開発者がやることは「日本語版を更新してPushする」だけ。
英語版は触る必要がありません。

---

事前準備：DeepL APIキーの登録

GitHubリポジトリの Settings → Secrets and variables → Actions に、以下を登録します。

Secret名	値
DEEPL_API_KEY	DeepLのAPIキー

💡 補足：DeepLの無料枠は月50万文字まで。個人のOSS運用ならほとんどの場合、無料枠で十分です。

---

ワークフロー全文

.github/workflows/translate-readme.yaml に配置します。

name: Translate README to English

on:
  push:
    paths:
      - 'README.ja.md'
  workflow_dispatch:

jobs:
  translate:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Check README.ja.md exists
        run: |
          if [ ! -s README.ja.md ]; then
            echo "Error: README.ja.md is missing or empty."
            exit 1
          fi

      - name: Translate with DeepL API
        env:
          DEEPL_API_KEY: ${{ secrets.DEEPL_API_KEY }}
        run: |
          JA_TEXT=$(cat README.ja.md | jq -Rs .)
          RESPONSE=$(curl -s -X POST "https://api-free.deepl.com/v2/translate" \
            --header "Authorization: DeepL-Auth-Key $DEEPL_API_KEY" \
            --data-urlencode "text=$JA_TEXT" \
            --data-urlencode "target_lang=EN" \
            --data-urlencode "source_lang=JA")

          ERROR_MSG=$(echo "$RESPONSE" | jq -r '.message // empty')
          if [ -n "$ERROR_MSG" ]; then
            echo "DeepL API Error: $ERROR_MSG"
            exit 1
          fi

          echo "$RESPONSE" | jq -r '.translations[0].text' > README.md

      - name: Add link to Japanese version
        run: |
          LINK=$'🇯🇵 Japanese documentation is also available.\\n[README.ja.md](./README.ja.md)\\n\\n'
          awk -v link="$LINK" 'NR==1 && /^#/ {print; print link; next} {print}' README.md > README.md.tmp
          mv README.md.tmp README.md

      - name: Verify output
        run: |
          if [ ! -s README.md ]; then
            echo "Error: Generated README.md is empty."
            exit 1
          fi

      - name: Commit and push if changed
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"
          git add README.md
          if git diff --cached --quiet; then
            echo "No changes to commit."
          else
            git commit -m "docs: auto-translate README.ja.md to README.md"
            git push
          fi

---

ワークフローのポイント解説

① 入力ファイルの事前検証

if [ ! -s README.ja.md ]; then
  exit 1
fi

空ファイルや誤削除状態での実行を防ぎ、意図しない上書きをブロックします。

② 翻訳エンジンの切り替え余地

workflow_dispatch を入れているため、将来的に OpenAI / Gemini / Claude への切り替えも容易です。現在は DeepL のみ実装済みです。

③ エラーハンドリング

DeepL API のエラーレスポンスを検知し、ワークフローを即座に停止します。

• APIキー誤り
• 利用制限超過
• ネットワークエラー

いずれも 異常なREADME.mdがコミットされる前に検知 できます。

④ 日本語版への導線を自動挿入

最初の見出し（#）の直後にリンクを挿入するため、READMEの構造を崩しません。日本のユーザーが「日本語版は？」と迷う時間をゼロにします。

⑤ 変更がなければCommitしない

if git diff --cached --quiet; then
  echo "No changes to commit."

無駄なコミット履歴を増やさず、Gitログをクリーンに保ちます。

---

実際に運用して気づいた3つの落とし穴

🚨 落とし穴1：DeepL APIの無料枠を超えた

対処：複数リポジトリで使う場合、APIキーをOrganization Secretsで一元管理し、文字数をモニタリングする別ジョブを追加しました。

🚨 落とし穴2：Markdown内のコードブロックが翻訳された

対処：DeepL APIの tag_handling=html 等の活用や、コードブロックを一時的にプレースホルダに置き換える前処理を検討中です。現状は手動で微修正しています。

🚨 落とし穴3：自動生成コミットでCIが無限ループした

対処：paths フィルタで README.ja.md のみを監視対象にし、自動生成された README.md のPushではワークフローが再実行されないよう制御しています。

---

導入後の効果

項目	Before	After
英語版更新の手間	手動翻訳（15分〜）	0分（完全自動）
翻訳漏れリスク	頻発	物理的に発生しない
海外からのStar	少なめ	増加傾向
ドキュメント品質	ばらつきあり	日本語版と常に同期

---

今後の展開

このワークフローは、GitHub Actions活用シリーズの第1弾です。

• 第2回：GitHub Actionsでindex.htmlを自動生成
• 第3回：GitHubのMarkdownにプロフィールバッジを自動挿入
• 第4回：GitHubのMarkdown内のプロフィールバッジを自動更新

これらを組み合わせることで、リポジトリ運用全体の自動化が進みます。

---

まとめ

項目	内容
解決した課題	多言語READMEの翻訳漏れ・手動更新の手間
キーワード	GitHub Actions, DeepL API, README自動翻訳, 多言語対応
得られる効果	保守コスト削減、海外ユーザーの離脱防止、OSSの信頼性向上

この仕組みを導入すれば、「日本語だけ更新して英語版を忘れる」というミスは二度と起きません。

ぜひご自身のリポジトリで試してみてください。動作報告や改善案があれば、コメントやGitHub Issueでお知らせください！

---

ソースコード

今回ご紹介したGitHub Actions Workflowのソースコードは、GitHubでも公開しています。

以下のリポジトリから、Workflowファイルや設定内容を確認できます。

• 🔗 GitHub:spec2clouds

本記事がお役に立ちましたら、いいね❤️ や GitHub Star⭐ をいただけると励みになります！IssueやPull Requestも歓迎していますので、改善案や機能追加のアイデアがありましたら、お気軽にご連絡ください。

---

• 📂 目次：【GitHub・業務効率化・開発ツール】連載の全記事まとめ
• 第1回：GitHub Actionsで多国語版README.mdを自動生成（閲覧中）
• 第2回：GitHub Actionsでindex.htmlを自動生成
• 第3回：GitHubのMarkdownにプロフィールバッジを自動挿入
• 第4回：GitHubのMarkdown内のプロフィールバッジを自動更新
• 💡 今後も開発効率化・ツール連携に関する記事を随時追加していきます！

📢 掲載通知を受け取る
著者をフォローして次回または新掲載の通知をお待ちください！

---