19 tháng 3, 2025
Cách Chúng Tôi Cung Cấp 50 Ngôn Ngữ
Khi chúng tôi bắt đầu làm cho trang web dựa trên GoHugo.io của mình đa ngôn ngữ, chúng tôi muốn một phương pháp 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 thủ công từng trang, 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 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 bản dịch nhanh chóng và chính xác.
Tại Sao Chúng Tôi Chọn OpenAI API Cho Việc Dịch Thuật
Các dịch vụ dịch thuật truyền thống thường đòi hỏi nhiều công sức thủ công, 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 dịch hàng loạt
- Tùy chỉnh phong cách dịch
- Duy trì kiểm soát chất lượng tốt hơn
- 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 từng trang để dịch lại
- Thêm ngôn ngữ mới với ít nỗ lực
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 cấu hình Hugo config/_default/languages.toml của chúng tôi:
```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
```
Cấu hình này đảm bảo Hugo có thể tạo ra các phiên bản nội dung riêng biệt theo từng ngôn ngữ.
2. Tự Động Hóa Dịch Thuật Với OpenAI API
Chúng tôi phát triển một script Bash để tự động dịch các tệp Markdown. Script này:
- Đọc các tệp
.mdtiếng Anh từ thư mục nguồn. - Sử dụng OpenAI API để dịch văn bản trong khi giữ nguyên định dạng Markdown.
- Ghi nội dung dịch vào các thư mục ngôn ngữ tương ứng.
- Theo dõi trạng thái dịch bằng một tệp JSON.
Dưới đây là script bash của chúng tôi để tự động dịch. Bạn có thể sử dụng và chỉnh sửa theo nhu cầu của mình:
```bash
# MIT License
# Copyright (c) 2024 Williston Technical Inc.
#
# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to deal
# in the Software without restriction, including without limitation the rights
# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
# copies of the Software, and to permit persons to whom the Software is
# furnished to do so, subject to the following conditions:
#
# The above copyright notice and this permission notice shall be included in all
# copies or substantial portions of the Software.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
# SOFTWARE.
#!/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
Để tránh dịch trùng lặp và theo dõi tiến độ, chúng tôi sử dụng một tệp JSON (translation_status.json). Script cập nhật tệp này sau khi xử lý mỗi tài liệu, đảm bảo chỉ dịch các nội dung mới hoặc đã được cập nhật.
4. Xử Lý Lỗi và Giới Hạn Tốc Độ API
Chúng tôi triển khai cơ chế thử lại và xử lý lỗi để đối phó với giới hạn tốc độ, lỗi API và vấn đề hạn ngạch. Script 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 dịch đã được tạo, chạy lệnh hugo --minify sẽ xây dựng trang web 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 Dịch Thuật
Mặc dù các bản dịch của OpenAI nhìn chung chính xác, một số thuật ngữ kỹ thuật có thể cần được xem xét thủ công, nhưng chúng tôi chỉ là một nhóm hai người, nên hy vọng kết quả tốt nhất. Chúng tôi đã tinh chỉnh các prompt để giữ nguyên ngữ cảnh và giọng điệu.
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, chúng tôi thêm logic xử lý hậu kỳ để giữ nguyên định dạng.
3. Tối Ưu Chi Phí API
Để giảm chi phí, chúng tôi thực hiện bộ nhớ đệm để tránh dịch lại các nội dung không thay đổi.
4. Xử Lý Việc Dịch Lại Hiệu Quả
Để dịch lại các trang cụ thể, chúng tôi thêm tham số retranslate: true trong front matter. Script chỉ dịch lại các trang được đánh dấu tham số này. Điều này cho phép chúng tôi cập nhật 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 trong khi vẫn duy trì chất lượng và sự linh hoạt. Phương pháp này giúp tiết kiệm thời gian, đảm bảo sự nhất quán và cho phép mở rộng dễ dàng. Nếu bạn muốn làm cho trang Hugo của mình đa ngôn ngữ, API của OpenAI là một giải pháp mạnh mẽ.