Upload project files

README.md

@@ -1,14 +1,10 @@
 ---
-title: Hf Transformers Docs I18n Agent
-emoji: ⚡
-colorFrom: green
-colorTo: red
+title: I18n Agent
+emoji: 🤖
+colorFrom: blue
+colorTo: green
 sdk: gradio
-sdk_version: 5.33.1
+sdk_version: "5.33.0"
 app_file: app.py
 pinned: false
-license: apache-2.0
-short_description: Translation agent for Hugging Face Transformers docs
 ---
-
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference

agent/handler.py

@@ -0,0 +1,386 @@
+"""Module for gradio chat-based translation agent interface."""
+
+import os
+import re
+from pathlib import Path
+
+import gradio as gr
+
+from agent.workflow import (
+    report_translation_target_files,
+    translate_docs_interactive,
+    generate_github_pr,
+)
+from pr_generator.searcher import find_reference_pr_simple_stream
+
+
+# State management
+class ChatState:
+    def __init__(self):
+        self.step = "welcome"  # welcome -> find_files -> translate -> create_github_pr
+        self.target_language = "ko"
+        self.k_files = 10
+        self.files_to_translate = []
+        self.current_file_content = {"translated": ""}
+        self.pr_result = None  # Store PR creation result
+        # GitHub configuration
+        self.github_config = {
+            "token": "",
+            "owner": "",
+            "repo_name": "",
+            "reference_pr_url": "https://github.com/huggingface/transformers/pull/24968",
+        }
+
+
+state = ChatState()
+
+
+def _extract_content_for_display(content: str) -> str:
+    """Extract text from document for display."""
+    # Remove Copyright header
+    to_translate = re.sub(r"<!--.*?-->", "", content, count=1, flags=re.DOTALL)
+    to_translate = to_translate.strip()
+    ## remove code blocks from text
+    to_translate = re.sub(r"```.*?```", "", to_translate, flags=re.DOTALL)
+    ## remove markdown tables from text
+    to_translate = re.sub(r"^\|.*\|$\n?", "", to_translate, flags=re.MULTILINE)
+    ## remove empty lines from text
+    to_translate = re.sub(r"\n\n+", "\n\n", to_translate)
+
+    return to_translate
+
+
+def get_welcome_message():
+    """Initial welcome message with file finding controls"""
+    return """**👋 Welcome to 🌐 Hugging Face i18n Translation Agent!**
+
+I'll help you find files that need translation and translate them in a streamlined workflow.
+
+**🔎 Let's start by finding files that need translation.**
+
+Use the **`Quick Controls`** on the right or **ask me `what`, `how`, or `help`** to get started.
+"""
+
+
+def process_file_search_handler(lang: str, k: int, history: list) -> tuple:
+    """Process file search request and update Gradio UI components."""
+    global state
+    state.target_language = lang
+    state.k_files = k
+    state.step = "find_files"
+
+    status_report, files_list = report_translation_target_files(lang, k)
+    state.files_to_translate = [file[0] for file in files_list] if files_list else []
+
+    response = f"""**✅ File search completed!**
+
+**Status Report:**
+{status_report}
+
+**📁 Found first {len(state.files_to_translate)} files to translate:**
+"""
+
+    if state.files_to_translate:
+        for i, file in enumerate(state.files_to_translate[:5], 1):  # Show first 5
+            response += f"\n{i}. `{file}`"
+
+        if len(state.files_to_translate) > 5:
+            response += f"\n... and {len(state.files_to_translate) - 5} more files"
+
+        response += "\n\n**🚀 Ready to start translation?**\nI can begin translating these files one by one. Would you like to proceed?"
+    else:
+        response += "\nNo files found that need translation."
+
+    # Add to history
+    history.append(["Please find files that need translation", response])
+    cleared_input = ""
+    selected_tab = 1 if state.files_to_translate else 0
+
+    return history, cleared_input, update_status(), gr.Tabs(selected=selected_tab)
+
+
+def start_translation_process():
+    """Start the translation process for the first file"""
+    if not state.files_to_translate:
+        return "❌ No files available for translation."
+
+    current_file = state.files_to_translate[0]
+
+    # Call translation function (simplified for demo)
+    try:
+        status, translated = translate_docs_interactive(
+            state.target_language, [[current_file]]
+        )
+
+        state.current_file_content = {"translated": translated}
+        path = (
+            Path(__file__).resolve().parent.parent
+            / f"translation_result/{current_file}"
+        )
+        p = Path(path)
+        p.parent.mkdir(parents=True, exist_ok=True)
+        p.write_text(translated, encoding="utf-8")
+
+        original_file_link = (
+            "https://github.com/huggingface/transformers/blob/main/" + current_file
+        )
+        response = (
+            f"""🔄 Translation for: `{current_file}`**\n"""
+            "**📄 Original Content Link:**\n"
+            ""
+            f"{original_file_link}\n"
+            "**🌐 Translated Content:**\n"
+            f"\n```\n\n{_extract_content_for_display(translated)}```\n"
+            f"{status}\n"
+        )
+        print("translated:")
+        print(translated)
+        print("extracted")
+
+    except Exception as e:
+        response = f"❌ Translation failed: {str(e)}"
+        response += "\n**➡️ Please try from the beginning.**"
+
+    return response
+
+
+def handle_general_message(message):
+    """Handle general messages"""
+    message_lower = message.lower()
+
+    if any(word in message_lower for word in ["help", "what", "how"]):
+        return """**🤖 I'm your Hugging Face i18n Translation Agent!**
+
+I can help you:
+1. **🔍 Find files** that need translation
+2. **🌐 Translate documents** using AI
+3. **📋 Review translations** for quality
+4. **🚀 Create GitHub PR** for translation
+
+Currently available actions with quick controls:
+- "find files" - Search for files needing translation
+- "translate" - Start translation process  
+- "review" - Review current translation
+- "github" - Create GitHub Pull Request
+- "restart" - Start over"""
+
+    elif "restart" in message_lower:
+        global state
+        state = ChatState()
+        return get_welcome_message()
+
+    else:
+        return """I understand you want to work on translations! 
+
+To get started, please use the controls above to configure your translation settings and find files that need translation.
+"""
+
+
+# Main handler
+def handle_user_message(message, history):
+    """Handle user messages and provide appropriate responses"""
+    global state
+
+    if not message.strip():
+        return history, ""
+
+    elif state.step == "find_files" and any(
+        word in message.lower()
+        for word in ["yes", "proceed", "start", "translate", "translation"]
+    ):
+        # User wants to start translation
+        if state.files_to_translate:
+            state.step = "translate"
+            response = start_translation_process()
+        else:
+            response = (
+                "❌ No files available for translation. Please search for files first."
+            )
+
+    # Handle GitHub PR creation - This part is removed as approve_handler is the main entry point
+    else:
+        # General response
+        response = handle_general_message(message)
+
+    history.append([message, response])
+    return history, ""
+
+
+def update_status():
+    if state.step == "welcome":
+        return """
+        <div style="display: grid; grid-template-columns: 1fr 1fr; gap: 10px;padding: 10px; background: rgba(0, 0, 0, 0.25); border-radius: 8px;">
+            <div><strong>🔄 Step:</strong> Welcome</div>
+            <div><strong>📁 Files:</strong> 0</div>
+            <div><strong>🌍 Language:</strong> ko</div>
+            <div><strong>⏳ Progress:</strong> Ready</div>
+        </div>
+        """
+
+    step_map = {
+        "welcome": "Welcome",
+        "find_files": "Finding Files",
+        "translate": "Translating",
+        "review": "Reviewing",
+        "create_github_pr": "Creating PR",
+    }
+
+    progress_map = {
+        "welcome": "Ready to start",
+        "find_files": "Files found",
+        "translate": f"{len(state.files_to_translate)} remaining",
+        "review": "Review complete",
+        "create_github_pr": "PR generation in progress",
+    }
+
+    # Check GitHub configuration status
+    github_status = "❌ Not configured"
+    if all(
+        [
+            state.github_config["token"],
+            state.github_config["owner"],
+            state.github_config["repo_name"],
+        ]
+    ):
+        github_status = (
+            f"✅ {state.github_config['owner']}/{state.github_config['repo_name']}"
+        )
+
+    status_html = f"""
+    <div style="display: grid; grid-template-columns: 1fr 1fr; gap: 10px; padding: 10px; background: rgba(0, 0, 0, 0.25); border-radius: 8px;">
+        <div><strong>🔄 Step:</strong> {step_map.get(state.step, state.step)}</div>
+        <div><strong>📁 Files:</strong> {len(state.files_to_translate)}</div>
+        <div><strong>🌍 Language:</strong> {state.target_language}</div>
+        <div><strong>⏳ Progress:</strong> {progress_map.get(state.step, 'In progress')}</div>
+        <div><strong>🔧 GitHub:</strong> {github_status}</div>
+    </div>
+    """
+
+    return status_html
+
+
+# Event handlers
+
+
+def sync_language_displays(lang):
+    return lang
+
+
+def update_github_config(token, owner, repo, reference_pr_url):
+    """Update GitHub configuration settings."""
+    global state
+
+    # Set GitHub token in environment variables
+    if token:
+        os.environ["GITHUB_TOKEN"] = token
+
+    # Save GitHub configuration to state
+    state.github_config.update(
+        {
+            "token": token,
+            "owner": owner,
+            "repo_name": repo,
+            "reference_pr_url": reference_pr_url
+            or state.github_config["reference_pr_url"],
+        }
+    )
+
+    return f"✅ GitHub configuration updated: {owner}/{repo}"
+
+
+def send_message(message, history):
+    new_history, cleared_input = handle_user_message(message, history)
+    return new_history, cleared_input, update_status()
+
+
+# Button handlers with tab switching
+def start_translate_handler(history, anthropic_key):
+    os.environ["ANTHROPIC_API_KEY"] = anthropic_key
+    new_hist, cleared_input = handle_user_message("start translation", history)
+    selected_tabs = 2 if state.current_file_content["translated"] else 0
+    return new_hist, cleared_input, update_status(), gr.Tabs(selected=selected_tabs)
+
+
+def approve_handler(history, owner, repo, reference_pr_url):
+    """Handles the request to generate a GitHub PR."""
+    global state
+    state.step = "create_github_pr"
+
+    # Update github config from the latest UI values
+    state.github_config["owner"] = owner
+    state.github_config["repo_name"] = repo
+    state.github_config["reference_pr_url"] = reference_pr_url
+
+    # Validate GitHub configuration
+    github_config = state.github_config
+    if not all([github_config.get("token"), owner, repo]):
+        response = "❌ GitHub configuration incomplete. Please provide GitHub Token, Owner, and Repository Name in Tab 3."
+        history.append(["GitHub PR creation request", response])
+        return history, "", update_status()
+
+    # If reference PR is not provided, use the agent to find one
+    if not github_config.get("reference_pr_url"):
+        response = "🤖 **Reference PR URL not found. The agent will now search for a suitable one...**"
+        try:
+            # This part is simplified to avoid streaming logic in a non-generator function
+            stream_gen = find_reference_pr_simple_stream(
+                target_language=state.target_language,
+                context="documentation translation",
+            )
+            # We will just get the final result from the generator
+            final_result = None
+            try:
+                while True:
+                    # We are not interested in the streamed messages here, just the final result.
+                    next(stream_gen)
+            except StopIteration as e:
+                final_result = e.value
+
+            if final_result and final_result.get("status") == "success":
+                result_text = final_result.get("result", "")
+                match = re.search(r"https://github.com/[^\s]+", result_text)
+                if match:
+                    found_url = match.group(0)
+                    state.github_config["reference_pr_url"] = found_url
+                    response += f"\n✅ **Agent found a reference PR:** {found_url}"
+                else:
+                    raise ValueError(
+                        "Could not extract a valid PR URL from agent's response."
+                    )
+            else:
+                error_message = final_result.get("message") or final_result.get(
+                    "result", "Unknown error"
+                )
+                raise ValueError(f"Agent failed to find a PR. Reason: {error_message}")
+        except Exception as e:
+            response += f"\n❌ **Agent failed to find a reference PR.**\nReason: {e}\n\nPlease provide a reference PR URL manually in Tab 3 and try again."
+            history.append(["Agent searching for PR", response])
+            return history, "", update_status()
+
+    # Proceed with PR generation
+    if state.files_to_translate and state.current_file_content.get("translated"):
+        current_file = state.files_to_translate[0]
+        translated_content = state.current_file_content["translated"]
+        response += "\n\n🚀 **Generating GitHub PR...**"
+
+        pr_response = generate_github_pr(
+            target_language=state.target_language,
+            filepath=current_file,
+            translated_content=translated_content,
+            github_config=state.github_config,
+        )
+        response += f"\n{pr_response}"
+    else:
+        response = "❌ No translated file available. Please complete the translation process first."
+
+    history.append(["GitHub PR creation request", response])
+    return history, "", update_status()
+
+
+def restart_handler(history):
+    """Resets the state and UI."""
+    global state
+    state = ChatState()
+    welcome_msg = get_welcome_message()
+    new_hist = [[None, welcome_msg]]
+    return new_hist, "", update_status(), gr.Tabs(selected=0)

