翻訳が利用可能になりました - メニューからお好みの言語を選択してください。
私たちがOpenAI APIを使ってウェブサイトを翻訳した方法

私たちがOpenAI APIを使ってウェブサイトを翻訳した方法

はじめに

私たちがGoHugo.ioベースのウェブサイトを多言語化しようとしたとき、効率的でスケーラブルかつコスト効果の高い翻訳生成方法を求めていました。各ページを手動で翻訳する代わりに、OpenAIのAPIを活用してプロセスを自動化しました。この記事では、HugoPlateテーマを使用してOpenAI APIをHugoに統合し、迅速かつ正確に翻訳を生成する方法を説明します。

なぜ翻訳にOpenAI APIを選んだのか

従来の翻訳サービスは多くの手動作業を必要とし、Google翻訳のような自動化ツールは便利ですが、私たちが必要とするカスタマイズのレベルを常に提供するわけではありません。OpenAIのAPIを使用することで、私たちは以下のことが可能になりました：

  • 大量の翻訳を自動化する
  • 翻訳スタイルをカスタマイズする
  • 品質をより良く管理する
  • Hugoベースのサイトとシームレスに統合する
  • 再翻訳が必要な個別ページをフラグ付けする

ステップバイステップのプロセス

1. Hugoウェブサイトの準備

私たちのサイトはすでにHugoPlateテーマを使用して設定されており、多言語機能をサポートしています。最初のステップは、Hugoのconfig/_default/languages.tomlファイルで言語サポートを有効にすることでした：

################ English language ##################
[en]
languageName = "English"
languageCode = "en-us"
contentDir = "content/english"
weight = 1

################ Arabic language ##################
[ar]
languageName = "العربية"
languageCode = "ar"
contentDir = "content/arabic"
languageDirection = 'rtl'
weight = 2

この設定により、Hugoはコンテンツの別々の言語バージョンを生成できるようになります。

2. OpenAI APIを使った翻訳の自動化

私たちはMarkdownファイルの翻訳を自動化するためにBashスクリプトを開発しました。このスクリプトは：

  • ソースディレクトリから英語の.mdファイルを読み取ります。
  • Markdownのフォーマットを保持しながらテキストを翻訳するためにOpenAI APIを使用します。
  • 翻訳されたコンテンツを適切な言語ディレクトリに書き込みます。
  • JSONファイルを使用して翻訳の状態を追跡します。

こちらが私たちのスクリプトの概要です：

#!/bin/bash
# ===========================================
# Hugo Content Translation and Update Script (Sequential Processing & New-Language Cleanup)
# ===========================================
# This script translates Hugo Markdown (.md) files from English to all supported target languages
# sequentially (one file at a time). It updates a JSON status file after processing each file.
# At the end of the run, it checks translation_status.json and removes any language from
# translate_new_language.txt only if every file for that language is marked as "success".
# ===========================================

set -euo pipefail

# --- Simple Logging Function (writes to stderr) ---
log_step() {
    echo "[$(date '+%Y-%m-%d %H:%M:%S')] $*" >&2
}

# --- Environment Setup ---
export PATH="/opt/homebrew/opt/coreutils/libexec/gnubin:$PATH"
# (Removed "Script starting." log)

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
log_step "SCRIPT_DIR set to: $SCRIPT_DIR"

if [ -f "$SCRIPT_DIR/.env" ]; then
    log_step "Loading environment variables from .env"
    set -o allexport
    source "$SCRIPT_DIR/.env"
    set +o allexport
fi

# Load new languages from translate_new_language.txt (if available)
declare -a NEW_LANGUAGES=()
if [ -f "$SCRIPT_DIR/translate_new_language.txt" ]; then
    while IFS= read -r line || [[ -n "$line" ]]; do
        NEW_LANGUAGES+=("$line")
    done <"$SCRIPT_DIR/translate_new_language.txt"
else
    log_step "No new languages file found; proceeding with empty NEW_LANGUAGES."
fi

