Function translate_tutorial

scripts/translation/translation.py:88–165

(base_file_path: str, output_file_path: str, language_code: str)

async def translate_tutorial(base_file_path: str, output_file_path: str, language_code: str) -> Optional[str]:
    index_json = load_index_json(language_code)
    english_title = Path(base_file_path).stem

    # Look for translated title
    translated_title = None
    for section_titles in index_json.values():
        if english_title in section_titles:
            translated_title = section_titles[english_title]
            break

    if not translated_title:
        logger.error(f"Title '{english_title}' not found in `index.json` for {language_code}. Skipping translation.")
        return None

    # Read the tutorial content
    try:
        with open(base_file_path, "r", encoding="utf-8") as f:
            content = f.read()
    except FileNotFoundError:
        logger.error(f"Tutorial file not found: {base_file_path}")
        return None

    # Extract content without "Tutorial" header and up to "Tutorial Code"
    content = re.sub(r"^Tutorial\n[-=]+\n", "", content, flags=re.MULTILINE)
    content = re.search(r"(.*?)\nTutorial Code\n[-=]+", content, re.DOTALL)

    if content:
        content = content.group(1).strip()

    # Prepare the translation prompt
    prompt = f"""
    Translate the following tutorial content into {language_code}. Follow these rules:

    - **Markdown Headers and Formatting**:
      -While the format must remain consistent, ensure that the header (e.g. ### Header) is translated into {language_code}. 
      Keep all Markdown elements such as headings (#, ##, ###, etc.) and lists (-) unchanged. 
      Do not modify the structure or formatting of the Markdown content. 
      Translate only the textual content within these elements where appropriate.
      - Keep "Exercise--------" with the same structure but translated to {language_code}.
      - Other headers such as "Tutorial--------" must stay exactly the same in the original language.

    - **Preserve Code Blocks and Formatting**:
      - Leave code examples and indentation unchanged.
      - Do not add backticks (` ``` `) or translate code snippets.

    - **Markdown Structure**:
      - Maintain lists, headings, and links.
      - Do not change URLs or Markdown links.

    - **Translation Scope**:
      - Translate only the explanatory sections.
      - Leave all code and inline comments unchanged.

    Content:
    {content}
    """