SuperClaude/docs/Development/translation-guide.md

README Translation Guide

概要

SuperClaude は Neural CLI を使用してローカルで高速翻訳を実現しています。

🎯 特徴

• ✅ 完全ローカル実行 - API キー不要
• 🚀 高速翻訳 - Ollama + qwen2.5:3b
• 💰 無料 - クラウド API 不要
• 🔒 プライバシー - データは外部送信されない

🔧 セットアップ

1. Ollama インストール

# macOS/Linux
curl -fsSL https://ollama.com/install.sh | sh

# モデルダウンロード
ollama pull qwen2.5:3b

2. Neural CLI ビルド (初回のみ)

cd ~/github/neural/src-tauri
cargo build --bin neural-cli --release

ビルド済みバイナリ: ~/github/neural/src-tauri/target/release/neural-cli

📝 使用方法

自動翻訳 (推奨)

cd ~/github/SuperClaude_Framework
make translate

実行内容:

1. neural-cli を自動インストール (~/.local/bin/)
2. README.md → README-zh.md (簡体字中国語)
3. README.md → README-ja.md (日本語)

手動翻訳

neural-cli translate README.md \
  --from English \
  --to "Simplified Chinese" \
  --output README-zh.md

neural-cli translate README.md \
  --from English \
  --to Japanese \
  --output README-ja.md

Ollama 接続確認

neural-cli health

出力例:

✅ Ollama is running at http://localhost:11434

📦 Available models:
  - qwen2.5:3b
  - llama3:latest
  - ...

⚙️ 高度な設定

カスタム Ollama URL

neural-cli translate README.md \
  --from English \
  --to Japanese \
  --output README-ja.md \
  --ollama-url http://custom-host:11434

別モデル使用

neural-cli translate README.md \
  --from English \
  --to Japanese \
  --output README-ja.md \
  --model llama3:latest

🚫 トラブルシューティング

エラー: "Failed to connect to Ollama"

原因: Ollama が起動していない

解決策:

# Ollama を起動
ollama serve

# 別ターミナルで確認
neural-cli health

エラー: "Model not found: qwen2.5:3b"

原因: モデルがダウンロードされていない

解決策:

ollama pull qwen2.5:3b

翻訳品質が低い

改善策:

1. より大きなモデルを使用:

   ollama pull qwen2.5:7b
   neural-cli translate README.md --model qwen2.5:7b ...
   

2. プロンプトを調整: neural/src-tauri/src/bin/cli.rs の translate_text 関数を編集

3. 温度パラメータを調整:

   "temperature": 0.1,  // より保守的な翻訳
   "temperature": 0.5,  // より自由な翻訳
   

📊 パフォーマンス

ファイルサイズ	翻訳時間 (qwen2.5:3b)	メモリ使用量
5KB README	~30秒	~2GB
10KB README	~1分	~2GB
20KB README	~2分	~2GB

システム要件:

• RAM: 最低4GB (推奨8GB)
• ストレージ: ~2GB (モデル用)
• CPU: Apple Silicon or x86_64

🔗 関連リンク

• Ollama Documentation
• Qwen2.5 Model
• Neural CLI Source

🎯 ワークフロー例

README 更新フロー

# 1. README.md を編集
vim README.md

# 2. 翻訳実行
make translate

# 3. 翻訳結果を確認
git diff README-zh.md README-ja.md

# 4. 必要に応じて手動調整
vim README-ja.md

# 5. コミット
git add README.md README-zh.md README-ja.md
git commit -m "docs: update README and translations"

大規模翻訳バッチ

# 複数ファイルを一括翻訳
for file in docs/*.md; do
  neural-cli translate "$file" \
    --from English \
    --to Japanese \
    --output "${file%.md}-ja.md"
done

💡 Tips

1. Ollama をバックグラウンドで常時起動:

   # macOS (LaunchAgent)
   brew services start ollama
   

2. 翻訳前にチェック:

   neural-cli health  # Ollama 接続確認
   

3. 翻訳後の品質チェック:

   • マークダウン構造が保持されているか
   • コードブロックが正しいか
   • リンクが機能するか

4. Git diff で確認:

   git diff README-ja.md | grep -E "^\+|^\-" | less