API_KEY="${OPENAI_API_KEY:-}"
if [ -z "$API_KEY" ]; then
    log_step "❌ Error: OPENAI_API_KEY environment variable is not set."
    exit 1
fi

# Supported Languages (full list)
SUPPORTED_LANGUAGES=("ar" "bg" "bn" "cs" "da" "de" "el" "es" "fa" "fi" "fr" "ha" "he" "hi" "hr" "hu" "id" "ig" "it" "ja" "ko" "ml" "mr" "ms" "nl" "no" "pa" "pl" "pt" "ro" "ru" "sk" "sn" "so" "sr" "sv" "sw" "ta" "te" "th" "tl" "tr" "uk" "vi" "xh" "yo" "zh" "zu")

STATUS_FILE="$SCRIPT_DIR/translation_status.json"
SRC_DIR="$SCRIPT_DIR/Content/english"
log_step "Source directory: $SRC_DIR"

# Check dependencies
for cmd in jq curl; do
    if ! command -v "$cmd" >/dev/null 2>&1; then
        log_step "❌ Error: '$cmd' is required. Please install it."
        exit 1
    fi
done

MAX_RETRIES=5
WAIT_TIME=2 # seconds

# Create/initialize status file if missing
if [ ! -f "$STATUS_FILE" ]; then
    echo "{}" >"$STATUS_FILE"
    log_step "Initialized status file at: $STATUS_FILE"
fi

# --- Locking for Status Updates ---
lock_status() {
    local max_wait=10
    local start_time
    start_time=$(date +%s)
    while ! mkdir "$STATUS_FILE.lockdir" 2>/dev/null; do
        sleep 0.01
        local now
        now=$(date +%s)
        if ((now - start_time >= max_wait)); then
            log_step "WARNING: Lock wait exceeded ${max_wait}s. Forcibly removing stale lock."
            rm -rf "$STATUS_FILE.lockdir"
        fi
    done
}

unlock_status() {
    rmdir "$STATUS_FILE.lockdir"
}

update_status() {
    local file_path="$1" lang="$2" status="$3"
    lock_status
    jq --arg file "$file_path" --arg lang "$lang" --arg status "$status" \
        '.[$file][$lang] = $status' "$STATUS_FILE" >"$STATUS_FILE.tmp" && mv "$STATUS_FILE.tmp" "$STATUS_FILE"
    unlock_status
}

# --- Translation Function ---
translate_text() {
    local text="$1" lang="$2"
    local retry_count=0
    while [ "$retry_count" -lt "$MAX_RETRIES" ]; do
        user_message="Translate the following text to $lang. Preserve all formatting exactly as in the original.
$text"
        json_payload=$(jq -n \
            --arg system "Translate from English to $lang. Preserve original formatting exactly." \
            --arg user_message "$user_message" \
            '{
                "model": "gpt-4o-mini",
                "messages": [
                    {"role": "system", "content": $system},
                    {"role": "user", "content": $user_message}
                ],
                "temperature": 0.3
            }')
        response=$(curl -s https://api.openai.com/v1/chat/completions \
            -H "Content-Type: application/json" \
            -H "Authorization: Bearer $API_KEY" \
            -d "$json_payload")
        log_step "📥 Received API response."
        local error_type
        error_type=$(echo "$response" | jq -r '.error.type // empty')
        local error_message
        error_message=$(echo "$response" | jq -r '.error.message // empty')
        if [ "$error_type" == "insufficient_quota" ]; then
            sleep "$WAIT_TIME"
            retry_count=$((retry_count + 1))
        elif [[ "$error_type" == "rate_limit_reached" || "$error_type" == "server_error" || "$error_type" == "service_unavailable" ]]; then
            sleep "$WAIT_TIME"
            retry_count=$((retry_count + 1))
        elif [ "$error_type" == "invalid_request_error" ]; then
            return 1
        elif [ -z "$error_type" ]; then
            if ! translated_text=$(echo "$response" | jq -r '.choices[0].message.content' 2>/dev/null); then
                return 1
            fi
            if [ "$translated_text" == "null" ] || [ -z "$translated_text" ]; then
                return 1
            else
                translated_text=$(echo "$translated_text" | sed -e 's/^```[[:space:]]*//; s/[[:space:]]*```$//')
                echo "$translated_text"
                return 0
            fi
        else
            return 1
        fi
    done
    return 1
}