agent/workflow.py

@@ -0,0 +1,205 @@
+"""Module for gradio interfaces."""
+
+import os
+from pathlib import Path
+import gradio as gr
+
+from translator.content import (
+    fill_scaffold,
+    get_content,
+    get_full_prompt,
+    llm_translate,
+    preprocess_content,
+)
+from translator.retriever import report
+
+# GitHub PR Agent import
+try:
+    from pr_generator.agent import GitHubPRAgent
+
+    GITHUB_PR_AVAILABLE = True
+except ImportError as e:
+    print(f"⚠️ GitHub PR Agent is not available: {e}")
+    GITHUB_PR_AVAILABLE = False
+
+# GitHub configuration - must be provided by user or environment variables
+
+
+def report_translation_target_files(
+    translate_lang: str, top_k: int = 1
+) -> tuple[str, list[list[str]]]:
+    """Return the top-k files that need translation.
+
+    Args:
+        translate_lang: Target language to translate
+        top_k: Number of top-first files to return for translation. (Default 1)
+    """
+    status_report, filepath_list = report(translate_lang, top_k)
+    return status_report, [[file] for file in filepath_list]
+
+
+def translate_docs(lang: str, file_path: str) -> tuple[str, str]:
+    """Translate documentation."""
+    # step 1. Get content from file path
+    content = get_content(file_path)
+    to_translate = preprocess_content(content)
+
+    # step 2. Prepare prompt with docs content
+    if lang == "ko":
+        translation_lang = "Korean"
+    to_translate_with_prompt = get_full_prompt(translation_lang, to_translate)
+
+    # step 3. Translate with LLM
+    # TODO: MCP clilent 넘길 부분
+    callback_result, translated_content = llm_translate(to_translate_with_prompt)
+
+    # step 4. Add scaffold to translation result
+    translated_doc = fill_scaffold(content, to_translate, translated_content)
+
+    return callback_result, translated_doc
+
+
+def translate_docs_interactive(
+    translate_lang: str, selected_files: list[list[str]]
+) -> tuple[str, str, str]:
+    """Interactive translation function that processes files one by one.
+
+    Args:
+        translate_lang: Target language to translate
+        selected_files: List of file paths to translate
+    """
+    # Extract file paths from the dataframe format
+    file_paths = [row[0] for row in selected_files if row and len(row) > 0]
+    if not file_paths:
+        return (
+            "No files selected for translation.",
+            gr.update(visible=False),
+            gr.update(visible=False),
+            gr.update(visible=False),
+            [],
+            0,
+        )
+
+    # Start with the first file
+    current_file = file_paths[0]
+
+    status = f"✅ Translation completed: `{current_file}` → `{translate_lang}`\n\n"
+    callback_result, translated_content = translate_docs(translate_lang, current_file)
+    status += f"💰 Used token and cost: \n```\n{callback_result}\n```"
+
+    if len(file_paths) > 1:
+        status += f"\n### 📝 Note: Currently, only the first file has been translated.\n> The remaining {len(file_paths) - 1} files have not been processed yet, as the system is in its beta version"
+
+    return status, translated_content
+
+
+def generate_github_pr(
+    target_language: str,
+    filepath: str,
+    translated_content: str = None,
+    github_config: dict = None,
+) -> str:
+    """Generate a GitHub PR for translated documentation.
+
+    Args:
+        target_language: Target language for translation (e.g., "ko")
+        filepath: Original file path (e.g., "docs/source/en/accelerator_selection.md")
+        translated_content: Translated content (if None, read from file)
+        github_config: GitHub configuration dictionary
+
+    Returns:
+        PR creation result message
+    """
+    if not GITHUB_PR_AVAILABLE:
+        return "❌ GitHub PR Agent is not available. Please install required libraries."
+
+    if not github_config:
+        return "❌ GitHub configuration not provided."
+
+    # Validate required configuration
+    required_fields = ["token", "owner", "repo_name", "reference_pr_url"]
+    missing_fields = [
+        field for field in required_fields if not github_config.get(field)
+    ]
+
+    if missing_fields:
+        return f"❌ Missing required configuration: {', '.join(missing_fields)}. Please provide these values."
+
+    # Set token in environment for the agent.
+    os.environ["GITHUB_TOKEN"] = github_config["token"]
+
+    try:
+        # Read translated content from file if not provided
+        if translated_content is None:
+            translation_file_path = (
+                Path(__file__).resolve().parent.parent
+                / f"translation_result/{filepath}"
+            )
+            if not translation_file_path.exists():
+                return f"❌ Translation file not found: {translation_file_path}"
+
+            with open(translation_file_path, "r", encoding="utf-8") as f:
+                translated_content = f.read()
+
+        if not translated_content or not translated_content.strip():
+            return "❌ Translated content is empty."
+
+        # Execute GitHub PR Agent
+        print(f"🚀 Starting GitHub PR creation...")
+        print(f"   📁 File: {filepath}")
+        print(f"   🌍 Language: {target_language}")
+        print(f"   📊 Reference PR: {github_config['reference_pr_url']}")
+        print(
+            f"   🏠 Repository: {github_config['owner']}/{github_config['repo_name']}"
+        )
+
+        agent = GitHubPRAgent()
+        result = agent.run_translation_pr_workflow(
+            reference_pr_url=github_config["reference_pr_url"],
+            target_language=target_language,
+            filepath=filepath,
+            translated_doc=translated_content,
+            owner=github_config["owner"],
+            repo_name=github_config["repo_name"],
+            base_branch=github_config.get("base_branch", "main"),
+        )
+
+        # Process result
+        if result["status"] == "success":
+            return f"""✅ **GitHub PR Creation Successful!**
+
+🔗 **PR URL:** {result["pr_url"]}
+🌿 **Branch:** {result["branch"]}
+📁 **File:** {result["file_path"]}
+
+{result["message"]}"""
+
+        elif result["status"] == "partial_success":
+            return f"""⚠️ **Partial Success**
+
+🌿 **Branch:** {result["branch"]}
+📁 **File:** {result["file_path"]}
+
+{result["message"]}
+
+**Error Details:**
+{result.get("error_details", "Unknown error")}"""
+
+        else:
+            return f"""❌ **GitHub PR Creation Failed**
+
+**Error Message:**
+{result["message"]}"""
+
+    except Exception as e:
+        error_msg = f"❌ Unexpected error occurred during PR creation: {str(e)}"
+        print(error_msg)
+        return error_msg
+
+
+# Backward compatibility function (replaces old mock function)
+def mock_generate_PR():
+    """Backward compatibility function - returns warning message only"""
+    return (
+        "⚠️ mock_generate_PR() is deprecated. Please use generate_github_pr() instead."
+    )

app.py

