
Cách Chúng Tôi Sử Dụng OpenAI API Để Dịch Trang Web Của Mình
- Bài viết, Câu chuyện
- Hugo , OpenAI , Dịch thuật , Tự động hóa
- 19 tháng 3, 2025
- 44 min read
Giới thiệu
Khi chúng tôi bắt đầu làm cho trang web dựa trên GoHugo.io của mình trở nên đa ngôn ngữ, chúng tôi muốn có một cách hiệu quả, có thể mở rộng và tiết kiệm chi phí để tạo ra các bản dịch. Thay vì dịch từng trang một cách thủ công, chúng tôi đã tận dụng API của OpenAI để tự động hóa quy trình. Bài viết này sẽ hướng dẫn cách chúng tôi tích hợp OpenAI API với Hugo, sử dụng chủ đề HugoPlate từ Zeon Studio, để tạo ra các bản dịch nhanh chóng và chính xác.
Tại Sao Chúng Tôi Chọn OpenAI API Để Dịch Thuật
Các dịch vụ dịch thuật truyền thống thường yêu cầu nỗ lực thủ công đáng kể, và các công cụ tự động như Google Translate, mặc dù hữu ích, không phải lúc nào cũng cung cấp mức độ tùy chỉnh mà chúng tôi cần. API của OpenAI cho phép chúng tôi:
- Tự động hóa dịch thuật hàng loạt
- Tùy chỉnh phong cách dịch
- Duy trì kiểm soát tốt hơn về chất lượng
- Tích hợp liền mạch với trang web dựa trên Hugo của chúng tôi
- Đánh dấu các trang riêng lẻ để dịch lại
Quy Trình Từng Bước
1. Chuẩn Bị Trang Web Hugo
Trang web của chúng tôi đã được thiết lập sử dụng chủ đề HugoPlate, hỗ trợ chức năng đa ngôn ngữ. Bước đầu tiên là kích hoạt hỗ trợ ngôn ngữ trong tệp config/_default/languages.toml
của Hugo:
################ 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
Cấu hình này đảm bảo rằng Hugo có thể tạo ra các phiên bản ngôn ngữ riêng biệt của nội dung của chúng tôi.
2. Tự Động Hóa Dịch Thuật Với OpenAI API
Chúng tôi đã phát triển một kịch bản Bash để tự động hóa việc dịch các tệp Markdown. Kịch bản này:
- Đọc các tệp
.md
tiếng Anh từ thư mục nguồn. - Sử dụng OpenAI API để dịch văn bản trong khi vẫn giữ nguyên định dạng Markdown.
- Ghi nội dung đã dịch vào các thư mục ngôn ngữ thích hợp.
- Theo dõi trạng thái dịch thuật bằng cách sử dụng một tệp JSON.
Dưới đây là tổng quan về kịch bản của chúng tôi:
#!/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. Quản Lý Trạng Thái Dịch Thuật
Để ngăn chặn việc dịch lặp lại và theo dõi tiến trình, chúng tôi đã sử dụng một tệp JSON (translation_status.json
). Kịch bản cập nhật tệp này sau khi xử lý mỗi tài liệu, đảm bảo chỉ có nội dung mới hoặc đã cập nhật được dịch.
4. Xử Lý Lỗi Và Giới Hạn Tốc Độ API
Chúng tôi đã triển khai các lần thử lại và xử lý lỗi để xử lý các giới hạn tốc độ, sự cố API và vấn đề hạn ngạch. Kịch bản sẽ chờ trước khi thử lại nếu OpenAI API trả về lỗi như rate_limit_reached
hoặc service_unavailable
.
5. Triển Khai
Khi nội dung đã được dịch được tạo ra, chạy hugo --minify
sẽ xây dựng trang tĩnh đa ngôn ngữ, sẵn sàng để triển khai.
Thách Thức Và Giải Pháp
1. Độ Chính Xác Của Dịch Thuật
Mặc dù các bản dịch của OpenAI thường chính xác, một số thuật ngữ kỹ thuật có thể cần xem xét thủ công, nhưng chúng tôi chỉ là một đội ngũ hai người, vì vậy chúng tôi hy vọng vào điều tốt đẹp nhất. Chúng tôi đã điều chỉnh các lời nhắc để duy trì ngữ cảnh và tông giọng.
2. Vấn Đề Định Dạng
Cú pháp Markdown đôi khi bị thay đổi trong quá trình dịch. Để khắc phục điều này, chúng tôi đã thêm logic xử lý sau để bảo tồn định dạng.
3. Tối Ưu Chi Phí API
Để giảm chi phí, chúng tôi đã triển khai bộ nhớ đệm để tránh dịch lại nội dung không thay đổi.
4. Xử Lý Dịch Lại Một Cách Hiệu Quả
Để dịch lại các trang cụ thể, chúng tôi đã thêm một tham số retranslate: true
vào phần đầu. Kịch bản chỉ dịch lại các trang được đánh dấu bằng tham số này. Điều này cho phép chúng tôi cập nhật các bản dịch khi cần mà không phải dịch lại toàn bộ trang web.
Kết Luận
Bằng cách tích hợp OpenAI API với Hugo, chúng tôi đã tự động hóa việc dịch trang web của mình trong khi vẫn duy trì chất lượng và tính linh hoạt. Cách tiếp cận này đã tiết kiệm thời gian, đảm bảo tính nhất quán và cho phép chúng tôi mở rộng một cách dễ dàng. Nếu bạn đang tìm cách làm cho trang web Hugo của mình trở nên đa ngôn ngữ, API của OpenAI cung cấp một giải pháp mạnh mẽ.