# --- Process a Single File (Sequential Version) ---
process_file() {
    local src_file="$1" target_file="$2" lang="$3" rel_src="$4"
    # If target file exists and is non-empty, mark status as success.
    if [ -s "$target_file" ]; then
        update_status "$rel_src" "$lang" "success"
        return 0
    fi
    content=$(<"$src_file")
    if [[ "$content" =~ ^(---|\+\+\+)[[:space:]]*$ ]] && [[ "$content" =~ [[:space:]]*(---|\+\+\+\+)[[:space:]]*$ ]]; then
        front_matter=$(echo "$content" | sed -n '/^\(---\|\+\+\+\)$/,/^\(---\|\+\+\+\)$/p')
        body_content=$(echo "$content" | sed -n '/^\(---\|\+\+\+\)$/,/^\(---\|\+\+\+\)$/d')
    else
        front_matter=""
        body_content="$content"
    fi
    log_step "Translating [$rel_src] to $lang..."
    translated_body=$(translate_text "$body_content" "$lang")
    if [ $? -ne 0 ]; then
        update_status "$rel_src" "$lang" "failed"
        return 1
    fi
    mkdir -p "$(dirname "$target_file")"
    if [ -n "$front_matter" ]; then
        echo -e "$front_matter
$translated_body" >"$target_file"
    else
        echo -e "$translated_body" >"$target_file"
    fi
    updated_content=$(echo "$content" | sed -E 's/^retranslate:\s*true/retranslate: false/')
    echo "$updated_content" >"$src_file"
    update_status "$rel_src" "$lang" "success"
}

# --- Main Sequential Processing ---
ALL_SUCCESS=true
for TARGET_LANG in "${SUPPORTED_LANGUAGES[@]}"; do
    log_step "Processing language: $TARGET_LANG"
    TARGET_DIR="$SCRIPT_DIR/Content/$TARGET_LANG"
    while IFS= read -r -d '' src_file; do
        rel_src="${src_file#$SCRIPT_DIR/}"
        target_file="$TARGET_DIR/${src_file#$SRC_DIR/}"
        # If file is marked not to retranslate, check that target file exists and is non-empty.
        if ! [[ " ${NEW_LANGUAGES[@]:-} " =~ " ${TARGET_LANG} " ]] && grep -q '^retranslate:\s*false' "$src_file"; then
            if [ -s "$target_file" ]; then
                update_status "$rel_src" "$TARGET_LANG" "success"
            else
                update_status "$rel_src" "$TARGET_LANG" "failed"
            fi
            continue
        fi
        process_file "$src_file" "$target_file" "$TARGET_LANG" "$rel_src"
    done < <(find "$SRC_DIR" -type f -name "*.md" -print0)
done

log_step "Translation run completed."
end_time=$(date +%s)
duration=$((end_time - $(date +%s)))
log_step "Execution Time: $duration seconds"

if [ "$ALL_SUCCESS" = true ]; then
    log_step "🎉 Translation completed successfully for all supported languages!"
else
    log_step "⚠️ Translation completed with some errors."
fi

# --- Clean Up Fully Translated New Languages ---
if [ -f "$SCRIPT_DIR/translate_new_language.txt" ]; then
    log_step "Cleaning up fully translated new languages..."
    for lang in "${NEW_LANGUAGES[@]:-}"; do
        incomplete=$(jq --arg lang "$lang" 'to_entries[] | select(.value[$lang] != null and (.value[$lang] != "success")) | .key' "$STATUS_FILE")
        if [ -z "$incomplete" ]; then
            log_step "All translations for new language '$lang' are marked as success. Removing from translate_new_language.txt."
            sed -E -i '' "/^[[:space:]]*$lang[[:space:]]*$/d" "$SCRIPT_DIR/translate_new_language.txt"
        else
            log_step "Language '$lang' still has incomplete translations."
        fi
    done