@@ -0,0 +1,251 @@
+"""Module for gradio chat-based translation agent interface."""
+
+import base64
+import os
+
+import gradio as gr
+from dotenv import load_dotenv
+
+from agent.handler import (
+    approve_handler,
+    get_welcome_message,
+    process_file_search_handler,
+    restart_handler,
+    send_message,
+    start_translate_handler,
+    sync_language_displays,
+    update_status,
+    update_github_config,
+)
+from translator.model import Languages
+
+load_dotenv()
+
+
+css = """
+.gradio-container {
+    background: linear-gradient(135deg, #ffeda7 0%, #ffbebf 100%);
+}
+.chat-container {
+    background: rgba(255, 255, 180, 0.25);
+    border-radius: 18px;
+    box-shadow: 0 4px 24px rgba(0,0,0,0.08);
+    padding: 1.5em;
+    backdrop-filter: blur(8px);
+    border: 1px solid rgba(255,255,180,0.25);
+    width: 100%;
+    height: 100%;
+}
+.control-panel {
+    background: rgba(255, 255, 180, 0.25);
+    border-radius: 18px;
+    box-shadow: 0 4px 24px rgba(0,0,0,0.08);
+    padding: 1.5em;
+    backdrop-filter: blur(8px);
+    border: 1px solid rgba(255,255,180,0.25);
+    width: 100%;
+}
+.status-card {
+    width: 100%
+}
+.action-button {
+    background: linear-gradient(135deg, #ff8c8c 0%, #f9a889 100%) !important;
+    color: white !important;
+    border: none !important;
+    font-weight: 600 !important;
+    box-shadow: 0 4px 12px rgba(0,0,0,0.15) !important;
+    transition: all 0.3s ease-in-out !important;
+}
+.action-button:hover {
+    background: linear-gradient(135deg, #f9a889 0%, #ff8c8c 100%) !important;
+    box-shadow: 0 6px 16px rgba(0,0,0,0.2) !important;
+    transform: translateY(-2px) !important;
+}
+
+.simple-tabs .tab-nav button {
+    background: transparent !important;
+    color: #4A5568 !important;
+    box-shadow: none !important;
+    transform: none !important;
+    border: none !important;
+    border-bottom: 2px solid #E2E8F0 !important;
+    border-radius: 0 !important;
+    font-weight: 600 !important;
+}
+
+.simple-tabs .tab-nav button.selected {
+    color: #f97316 !important;
+    border-bottom: 2px solid #f97316 !important;
+}
+
+.simple-tabs .tab-nav button:hover {
+    background: #f3f4f6 !important;
+    color: #f97316 !important;
+    box-shadow: none !important;
+    transform: none !important;
+}
+"""
+
+
+# Create the main interface
+with gr.Blocks(
+    css=css, title=" 🌐 Hugging Face Transformers Docs i18n made easy"
+) as demo:
+
+    # Title
+    with open("images/hfkr_logo.png", "rb") as img_file:
+        base64_img = base64.b64encode(img_file.read()).decode()
+    gr.Markdown(
+        f'<img src="data:image/png;base64,{base64_img}" style="display: block; margin-left: auto; margin-right: auto; height: 15em;"/>'
+    )
+    gr.Markdown(
+        '<h1 style="text-align: center;"> 🌐 Hugging Face Transformers Docs i18n made easy</h1>'
+    )
+
+    # Content
+    with gr.Row():
+        # Chat interface
+        with gr.Column(scale=4, elem_classes=["chat-container"]):
+            gr.Markdown("### 🌐 Hugging Face i18n Agent")
+
+            chatbot = gr.Chatbot(
+                value=[[None, get_welcome_message()]], scale=1, height=585
+            )
+
+        # Controller interface
+        with gr.Column(scale=2):
+            # Quick Controller
+            with gr.Column(elem_classes=["control-panel"]):
+                gr.Markdown("### 🛠️ Quick Controls")
+                status_display = gr.HTML(update_status())
+
+                with gr.Tabs(elem_classes="simple-tabs") as control_tabs:
+                    with gr.TabItem("1. Find Files", id=0):
+                        with gr.Group():
+                            lang_dropdown = gr.Dropdown(
+                                choices=[language.value for language in Languages],
+                                label="🌍 Translate To",
+                                value="ko",
+                            )
+                            k_input = gr.Number(
+                                label="📊 First k missing translated docs",
+                                value=1,
+                                minimum=1,
+                                maximum=100,
+                            )
+                            find_btn = gr.Button(
+                                "🔍 Find Files to Translate",
+                                elem_classes="action-button",
+                            )
+
+                    with gr.TabItem("2. Translate", id=1):
+                        with gr.Group():
+                            translate_lang_display = gr.Dropdown(
+                                choices=[language.value for language in Languages],
+                                label="🌍 Translation Language",
+                                value="ko",
+                                interactive=False,
+                            )
+                            anthropic_key = gr.Textbox(
+                                label="🔑 Anthropic API key for translation generation",
+                                type="password",
+                            )
+                            start_translate_btn = gr.Button(
+                                "🚀 Start Translation", elem_classes="action-button"
+                            )
+
+                    with gr.TabItem("3. Upload PR", id=2):
+                        with gr.Group():
+                            github_token = gr.Textbox(
+                                label="🔑 GitHub Token",
+                                type="password",
+                                placeholder="ghp_xxxxxxxxxxxxxxxxxxxx",
+                            )
+                            github_owner = gr.Textbox(
+                                label="👤 GitHub Owner/Username",
+                                placeholder="your-username",
+                            )
+                            github_repo = gr.Textbox(
+                                label="📁 Repository Name",
+                                placeholder="your-repository",
+                            )
+                            reference_pr_url = gr.Textbox(
+                                label="🔗 Reference PR URL (Optional - Agent will find one if not provided)",
+                                placeholder="reference PR URL",
+                            )
+
+                            save_config_btn = gr.Button(
+                                "💾 Save GitHub Config", elem_classes="action-button"
+                            )
+                            approve_btn = gr.Button(
+                                "✅ Generate GitHub PR", elem_classes="action-button"
+                            )
+                            restart_btn = gr.Button(
+                                "🔄 Restart Translation", elem_classes="action-button"
+                            )
+
+            # Chat Controller
+            with gr.Column(elem_classes=["control-panel"]):
+                gr.Markdown("### 💬 Chat with agent")
+                msg_input = gr.Textbox(
+                    placeholder="Type your message here... (e.g. 'what', 'how', or 'help')",
+                    container=False,
+                    scale=4,
+                )
+                send_btn = gr.Button("Send", scale=1, elem_classes="action-button")
+
+    # Event Handlers
+
+    find_btn.click(
+        fn=process_file_search_handler,
+        inputs=[lang_dropdown, k_input, chatbot],
+        outputs=[chatbot, msg_input, status_display, control_tabs],
+    )
+
+    # Sync language across tabs
+    lang_dropdown.change(
+        fn=sync_language_displays,
+        inputs=[lang_dropdown],
+        outputs=[translate_lang_display],
+    )
+
+    # Button event handlers
+    start_translate_btn.click(
+        fn=start_translate_handler,
+        inputs=[chatbot, anthropic_key],
+        outputs=[chatbot, msg_input, status_display, control_tabs],
+    )
+
+    # GitHub Config Save
+    save_config_btn.click(
+        fn=update_github_config,
+        inputs=[github_token, github_owner, github_repo, reference_pr_url],
+        outputs=[msg_input],
+    )
+
+    approve_btn.click(
+        fn=approve_handler,
+        inputs=[chatbot, github_owner, github_repo, reference_pr_url],
+        outputs=[chatbot, msg_input, status_display],
+    )
+
+    restart_btn.click(
+        fn=restart_handler,
+        inputs=[chatbot],
+        outputs=[chatbot, msg_input, status_display, control_tabs],
+    )
+
+    send_btn.click(
+        fn=send_message,
+        inputs=[msg_input, chatbot],
+        outputs=[chatbot, msg_input, status_display],
+    )
+
+    msg_input.submit(
+        fn=send_message,
+        inputs=[msg_input, chatbot],
+        outputs=[chatbot, msg_input, status_display],
+    )
+
+root_path = os.environ.get("GRADIO_ROOT_PATH")
+demo.launch(root_path=root_path)

example.env

@@ -0,0 +1,7 @@
+ANTHROPIC_API_KEY=<your api key>
+
+# GitHub PR Agent Configuration
+GITHUB_TOKEN=<your github token>
+GITHUB_OWNER=<your github username>
+GITHUB_REPO=<your repository name>
+REFERENCE_PR_URL=<reference pr url for style analysis>

index.html

@@ -0,0 +1,19 @@
+<!doctype html>
+<html>
+	<head>
+		<meta charset="utf-8" />
+		<meta name="viewport" content="width=device-width" />
+		<title>My static Space</title>
+		<link rel="stylesheet" href="style.css" />
+	</head>
+	<body>
+		<div class="card">
+			<h1>Welcome to your static Space!</h1>
+			<p>You can modify this app directly by editing <i>index.html</i> in the Files and versions tab.</p>
+			<p>
+				Also don't forget to check the
+				<a href="https://huggingface.co/docs/hub/spaces" target="_blank">Spaces documentation</a>.
+			</p>
+		</div>
+	</body>
+</html>

pr_generator/agent.py

@@ -0,0 +1,593 @@
+"""
+GitHub PR creation agent using Langchain.
+This code integrates with the actual GitHub API using the PyGithub library.
+Please set the GITHUB_TOKEN environment variable and install required libraries before running.
+"""
+
+import os
+import re
+import json
+from typing import Optional, Dict, List, Tuple, Any
+
+# Load environment variables from .env file
+from dotenv import load_dotenv
+
+load_dotenv()
+
+# Constants definition
+ANTHROPIC_MODEL_ID = "claude-sonnet-4-20250514"
+DEFAULT_TEMPERATURE = 0.0
+
+# Library imports and error handling
+try:
+    from github import Github, GithubException
+    from github.GitRef import GitRef
+    from langchain_anthropic import ChatAnthropic
+
+    REQUIRED_LIBS_AVAILABLE = True
+except ImportError as e:
+    print(f"Required libraries are not installed: {e}")
+    print("Please run: pip install PyGithub boto3 langchain-anthropic")
+    REQUIRED_LIBS_AVAILABLE = False
+
+
+class GitHubPRAgent:
+    """Agent class for GitHub PR creation"""
+
+    def __init__(self):
+        self._github_client = None
+        self._llm = None
+
+    @property
+    def github_client(self) -> Optional[Github]:
+        """Return GitHub API client with lazy initialization."""
+        if not REQUIRED_LIBS_AVAILABLE:
+            raise ImportError("Required libraries not found.")
+
+        if self._github_client is None:
+            token = os.environ.get("GITHUB_TOKEN")
+            if not token:
+                print("Warning: GITHUB_TOKEN environment variable not set.")
+                return Github()  # Limited access
+            self._github_client = Github(token)
+
+        return self._github_client
+
+    @property
+    def llm(self):
+        """Return LLM client with lazy initialization."""
+        if not REQUIRED_LIBS_AVAILABLE:
+            raise ImportError("Required libraries not found.")
+
+        if self._llm is None:
+            self._llm = ChatAnthropic(
+                model=ANTHROPIC_MODEL_ID,
+                temperature=DEFAULT_TEMPERATURE,
+            )
+        return self._llm
+
+    def _handle_github_error(self, e: Exception, operation: str) -> str:
+        """Handle GitHub API errors consistently."""
+        if isinstance(e, GithubException):
+            return f"{operation} failed: {e.status} {e.data.get('message', e.data)}"
+        return f"Unexpected error during {operation}: {str(e)}"
+
+    def create_pull_request(
+        self,
+        owner: str,
+        repo_name: str,
+        title: str,
+        head: str,
+        base: str,
+        body: str = "",
+        draft: bool = False,
+        maintainer_can_modify: bool = True,
+    ) -> str:
+        """Create a new Pull Request."""
+        try:
+            # 1. Check if head and base are the same
+            if head == base:
+                return f"ERROR: head branch ({head}) and base branch ({base}) are identical."
+
+            # 2. Check for existing PR
+            existing_pr = self.check_existing_pr(owner, repo_name, head, base)
+            if existing_pr:
+                return f"ERROR: {existing_pr}"
+
+            # 3. Verify head branch exists
+            repo = self.github_client.get_repo(f"{owner}/{repo_name}")
+            try:
+                head_branch = repo.get_branch(head)
+                base_branch = repo.get_branch(base)
+
+                # 4. Check if head and base branches point to the same commit
+                if head_branch.commit.sha == base_branch.commit.sha:
+                    return f"ERROR: head branch ({head}) and base branch ({base}) point to the same commit. No changes to merge."
+
+            except GithubException as e:
+                if e.status == 404:
+                    return f"ERROR: Branch not found. head: {head}, base: {base}"
+
+            # 5. Create PR
+            pr = repo.create_pull(
+                title=title,
+                body=body,
+                head=head,
+                base=base,
+                draft=draft,
+                maintainer_can_modify=maintainer_can_modify,
+            )
+            return f"PR creation successful: {pr.html_url}"
+        except GithubException as e:
+            if e.status == 422:
+                error_msg = e.data.get("message", "Unknown error")
+                errors = e.data.get("errors", [])
+
+                error_details = []
+                for error in errors:
+                    if "message" in error:
+                        error_details.append(error["message"])
+
+                detail_msg = " | ".join(error_details) if error_details else ""
+                return f"ERROR: PR creation failed (422): {error_msg}. {detail_msg}"
+            return self._handle_github_error(e, "PR creation")
+        except Exception as e:
+            return self._handle_github_error(e, "PR creation")
+
+    def create_branch(
+        self, owner: str, repo_name: str, branch_name: str, source_sha: str
+    ) -> str:
+        """Create a new branch."""
+        try:
+            repo = self.github_client.get_repo(f"{owner}/{repo_name}")
+            ref_name = f"refs/heads/{branch_name}"
+            new_ref = repo.create_git_ref(ref=ref_name, sha=source_sha)
+
+            if isinstance(new_ref, GitRef):
+                return f"SUCCESS: Branch '{branch_name}' created successfully (ref: {new_ref.ref})"
+            return f"ERROR: Branch '{branch_name}' creation failed. Please check API response."
+        except GithubException as e:
+            if e.status == 422 and "Reference already exists" in str(e.data):
+                return f"WARNING: Branch '{branch_name}' already exists."
+            return self._handle_github_error(e, "branch creation")
+        except Exception as e:
+            return self._handle_github_error(e, "branch creation")
+
+    def check_existing_pr(
+        self, owner: str, repo_name: str, head: str, base: str
+    ) -> Optional[str]:
+        """Check if there's an existing PR with the same head and base."""
+        try:
+            repo = self.github_client.get_repo(f"{owner}/{repo_name}")
+            pulls = repo.get_pulls(state="open", head=f"{owner}:{head}", base=base)
+            for pr in pulls:
+                return f"Existing PR found: {pr.html_url}"
+            return None
+        except Exception as e:
+            print(f"⚠️ Error checking existing PR: {str(e)}")
+            return None
+
+    def create_or_update_file(
+        self,
+        owner: str,
+        repo_name: str,
+        path: str,
+        message: str,
+        content: str,
+        branch_name: Optional[str] = None,
+        sha_blob: Optional[str] = None,
+    ) -> str:
+        """Create or update a single file."""
+        try:
+            repo = self.github_client.get_repo(f"{owner}/{repo_name}")
+
+            args = {
+                "path": path,
+                "message": message,
+                "content": content,
+            }
+            if branch_name:
+                args["branch"] = branch_name
+
+            # Try to update file
+            if sha_blob:
+                args["sha"] = sha_blob
+                repo.update_file(**args)
+                return f"SUCCESS: File updated - {path}"
+
+            # Try to create file
+            repo.create_file(**args)
+            return f"SUCCESS: File created - {path}"
+
+        except GithubException as e:
+            # Try to update if file already exists
+            if e.status == 422:
+                try:
+                    existing_file = repo.get_contents(
+                        path, ref=branch_name or repo.default_branch
+                    )
+                    args["sha"] = existing_file.sha
+                    repo.update_file(**args)
+                    return f"SUCCESS: File updated - {path}"
+                except:
+                    pass
+            return f"ERROR: File processing failed - {path}"
+        except Exception:
+            return f"ERROR: File processing failed - {path}"
+
+    def analyze_reference_pr(self, pr_url: str) -> Dict[str, Any]:
+        """Analyze reference PR to extract style information."""
+        try:
+            # Parse PR URL
+            match = re.match(r"https://github\.com/([^/]+)/([^/]+)/pull/(\d+)", pr_url)
+            if not match:
+                return {"error": f"Invalid PR URL format: {pr_url}"}
+
+            owner, repo_name, pr_number = match.groups()
+            repo = self.github_client.get_repo(f"{owner}/{repo_name}")
+            pr = repo.get_pull(int(pr_number))
+
+            return {
+                "title": pr.title,
+                "body": pr.body,
+                "head_branch": pr.head.ref,
+                "base_branch": pr.base.ref,
+                "files_changed": [f.filename for f in pr.get_files()],
+                "commits": [
+                    {"message": c.commit.message, "sha": c.sha}
+                    for c in pr.get_commits()
+                ],
+            }
+        except Exception as e:
+            return {"error": f"Error occurred during PR analysis: {str(e)}"}
+
+    def _generate_with_llm(
+        self, prompt: str, fallback_value: str, operation: str
+    ) -> str:
+        """Generate text using LLM."""
+        try:
+            response = self.llm.invoke(prompt)
+            generated = response.content.strip()
+            print(f"LLM generated {operation}: {generated}")
+            return generated
+        except Exception as e:
+            print(f"❌ Error generating {operation} with LLM: {e}")
+            print(f"Using fallback value: {fallback_value}")
+            return fallback_value
+
+    def generate_branch_name_from_reference(
+        self, reference_branch_name: str, target_language: str, file_name: str
+    ) -> str:
+        """Use LLM to analyze reference PR information and generate appropriate branch name."""
+        prompt = f"""Here is the reference PR information:
+
+Reference PR branch name: {reference_branch_name}
+
+Now I need to generate a branch name for a new translation task:
+- Target language: {target_language}
+- File to translate: {file_name}
+
+Please analyze the pattern and style of the reference PR title to generate a consistent new branch name.
+
+Requirements:
+1. Follow the naming conventions and patterns of the reference PR
+2. Appropriately reflect the target language ({target_language}) and file name ({file_name}) if applicable
+
+Please return only the branch name. No other explanation is needed."""
+
+        fallback = f"translate-{target_language}-{file_name.replace('_', '-')}"
+        return self._generate_with_llm(prompt, fallback, "branch name")
+
+    def generate_pr_content_from_reference(
+        self,
+        reference_title: str,
+        reference_body: str,
+        target_language: str,
+        filepath: str,
+        target_filepath: str,
+        file_name: str,
+    ) -> Tuple[str, str]:
+        """Use LLM to analyze reference PR title and body and generate appropriate PR content."""
+        prompt = f"""Here is the reference PR information:
+
+Reference PR title: {reference_title}
+
+Reference PR body:
+{reference_body}
+
+Now I need to generate PR title and body for a new translation task:
+- Target language: {target_language}
+- Original file: {filepath}
+- Translation file: {target_filepath}
+- File name: {file_name}
+
+Please analyze the style and format of the reference PR to generate consistent new PR title and body.
+
+Requirements:
+1. Follow the title format and pattern of the reference PR
+2. Maintain the body style, markdown format, indentation, and line breaks of the reference PR
+3. Appropriately reflect the target language ({target_language}) and file paths
+4. If there are user mentions (@username), change them to general text instead of actual mentions
+5. Adjust the content to fit the translation task
+
+Response format:
+Title: [PR title here]
+Body: [PR body here, maintaining the exact markdown format and structure of the original]"""
+
+        try:
+            response = self.llm.invoke(prompt)
+            generated_content = response.content.strip()
+
+            # Separate title and body from response
+            lines = generated_content.split("\n")
+            title_line = ""
+            body_lines = []
+            parsing_body = False
+
+            for line in lines:
+                if line.startswith("Title:"):
+                    title_line = line.replace("Title:", "").strip()
+                elif line.startswith("Body:"):
+                    parsing_body = True
+                    body_content = line.replace("Body:", "").strip()
+                    if body_content:
+                        body_lines.append(body_content)
+                elif parsing_body:
+                    body_lines.append(line)
+
+            generated_title = title_line if title_line else reference_title
+            generated_body = (
+                "\n".join(body_lines)
+                if body_lines
+                else f"Add {target_language} translation for `{filepath}`."
+            )
+
+            print(f"LLM generated PR title: {generated_title}")
+            print(f"LLM generated PR body (first 100 chars): {generated_body[:100]}...")
+
+            return generated_title, generated_body
+
+        except Exception as e:
+            print(f"❌ Error generating PR content with LLM: {e}")
+            return self._generate_default_pr_content(
+                target_language, filepath, target_filepath, file_name
+            )
+
+    def _generate_default_pr_content(
+        self, target_language: str, filepath: str, target_filepath: str, file_name: str
+    ) -> Tuple[str, str]:
+        """Generate default PR content."""
+        title = f"[i18n-{target_language}] Add {target_language} translation for {file_name}"
+        body = f"""## Summary
+Add {target_language} translation for `{filepath}`.
+
+## Changes
+- Add {target_language} translation: `{target_filepath}`
+- Original file: `{filepath}`
+"""
+        return title, body
+
+    def generate_commit_message_from_reference(
+        self, commit_messages: List[str], target_language: str, file_name: str
+    ) -> str:
+        """Use LLM to analyze reference PR commit messages and generate appropriate commit message."""
+        commits_text = (
+            "\n".join([f"- {msg}" for msg in commit_messages])
+            if commit_messages
+            else "None"
+        )
+
+        prompt = f"""Here are the commit messages from the reference PR:
+
+{commits_text}
+
+Now I need to generate a commit message for a new translation task:
+- Target language: {target_language}
+- File to translate: {file_name}
+
+Please analyze the commit message patterns and style of the reference PR to generate a consistent new commit message.
+
+Requirements:
+1. Follow the commit message style and format of the reference PR
+2. Appropriately reflect the target language ({target_language}) and file name ({file_name})
+3. Follow general Git commit message conventions
+4. Be concise and clear
+5. If you detect typos in the given commit messages, use corrected versions (e.g., dos -> docs)
+
+Please return only the commit message. No other explanation is needed."""
+
+        fallback = f"docs: add {target_language} translation for {file_name}"
+        return self._generate_with_llm(prompt, fallback, "commit message")
+
+    def get_branch_info(self, owner: str, repo_name: str, branch_name: str) -> str:
+        """Get information about an existing branch."""
+        try:
+            repo = self.github_client.get_repo(f"{owner}/{repo_name}")
+            branch = repo.get_branch(branch_name)
+            commit = branch.commit
+            commit_info = commit.commit
+
+            return f"""
+📋 Existing branch information:
+  - Branch name: {branch_name}
+  - Latest commit: {commit.sha[:8]}
+  - Commit message: {commit_info.message.split(chr(10))[0][:80]}...
+  - Author: {commit_info.author.name}
+  - Date: {commit_info.author.date.strftime('%Y-%m-%d %H:%M:%S')}
+            """
+        except Exception as e:
+            return f"Failed to retrieve branch information: {str(e)}"
+
+    def run_translation_pr_workflow(
+        self,
+        reference_pr_url: str,
+        target_language: str,
+        filepath: str,
+        translated_doc: str,
+        owner: str,
+        repo_name: str,
+        base_branch: str = "main",
+    ) -> Dict[str, Any]:
+        """Execute translation document PR creation workflow."""
+        try:
+            # 1. Analyze reference PR
+            print(f"🔍 Analyzing reference PR: {reference_pr_url}")
+            pr_analysis = self.analyze_reference_pr(reference_pr_url)
+
+            if "error" in pr_analysis:
+                return {"status": "error", "message": pr_analysis["error"]}
+
+            print("Reference PR analysis completed")
+
+            # 2. Generate translation file path and branch name
+            target_filepath = filepath.replace("/en/", f"/{target_language}/")
+            file_name = filepath.split("/")[-1].replace(".md", "")
+
+            print(f"🌿 Generating branch name...")
+            branch_name = self.generate_branch_name_from_reference(
+                pr_analysis["head_branch"], target_language, file_name
+            )
+
+            # 3. Get main branch SHA and create branch
+            repo = self.github_client.get_repo(f"{owner}/{repo_name}")
+            main_branch = repo.get_branch(base_branch)
+            main_sha = main_branch.commit.sha
+
+            print(f"🌿 Creating branch: {branch_name}")
+            branch_result = self.create_branch(owner, repo_name, branch_name, main_sha)
+
+            # Check branch creation result
+            if branch_result.startswith("ERROR"):
+                return {
+                    "status": "error",
+                    "message": f"Branch creation failed: {branch_result}",
+                    "branch": branch_name,
+                }
+            elif branch_result.startswith("WARNING"):
+                print(f"⚠️ {branch_result}")
+                # Continue if branch already exists
+            else:
+                print(f"{branch_result}")
+
+            # 4. Generate commit message and save file
+            commit_messages = [commit["message"] for commit in pr_analysis["commits"]]
+            commit_message = self.generate_commit_message_from_reference(
+                commit_messages, target_language, file_name
+            )
+
+            print(f"📄 Saving file: {target_filepath}")
+            file_result = self.create_or_update_file(
+                owner,
+                repo_name,
+                target_filepath,
+                commit_message,
+                translated_doc,
+                branch_name,
+            )
+
+            if not file_result.startswith("SUCCESS"):
+                return {
+                    "status": "error",
+                    "message": "An issue occurred while saving the file.",
+                    "branch": branch_name,
+                    "file_path": target_filepath,
+                }
+
+            print(f"{file_result}")
+
+            # 5. Create PR
+            pr_title, pr_body = self.generate_pr_content_from_reference(
+                pr_analysis["title"],
+                pr_analysis["body"],
+                target_language,
+                filepath,
+                target_filepath,
+                file_name,
+            )
+
+            print(f"🔄 Creating PR: {pr_title}")
+            print(f"   Head: {branch_name} → Base: {base_branch}")
+
+            pr_result = self.create_pull_request(
+                owner, repo_name, pr_title, branch_name, base_branch, pr_body
+            )
+
+            if pr_result.startswith("ERROR"):
+                print(f"❌ {pr_result}")
+                return {
+                    "status": "partial_success",
+                    "branch": branch_name,
+                    "file_path": target_filepath,
+                    "message": f"File was saved but PR creation failed: {pr_result}",
+                    "error_details": pr_result,
+                }
+            elif "successful" in pr_result and "http" in pr_result:
+                print(f"{pr_result}")
+                return {
+                    "status": "success",
+                    "branch": branch_name,
+                    "file_path": target_filepath,
+                    "pr_url": pr_result.split(": ")[-1],
+                    "message": "Translation document PR created successfully!",
+                }
+            else:
+                return {
+                    "status": "partial_success",
+                    "branch": branch_name,
+                    "file_path": target_filepath,
+                    "message": "File was saved but PR creation failed.",
+                }
+
+        except Exception as e:
+            return {
+                "status": "error",
+                "message": f"Error occurred during workflow execution: {str(e)}",
+            }
+
+
+# Backward compatibility functions (maintain compatibility with existing code)
+_agent = GitHubPRAgent()
+
+
+def get_github_client():
+    return _agent.github_client
+
+
+def create_pull_request_func(*args, **kwargs):
+    return _agent.create_pull_request(*args, **kwargs)
+
+
+def create_branch_func(*args, **kwargs):
+    return _agent.create_branch(*args, **kwargs)
+
+
+def create_or_update_file_func(*args, **kwargs):
+    return _agent.create_or_update_file(*args, **kwargs)
+
+
+def analyze_reference_pr_func(*args, **kwargs):
+    return _agent.analyze_reference_pr(*args, **kwargs)
+
+
+def generate_branch_name_from_reference(*args, **kwargs):
+    return _agent.generate_branch_name_from_reference(*args, **kwargs)
+
+
+def generate_pr_content_from_reference(*args, **kwargs):
+    return _agent.generate_pr_content_from_reference(*args, **kwargs)
+
+
+def generate_default_pr_content(*args, **kwargs):
+    return _agent._generate_default_pr_content(*args, **kwargs)
+
+
+def generate_commit_message_from_reference(*args, **kwargs):
+    return _agent.generate_commit_message_from_reference(*args, **kwargs)
+
+
+def get_branch_info(*args, **kwargs):
+    return _agent.get_branch_info(*args, **kwargs)
+
+
+def run_translation_pr_agent_simple(*args, **kwargs):
+    return _agent.run_translation_pr_workflow(*args, **kwargs)