fi

3. 翻訳状態の管理

冗長な翻訳を防ぎ、進捗を追跡するために、JSONファイル（translation_status.json）を使用しました。スクリプトは各ドキュメントを処理した後にこのファイルを更新し、新しいまたは更新されたコンテンツのみが翻訳されるようにします。

4. エラーハンドリングとAPIのレート制限

レート制限、APIの失敗、クォータの問題に対処するために、再試行とエラーハンドリングを実装しました。OpenAI APIがrate_limit_reachedやservice_unavailableのようなエラーを返した場合、スクリプトは再試行する前に待機します。

5. デプロイメント

翻訳されたコンテンツが生成されたら、hugo --minifyを実行して多言語の静的サイトを構築し、デプロイの準備を整えます。

課題と解決策

1. 翻訳の正確性

OpenAIの翻訳は一般的に正確でしたが、一部の技術用語は手動での確認が必要な場合がありますが、私たちは2人のチームなので、最善を尽くすことを期待しています。文脈とトーンを維持するためにプロンプトを微調整しました。

2. フォーマットの問題

Markdownの構文が翻訳中に変更されることがありました。これを修正するために、フォーマットを保持するための後処理ロジックを追加しました。

3. APIコストの最適化

コストを削減するために、変更されていないコンテンツの再翻訳を避けるためにキャッシュを実装しました。

4. 再翻訳の効率的な処理

特定のページを再翻訳するために、retranslate: trueというフロントマターのパラメータを追加しました。スクリプトはこのパラメータでマークされたページのみを再翻訳します。これにより、サイト全体を再翻訳することなく、必要に応じて翻訳を更新できます。

結論

OpenAI APIをHugoに統合することで、私たちはウェブサイトの翻訳を自動化し、品質と柔軟性を維持しました。このアプローチは時間を節約し、一貫性を確保し、スケールを容易にしました。Hugoサイトを多言語化したい場合、OpenAIのAPIは強力なソリューションを提供します。

Share This Page:

関連記事

翻訳によるアクセスの拡大

翻訳によるアクセスの拡大

私たちは、私たちの翻訳があなたの期待に応えられない場合があることを心からお詫び申し上げます。EVnStevenでは、できるだけ多くの人々に私たちのコンテンツをアクセス可能にすることにコミットしており、そのために複数の言語での翻訳を可能にしています。しかし、AI生成の翻訳が常にすべてのニュアンスを正確に捉えるわけではないことを理解しており、内容が不適切または不明瞭に感じられる場合にはお詫び申し上げます。

私たちの翻訳はAIツールを通じて行われているため、すべての言語で各記事を個別に更新するリソースはありません。その代わりに、AI翻訳ツールの改善に伴い、定期的にライブラリ全体を再翻訳する計画です。それまでの間、一部の翻訳が完全に正確でない場合には、あなたの忍耐と理解に心から感謝いたします。

なぜ私たちが単にオンデマンドのブラウザ翻訳を許可するのではなく、ウェブサイト全体を事前に翻訳しているのか不思議に思うかもしれません。これらの事前翻訳されたページを提供することで、Googleや他の検索エンジンが各言語版をインデックスできるようになります。これにより、母国語で検索した際に私たちを見つけやすくなり、より効果的にグローバルなオーディエンスとつながることができます。

翻訳が不適切に思われる場合にのみ、即座に変更を行います。私たち自身でこれをチェックする完璧な方法がないため、あなたの助けを歓迎します。不適切または攻撃的に感じられる言語に出くわした場合は、website.translations@evnsteven.appまでお知らせください。あなたのフィードバックにより、私たちのコンテンツがすべての人に対して敬意を持ち、アクセス可能であり続けることが保証されます。

より包括的なグローバルコミュニティに向けて努力している間、あなたの理解に感謝いたします！


続きを読む