pr_generator/searcher.py

@@ -0,0 +1,238 @@
+"""
+GitHub PR Search Agent
+An agent that finds a suitable reference PR when a reference PR URL is not provided.
+"""
+
+import os
+import re
+import logging
+from typing import List, Dict, Any, Optional
+
+# Load environment variables
+from dotenv import load_dotenv
+
+load_dotenv()
+
+# Setup logging
+logging.basicConfig(
+    level=logging.INFO, format="%(asctime)s - %(levelname)s - %(message)s"
+)
+logger = logging.getLogger(__name__)
+
+# Langchain imports
+try:
+    from langchain_anthropic import ChatAnthropic
+    from langchain.tools import StructuredTool
+    from langchain.agents import AgentExecutor, create_tool_calling_agent
+    from langchain_core.prompts import ChatPromptTemplate
+    from github import Github
+
+    REQUIRED_LIBS_AVAILABLE = True
+except ImportError as e:
+    print(f"Required libraries are not installed: {e}")
+    REQUIRED_LIBS_AVAILABLE = False
+
+# Constants
+ANTHROPIC_MODEL_ID = "claude-sonnet-4-20250514"
+DEFAULT_TEMPERATURE = 0.0
+# Fallback PR URL to ensure a PR is always returned
+DEFAULT_FALLBACK_PR_URL = "https://github.com/huggingface/transformers/pull/24968"
+
+
+class GitHubPRSearcher:
+    """GitHub PR Searcher - now using a LangChain agent."""
+
+    def _search_github_prs(self, query: str) -> List[Dict[str, Any]]:
+        """
+        Searches GitHub for pull requests matching the query and returns the top 5 results.
+        The query should be a valid GitHub search query.
+        """
+        logger.info(f"Executing GitHub search with query: {query}")
+        try:
+            issues = self.github_client.search_issues(query=query)
+            # Take top 5 to keep context small for the agent
+            top_issues = issues.get_page(0)[:5]
+
+            if not top_issues:
+                return []
+
+            return [
+                {"title": issue.title, "url": issue.html_url, "number": issue.number}
+                for issue in top_issues
+            ]
+        except Exception as e:
+            logger.error(f"Error during GitHub search: {e}", exc_info=True)
+            # Return an error message that the agent can understand
+            return [{"error": f"An error occurred during search: {e}"}]
+
+    def __init__(self):
+        if not REQUIRED_LIBS_AVAILABLE:
+            raise ImportError("Required libraries for agent could not be found.")
+
+        self._github_client = None
+        self.llm = ChatAnthropic(
+            model=ANTHROPIC_MODEL_ID,
+            temperature=DEFAULT_TEMPERATURE,
+        )
+
+        search_tool = StructuredTool.from_function(
+            func=self._search_github_prs,
+            name="search_github_prs",
+            description="Searches GitHub for pull requests matching the query and returns the top 5 results. The query should be a valid GitHub search query.",
+        )
+        tools = [search_tool]
+
+        prompt_string = """You are a GitHub expert. Your mission is to find the best reference pull request (PR) for a given task.
+
+You need to find a merged PR in the repository: {owner}/{repo_name}.
+The PR should be for a documentation translation into **{target_language}**.
+The context for the translation is: **{context}**.
+
+Use the tools at your disposal to search for relevant PRs.
+Analyze the search results and select the one that best matches the request. A good PR is usually one that has "translation", "docs", "i18n", and the target language in its title.
+
+Here is an example of a good search query you could use:
+`repo:{owner}/{repo_name} is:pr is:merged "{target_language}" "{context}" i18n translation docs`
+
+After your analysis, you MUST output **only the final URL** of the best PR you have chosen. Do not include any other text in your final response."""
+
+        prompt = ChatPromptTemplate.from_messages(
+            [
+                ("system", prompt_string),
+                (
+                    "human",
+                    "Find the best reference PR for translating docs to {target_language} about {context} in the {owner}/{repo_name} repository.",
+                ),
+                ("placeholder", "{agent_scratchpad}"),
+            ]
+        )
+
+        agent = create_tool_calling_agent(self.llm, tools, prompt)
+        self.agent_executor = AgentExecutor(agent=agent, tools=tools, verbose=False)
+
+    @property
+    def github_client(self) -> Optional[Github]:
+        """Lazy initialization of the GitHub API client."""
+        if not REQUIRED_LIBS_AVAILABLE:
+            raise ImportError("Required libraries could not be found.")
+
+        if self._github_client is None:
+            token = os.environ.get("GITHUB_TOKEN")
+            if not token:
+                print("Warning: GITHUB_TOKEN environment variable is not set.")
+                self._github_client = Github()  # Limited access
+            else:
+                self._github_client = Github(token)
+        return self._github_client
+
+    def find_best_reference_pr(
+        self, owner: str, repo_name: str, target_language: str, context: str
+    ):
+        """
+        Finds the best reference PR using a LangChain agent.
+        Yields progress and returns the final PR URL.
+        """
+        message = "🤖 Agent is searching for the best reference PR..."
+        logger.info(message)
+        yield message
+
+        try:
+            agent_input = {
+                "owner": owner,
+                "repo_name": repo_name,
+                "target_language": target_language,
+                "context": context,
+            }
+
+            agent_output = None
+            for event in self.agent_executor.stream(agent_input):
+                if "actions" in event and event["actions"]:
+                    action = event["actions"][0]
+                    tool_query = action.tool_input.get("query", str(action.tool_input))
+                    message = f"🔍 Agent is using tool `{action.tool}` with query:\n`{tool_query}`"
+                    logger.info(message)
+                    yield message
+                elif "steps" in event and event["steps"]:
+                    message = "📊 Agent is analyzing the results from the tool..."
+                    logger.info(message)
+                    yield message
+                elif "output" in event and event["output"]:
+                    agent_output = event["output"]
+
+            if not agent_output:
+                message = "⚠️ Agent failed to find a suitable PR. Using default PR."
+                logger.warning(message)
+                yield message
+                return DEFAULT_FALLBACK_PR_URL
+
+            # The agent's final output can be a string, a list of tool results,
+            # or a list of content blocks from the LLM. We'll find the URL
+            # by searching for it in the string representation of the output.
+            output_text = str(agent_output)
+            urls = re.findall(r"https?://github.com/[^/]+/[^/]+/pull/\d+", output_text)
+
+            final_url = ""
+            if urls:
+                final_url = urls[-1]  # Take the last URL found
+
+            if not final_url:
+                message = f"⚠️ Agent returned unparsable output: {agent_output}. Using default PR."
+                logger.warning(message)
+                yield message
+                return DEFAULT_FALLBACK_PR_URL
+
+            message = f"✅ Selected the best PR:\n`{final_url}`"
+            logger.info(f"Selected the best PR: {final_url}")
+            yield message
+            return final_url
+
+        except Exception as e:
+            message = f"❌ Error during agent execution: {e}\nUsing default PR."
+            logger.error(message, exc_info=True)
+            yield message
+            return DEFAULT_FALLBACK_PR_URL
+
+
+def find_reference_pr_simple_stream(target_language: str = "", context: str = ""):
+    """
+    A simple function to find a reference PR, streaming progress.
+    This function always searches in the 'huggingface/transformers' repository.
+    """
+    searcher = GitHubPRSearcher()
+    stream_generator = searcher.find_best_reference_pr(
+        "huggingface", "transformers", target_language, context
+    )
+    # The handler will receive the final URL from the generator's return statement
+    final_url = yield from stream_generator
+
+    # Format the final result as expected by the handler
+    return {
+        "status": "success",
+        "result": f"Recommended PR URL: {final_url}",
+        "repository": "huggingface/transformers",
+        "target_language": target_language,
+    }
+
+
+# Example usage
+if __name__ == "__main__":
+    # Example execution for streaming
+    # In a real application, a generator consumer (like the one in handler.py)
+    # would process the yielded values. This script simulates that.
+    print("--- Running Streaming Search Simulation ---")
+
+    def run_simulation():
+        """Simulates the consumption of the streaming generator."""
+        test_gen = find_reference_pr_simple_stream(
+            target_language="korean", context="docs"
+        )
+        try:
+            while True:
+                # This will print progress messages
+                print(next(test_gen))
+        except StopIteration as e:
+            # When the generator is exhausted, the final result is in e.value
+            print("\n--- FINAL RESULT ---")
+            print(e.value)
+
+    run_simulation()

requirements.txt

@@ -0,0 +1,9 @@
+gradio==5.33.0
+requests
+pydantic
+langchain-anthropic
+python-dotenv
+langchain
+PyGithub
+langchain-core
+langchain-community 

style.css

@@ -0,0 +1,28 @@
+body {
+	padding: 2rem;
+	font-family: -apple-system, BlinkMacSystemFont, "Arial", sans-serif;
+}
+
+h1 {
+	font-size: 16px;
+	margin-top: 0;
+}
+
+p {
+	color: rgb(107, 114, 128);
+	font-size: 15px;
+	margin-bottom: 10px;
+	margin-top: 5px;
+}
+
+.card {
+	max-width: 620px;
+	margin: 0 auto;
+	padding: 16px;
+	border: 1px solid lightgray;
+	border-radius: 16px;
+}
+
+.card p:last-child {
+	margin-bottom: 0;
+}

test/test_final_translate.md

@@ -0,0 +1,127 @@
+<!--Copyright 2025 The HuggingFace Team. All rights reserved.
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on
+an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
+specific language governing permissions and limitations under the License.
+
+⚠️ Note that this file is in Markdown but contains specific syntax for our doc-builder (similar to MDX) that may not be
+rendered properly in your Markdown viewer.
+
+-->
+
+# 가속기 선택 [[accelerator-selection]]
+
+분산 훈련 중에는 사용할 가속기(CUDA, XPU, MPS, HPU 등)의 개수와 순서를 지정할 수 있습니다. 이는 서로 다른 컴퓨팅 성능을 가진 가속기들이 있을 때 더 빠른 가속기를 먼저 사용하고 싶거나, 사용 가능한 가속기 중 일부만 사용하고 싶을 때 유용합니다. 선택 과정은 [DistributedDataParallel](https://pytorch.org/docs/stable/generated/torch.nn.parallel.DistributedDataParallel.html)과 [DataParallel](https://pytorch.org/docs/stable/generated/torch.nn.DataParallel.html) 모두에서 작동합니다. Accelerate나 [DeepSpeed integration](./main_classes/deepspeed)이 필요하지 않습니다.
+
+이 가이드에서는 사용할 가속기의 개수와 사용 순서를 선택하는 방법을 보여드립니다.
+
+## 가속기 개수 [[number-of-accelerators]]
+
+예를 들어, 4개의 가속기가 있고 처음 2개만 사용하고 싶다면 아래 명령어를 실행하세요.
+
+<hfoptions id="select-accelerator">
+<hfoption id="torchrun">
+
+사용할 가속기 개수를 선택하려면 `--nproc_per_node`를 사용하세요.
+
+```bash
+torchrun --nproc_per_node=2  trainer-program.py ...
+```
+
+</hfoption>
+<hfoption id="Accelerate">
+
+사용할 가속기 개수를 선택하려면 `--num_processes`를 사용하세요.
+
+```bash
+accelerate launch --num_processes 2 trainer-program.py ...
+```
+
+</hfoption>
+<hfoption id="🤗 DeepSpeed">
+
+사용할 GPU 개수를 선택하려면 `--num_gpus`를 사용하세요.
+
+```bash
+deepspeed --num_gpus 2 trainer-program.py ...
+```
+
+</hfoption>
+</hfoptions>
+
+## 가속기 순서 [[order-of-accelerators]]
+사용할 특정 가속기와 그 순서를 선택하려면 하드웨어에 적합한 환경 변수를 사용하세요. 이는 보통 각 실행마다 명령줄에서 설정되지만, `~/.bashrc`나 다른 시작 설정 파일에 추가할 수도 있습니다.
+
+예를 들어, 4개의 가속기(0, 1, 2, 3)가 있고 가속기 0과 2만 실행하고 싶다면:
+
+<hfoptions id="accelerator-type">
+<hfoption id="CUDA">
+
+```bash
+CUDA_VISIBLE_DEVICES=0,2 torchrun trainer-program.py ...
+```
+
+GPU 0과 2만 PyTorch에 "보이며" 각각 `cuda:0`과 `cuda:1`로 매핑됩니다.  
+순서를 바꾸려면(GPU 2를 `cuda:0`으로, GPU 0을 `cuda:1`로 사용):
+
+
+```bash
+CUDA_VISIBLE_DEVICES=2,0 torchrun trainer-program.py ...
+```
+
+GPU 없이 실행하려면:
+
+```bash
+CUDA_VISIBLE_DEVICES= python trainer-program.py ...
+```
+
+`CUDA_DEVICE_ORDER`를 사용하여 CUDA 장치의 순서를 제어할 수도 있습니다:
+
+- PCIe 버스 ID 순서(`nvidia-smi`와 일치):
+
+    ```bash
+$hf_i18n_placeholder21export CUDA_DEVICE_ORDER=PCI_BUS_ID
+    ```
+
+- 컴퓨팅 성능 순서(가장 빠른 것부터):
+
+    ```bash
+    export CUDA_DEVICE_ORDER=FASTEST_FIRST
+    ```
+
+</hfoption>
+<hfoption id="Intel XPU">
+
+```bash
+ZE_AFFINITY_MASK=0,2 torchrun trainer-program.py ...
+```
+
+XPU 0과 2만 PyTorch에 "보이며" 각각 `xpu:0`과 `xpu:1`로 매핑됩니다.  
+순서를 바꾸려면(XPU 2를 `xpu:0`으로, XPU 0을 `xpu:1`로 사용):
+
+```bash
+ZE_AFFINITY_MASK=2,0 torchrun trainer-program.py ...
+```
+
+
+다음으로 Intel XPU의 순서를 제어할 수도 있습니다:
+
+```bash
+export ZE_ENABLE_PCI_ID_DEVICE_ORDER=1
+```
+
+Intel XPU에서의 장치 열거 및 정렬에 대한 자세한 정보는 [Level Zero](https://github.com/oneapi-src/level-zero/blob/master/README.md?plain=1#L87) 문서를 참조하세요.
+
+</hfoption>
+</hfoptions>
+
+
+
+> [!WARNING]
+> 환경 변수는 명령줄에 추가하는 대신 export할 수 있습니다. 환경 변수가 어떻게 설정되었는지 잊어버리고 잘못된 가속기를 사용하게 될 수 있어 혼란스러울 수 있으므로 권장하지 않습니다. 대신 특정 훈련 실행을 위한 환경 변수를 같은 명령줄에서 설정하는 것이 일반적인 관행입니다.
+

test/test_prompt.py

@@ -0,0 +1,71 @@
+output = """
+What do these sentences about Hugging Face Transformers (a machine learning library) mean in Korean? Please do not translate the word after a 🤗 emoji as it is a product name. Output only the translated result without any explanations or introductions.
+```md
+# Accelerator selection
+
+During distributed training, you can specify the number and order of accelerators (CUDA, XPU, MPS, HPU, etc.) to use. This can be useful when you have accelerators with different computing power and you want to use the faster accelerator first. Or you could only use a subset of the available accelerators. The selection process works for both [DistributedDataParallel](https://pytorch.org/docs/stable/generated/torch.nn.parallel.DistributedDataParallel.html) and [DataParallel](https://pytorch.org/docs/stable/generated/torch.nn.DataParallel.html). You don't need Accelerate or [DeepSpeed integration](./main_classes/deepspeed).
+
+This guide will show you how to select the number of accelerators to use and the order to use them in.
+
+## Number of accelerators
+
+For example, if there are 4 accelerators and you only want to use the first 2, run the command below.
+
+<hfoptions id="select-accelerator">
+<hfoption id="torchrun">
+
+Use the `--nproc_per_node` to select how many accelerators to use.
+
+</hfoption>
+<hfoption id="Accelerate">
+
+Use `--num_processes` to select how many accelerators to use.
+
+</hfoption>
+<hfoption id="DeepSpeed">
+
+Use `--num_gpus` to select how many GPUs to use.
+
+</hfoption>
+</hfoptions>
+
+## Order of accelerators
+To select specific accelerators to use and their order, use the environment variable appropriate for your hardware. This is often set on the command line for each run, but can also be added to your `~/.bashrc` or other startup config file.
+
+For example, if there are 4 accelerators (0, 1, 2, 3) and you only want to run accelerators 0 and 2:
+
+<hfoptions id="accelerator-type">
+<hfoption id="CUDA">
+
+Only GPUs 0 and 2 are "visible" to PyTorch and are mapped to `cuda:0` and `cuda:1` respectively.  
+To reverse the order (use GPU 2 as `cuda:0` and GPU 0 as `cuda:1`):
+
+To run without any GPUs:
+
+You can also control the order of CUDA devices using `CUDA_DEVICE_ORDER`:
+
+- Order by PCIe bus ID (matches `nvidia-smi`):
+
+    
+
+- Order by compute capability (fastest first):
+
+    
+
+</hfoption>
+<hfoption id="Intel XPU">
+
+Only XPUs 0 and 2 are "visible" to PyTorch and are mapped to `xpu:0` and `xpu:1` respectively.  
+To reverse the order (use XPU 2 as `xpu:0` and XPU 0 as `xpu:1`):
+
+You can also control the order of Intel XPUs with:
+
+For more information about device enumeration and sorting on Intel XPU, please refer to the [Level Zero](https://github.com/oneapi-src/level-zero/blob/master/README.md?plain=1#L87) documentation.
+
+</hfoption>
+</hfoptions>
+
+> [!WARNING]
+> Environment variables can be exported instead of being added to the command line. This is not recommended because it can be confusing if you forget how the environment variable was set up and you end up using the wrong accelerators. Instead, it is common practice to set the environment variable for a specific training run on the same command line.
+```
+"""

test/test_translate.py

@@ -0,0 +1,68 @@
+translated_content = """
+# 가속기 선택
+
+분산 훈련 중에는 사용할 가속기(CUDA, XPU, MPS, HPU 등)의 개수와 순서를 지정할 수 있습니다. 이는 서로 다른 컴퓨팅 성능을 가진 가속기들이 있을 때 더 빠른 가속기를 먼저 사용하고 싶거나, 사용 가능한 가속기 중 일부만 사용하고 싶을 때 유용합니다. 선택 과정은 [DistributedDataParallel](https://pytorch.org/docs/stable/generated/torch.nn.parallel.DistributedDataParallel.html)과 [DataParallel](https://pytorch.org/docs/stable/generated/torch.nn.DataParallel.html) 모두에서 작동합니다. Accelerate나 [DeepSpeed integration](./main_classes/deepspeed)이 필요하지 않습니다.
+
+이 가이드에서는 사용할 가속기의 개수와 사용 순서를 선택하는 방법을 보여드립니다.
+
+## 가속기 개수
+
+예를 들어, 4개의 가속기가 있고 처음 2개만 사용하고 싶다면 아래 명령어를 실행하세요.
+
+<hfoptions id="select-accelerator">
+<hfoption id="torchrun">
+
+사용할 가속기 개수를 선택하려면 `--nproc_per_node`를 사용하세요.
+
+</hfoption>
+<hfoption id="Accelerate">
+
+사용할 가속기 개수를 선택하려면 `--num_processes`를 사용하세요.
+
+</hfoption>
+<hfoption id="🤗 DeepSpeed">
+
+사용할 GPU 개수를 선택하려면 `--num_gpus`를 사용하세요.
+
+</hfoption>
+</hfoptions>
+
+## 가속기 순서
+사용할 특정 가속기와 그 순서를 선택하려면 하드웨어에 적합한 환경 변수를 사용하세요. 이는 보통 각 실행마다 명령줄에서 설정되지만, `~/.bashrc`나 다른 시작 설정 파일에 추가할 수도 있습니다.
+
+예를 들어, 4개의 가속기(0, 1, 2, 3)가 있고 가속기 0과 2만 실행하고 싶다면:
+
+<hfoptions id="accelerator-type">
+<hfoption id="CUDA">
+
+GPU 0과 2만 PyTorch에 "보이며" 각각 `cuda:0`과 `cuda:1`로 매핑됩니다.  
+순서를 바꾸려면(GPU 2를 `cuda:0`으로, GPU 0을 `cuda:1`로 사용):
+
+GPU 없이 실행하려면:
+
+`CUDA_DEVICE_ORDER`를 사용하여 CUDA 장치의 순서를 제어할 수도 있습니다:
+
+- PCIe 버스 ID 순서(`nvidia-smi`와 일치):
+
+    
+
+- 컴퓨팅 성능 순서(가장 빠른 것부터):
+
+    
+
+</hfoption>
+<hfoption id="Intel XPU">
+
+XPU 0과 2만 PyTorch에 "보이며" 각각 `xpu:0`과 `xpu:1`로 매핑됩니다.  
+순서를 바꾸려면(XPU 2를 `xpu:0`으로, XPU 0을 `xpu:1`로 사용):
+
+다음으로 Intel XPU의 순서를 제어할 수도 있습니다:
+
+Intel XPU에서의 장치 열거 및 정렬에 대한 자세한 정보는 [Level Zero](https://github.com/oneapi-src/level-zero/blob/master/README.md?plain=1#L87) 문서를 참조하세요.
+
+</hfoption>
+</hfoptions>
+
+> [!WARNING]
+> 환경 변수는 명령줄에 추가하는 대신 export할 수 있습니다. 환경 변수가 어떻게 설정되었는지 잊어버리고 잘못된 가속기를 사용하게 될 수 있어 혼란스러울 수 있으므로 권장하지 않습니다. 대신 특정 훈련 실행을 위한 환경 변수를 같은 명령줄에서 설정하는 것이 일반적인 관행입니다.
+"""

translation_result/docs/source/en/accelerator_selection.md

@@ -0,0 +1,127 @@
+<!--Copyright 2025 The HuggingFace Team. All rights reserved.
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on
+an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
+specific language governing permissions and limitations under the License.
+
+⚠️ Note that this file is in Markdown but contains specific syntax for our doc-builder (similar to MDX) that may not be
+rendered properly in your Markdown viewer.
+
+-->
+
+# 가속기 선택 [[accelerator-selection]]
+
+분산 훈련 중에 사용할 가속기(CUDA, XPU, MPS, HPU 등)의 수와 순서를 지정할 수 있습니다. 이는 서로 다른 연산 성능을 가진 가속기가 있고 더 빠른 가속기를 먼저 사용하고 싶을 때 유용할 수 있습니다. 또는 사용 가능한 가속기 중 일부만 사용할 수도 있습니다. 선택 과정은 [DistributedDataParallel](https://pytorch.org/docs/stable/generated/torch.nn.parallel.DistributedDataParallel.html)과 [DataParallel](https://pytorch.org/docs/stable/generated/torch.nn.DataParallel.html) 모두에서 작동합니다. Accelerate나 [DeepSpeed integration](./main_classes/deepspeed)이 필요하지 않습니다.
+
+이 가이드는 사용할 가속기의 수와 사용 순서를 선택하는 방법을 보여줍니다.
+
+## 가속기 수 [[number-of-accelerators]]
+
+예를 들어, 4개의 가속기가 있고 처음 2개만 사용하고 싶다면 아래 명령을 실행하세요.
+
+<hfoptions id="select-accelerator">
+<hfoption id="torchrun">
+
+`--nproc_per_node`를 사용하여 사용할 가속기 수를 선택하세요.
+
+```bash
+torchrun --nproc_per_node=2  trainer-program.py ...
+```
+
+</hfoption>
+<hfoption id="Accelerate">
+
+`--num_processes`를 사용하여 사용할 가속기 수를 선택하세요.
+
+```bash
+accelerate launch --num_processes 2 trainer-program.py ...
+```
+
+</hfoption>
+<hfoption id="DeepSpeed">
+
+`--num_gpus`를 사용하여 사용할 GPU 수를 선택하세요.
+
+```bash
+deepspeed --num_gpus 2 trainer-program.py ...
+```
+
+</hfoption>
+</hfoptions>
+
+## 가속기 순서 [[order-of-accelerators]]
+사용할 특정 가속기와 그 순서를 선택하려면 하드웨어에 적합한 환경 변수를 사용하세요. 이는 각 실행마다 명령줄에서 설정되는 경우가 많지만, `~/.bashrc`나 다른 시작 설정 파일에 추가할 수도 있습니다.
+
+예를 들어, 4개의 가속기(0, 1, 2, 3)가 있고 가속기 0과 2만 실행하고 싶다면:
+
+<hfoptions id="accelerator-type">
+<hfoption id="CUDA">
+
+```bash
+CUDA_VISIBLE_DEVICES=0,2 torchrun trainer-program.py ...
+```
+
+GPU 0과 2만 PyTorch에 "보이며" 각각 `cuda:0`과 `cuda:1`로 매핑됩니다.  
+순서를 바꾸려면 (GPU 2를 `cuda:0`으로, GPU 0을 `cuda:1`로 사용):
+
+
+```bash
+CUDA_VISIBLE_DEVICES=2,0 torchrun trainer-program.py ...
+```
+
+GPU 없이 실행하려면:
+
+```bash
+CUDA_VISIBLE_DEVICES= python trainer-program.py ...
+```
+
+`CUDA_DEVICE_ORDER`를 사용하여 CUDA 장치 순서를 제어할 수도 있습니다:
+
+- PCIe 버스 ID 순서로 정렬 (`nvidia-smi`와 일치):
+
+    ```bash
+$hf_i18n_placeholder21export CUDA_DEVICE_ORDER=PCI_BUS_ID
+    ```
+
+- 연산 성능 순서로 정렬 (가장 빠른 것부터):
+
+    ```bash
+    export CUDA_DEVICE_ORDER=FASTEST_FIRST
+    ```
+
+</hfoption>
+<hfoption id="Intel XPU">
+
+```bash
+ZE_AFFINITY_MASK=0,2 torchrun trainer-program.py ...
+```
+
+XPU 0과 2만 PyTorch에 "보이며" 각각 `xpu:0`과 `xpu:1`로 매핑됩니다.  
+순서를 바꾸려면 (XPU 2를 `xpu:0`으로, XPU 0을 `xpu:1`로 사용):
+
+```bash
+ZE_AFFINITY_MASK=2,0 torchrun trainer-program.py ...
+```
+
+
+다음으로 Intel XPU 순서를 제어할 수도 있습니다:
+
+```bash
+export ZE_ENABLE_PCI_ID_DEVICE_ORDER=1
+```
+
+Intel XPU의 장치 열거 및 정렬에 대한 자세한 정보는 [Level Zero](https://github.com/oneapi-src/level-zero/blob/master/README.md?plain=1#L87) 문서를 참조하세요.
+
+</hfoption>
+</hfoptions>
+
+
+
+> [!WARNING]
+> 환경 변수는 명령줄에 추가하는 대신 export할 수 있습니다. 환경 변수가 어떻게 설정되었는지 잊어버리고 결국 잘못된 가속기를 사용하게 될 수 있어 혼란스러울 수 있으므로 권장하지 않습니다. 대신, 동일한 명령줄에서 특정 훈련 실행에 대해 환경 변수를 설정하는 것이 일반적인 관례입니다.
+```

translator/content.py

@@ -0,0 +1,105 @@
+import re
+import string
+
+import requests
+from langchain.callbacks import get_openai_callback
+from langchain_anthropic import ChatAnthropic
+
+
+def get_content(filepath: str) -> str:
+    url = string.Template(
+        "https://raw.githubusercontent.com/huggingface/" "transformers/main/$filepath"
+    ).safe_substitute(filepath=filepath)
+    response = requests.get(url)
+    if response.status_code == 200:
+        content = response.text
+        return content
+    else:
+        raise ValueError("Failed to retrieve content from the URL.", url)
+
+
+def preprocess_content(content: str) -> str:
+    # Extract text to translate from document
+
+    ## ignore top license comment
+    to_translate = content[content.find("#") :]
+    ## remove code blocks from text
+    to_translate = re.sub(r"```.*?```", "", to_translate, flags=re.DOTALL)
+    ## remove markdown tables from text
+    to_translate = re.sub(r"^\|.*\|$\n?", "", to_translate, flags=re.MULTILINE)
+    ## remove empty lines from text
+    to_translate = re.sub(r"\n\n+", "\n\n", to_translate)
+
+    return to_translate
+
+
+def get_full_prompt(language: str, to_translate: str) -> str:
+    prompt = string.Template(
+        "What do these sentences about Hugging Face Transformers "
+        "(a machine learning library) mean in $language? "
+        "Please do not translate the word after a 🤗 emoji "
+        "as it is a product name. Output only the translated markdown result "
+        "without any explanations or introductions.\n\n```md"
+    ).safe_substitute(language=language)
+    return "\n".join([prompt, to_translate.strip(), "```"])
+
+
+def split_markdown_sections(markdown: str) -> list:
+    # Find all titles using regular expressions
+    return re.split(r"^(#+\s+)(.*)$", markdown, flags=re.MULTILINE)[1:]
+    # format is like [level, title, content, level, title, content, ...]
+
+
+def get_anchors(divided: list) -> list:
+    anchors = []
+    # from https://github.com/huggingface/doc-builder/blob/01b262bae90d66e1150cdbf58c83c02733ed4366/src/doc_builder/build_doc.py#L300-L302
+    for title in divided[1::3]:
+        anchor = re.sub(r"[^a-z0-9\s]+", "", title.lower())
+        anchor = re.sub(r"\s{2,}", " ", anchor.strip()).replace(" ", "-")
+        anchors.append(f"[[{anchor}]]")
+    return anchors
+
+
+def make_scaffold(content: str, to_translate: str) -> string.Template:
+    scaffold = content
+    for i, text in enumerate(to_translate.split("\n\n")):
+        scaffold = scaffold.replace(text, f"$hf_i18n_placeholder{i}", 1)
+    return string.Template(scaffold)
+
+
+def fill_scaffold(content: str, to_translate: str, translated: str) -> str:
+    scaffold = make_scaffold(content, to_translate)
+    divided = split_markdown_sections(to_translate)
+    anchors = get_anchors(divided)
+
+    translated = split_markdown_sections(translated)
+
+    translated[1::3] = [
+        f"{korean_title} {anchors[i]}"
+        for i, korean_title in enumerate(translated[1::3])
+    ]
+    translated = "".join(
+        ["".join(translated[i * 3 : i * 3 + 3]) for i in range(len(translated) // 3)]
+    ).split("\n\n")
+    if newlines := scaffold.template.count("$hf_i18n_placeholder") - len(translated):
+        return str(
+            [
+                f"Please {'recover' if newlines > 0 else 'remove'} "
+                f"{abs(newlines)} incorrectly inserted double newlines."
+            ]
+        )
+
+    translated_doc = scaffold.safe_substitute(
+        {f"hf_i18n_placeholder{i}": text for i, text in enumerate(translated)}
+    )
+    return translated_doc
+
+
+def llm_translate(to_translate: str) -> tuple[str, str]:
+    with get_openai_callback() as cb:
+        model = ChatAnthropic(
+            model="claude-sonnet-4-20250514", max_tokens=64000, streaming=True
+        )
+        ai_message = model.invoke(to_translate)
+        print("cb:", cb)
+    return cb, ai_message.content

translator/model.py

@@ -0,0 +1,70 @@
+from enum import Enum, unique
+
+from pydantic import BaseModel, computed_field
+
+
+@unique
+class Languages(Enum):
+    az = "az"
+    bn = "bn"
+    de = "de"
+    em = "em"
+    es = "es"
+    fa = "fa"
+    fr = "fr"
+    he = "he"
+    hu = "hu"
+    id = "id"
+    it = "it"
+    ja = "ja"
+    ko = "ko"
+    pl = "pl"
+    pt = "pt"
+    ru = "ru"
+    tr = "tr"
+    uk = "uk"
+    ur = "ur"
+    vi = "vi"
+    yo = "yo"
+    zh = "zh"
+    zh_hant = "zh-hant"
+
+
+class TranslationDoc(BaseModel):
+    official_lang: str = "en"
+    translation_lang: str
+    original_file: str
+    translation_file: str | None = None
+    translation_exists: bool
+
+
+class Summary(BaseModel):
+    lang: str
+    files_analyzed: int = 0
+    files_translated: int = 0
+    files_outdated: int = 0
+    files_missing_translation: int = 0
+    files: list[TranslationDoc] = []
+
+    @computed_field  # type: ignore
+    @property
+    def percentage_missing_translation(self) -> float:
+        try:
+            return (
+                100 * float(self.files_missing_translation) / float(self.files_analyzed)
+            )
+        except Exception:
+            return 0.0
+
+    def append_file(self, doc: TranslationDoc) -> None:
+        self.files.append(doc)
+        self.files_analyzed += 1
+
+        if doc.translation_exists:
+            self.files_translated += 1
+
+        if not doc.translation_exists:
+            self.files_missing_translation += 1
+
+    def first_missing_translation_files(self, length: int = 10) -> list[TranslationDoc]:
+        return list(filter(lambda d: not d.translation_exists, self.files))[:length]

translator/retriever.py

@@ -0,0 +1,79 @@
+import os
+from pathlib import Path
+
+import requests
+
+from .model import Languages, Summary, TranslationDoc
+
+URL = "https://api.github.com/repos/huggingface/transformers/git/trees/main?recursive=1"
+
+
+def get_github_repo_files():
+    """
+    Get github repo files
+    """
+    response = requests.get(URL)
+
+    data = response.json()
+    all_items = data.get("tree", [])
+
+    file_paths = [
+        item["path"]
+        for item in all_items
+        if item["type"] == "blob" and (item["path"].startswith("docs"))
+    ]
+    return file_paths
+
+
+def retrieve(summary: Summary, table_size: int = 10) -> tuple[str, list[str]]:
+    """
+    Retrieve missing docs
+    """
+
+    report = f"""
+| Item | Count | Percentage |
+|------|-------|------------|
+| 📂 HuggingFaces docs | {summary.files_analyzed} | - |
+| 🪹 Missing translations | {summary.files_missing_translation} | {summary.percentage_missing_translation:.2f}% |
+"""
+    print(report)
+    first_missing_docs = list()
+    for file in summary.first_missing_translation_files(table_size):
+        first_missing_docs.append(file.original_file)
+
+    print(first_missing_docs)
+    return report, first_missing_docs
+
+
+def report(target_lang: str, top_k: int = 1) -> tuple[str, list[str]]:
+    """
+    Generate a report for the translated docs
+    """
+    docs_file = get_github_repo_files()
+
+    base_docs_path = Path("docs/source")
+    en_docs_path = Path("docs/source/en")
+
+    lang = Languages[target_lang]
+    summary = Summary(lang=lang.value)
+
+    for file in docs_file:
+        if file.endswith(".md"):
+            try:
+                file_relative_path = Path(file).relative_to(en_docs_path)
+            except ValueError:
+                continue
+
+            translated_path = os.path.join(
+                base_docs_path, lang.value, file_relative_path
+            )
+            translation_exists = translated_path in docs_file
+
+            doc = TranslationDoc(
+                translation_lang=lang.value,
+                original_file=file,
+                translation_file=translated_path,
+                translation_exists=translation_exists,
+            )
+            summary.append_file(doc)
+    return retrieve(summary, top_k)