Implementation:Openai Openai agents python Translate Docs
| Knowledge Sources | |
|---|---|
| Domains | Documentation, Internationalization, Build_Tooling |
| Last Updated | 2026-02-11 00:00 GMT |
Overview
A CLI script that translates the SDK's English documentation into Japanese, Korean, and Chinese using the OpenAI API, with chunking, concurrency, and git-based staleness detection.
Description
The translate_docs.py script is a procedural Python utility that automates the translation of the OpenAI Agents SDK's Markdown documentation into three target languages: Japanese (ja), Korean (ko), and Chinese (zh). It uses the OpenAI API (via the openai Python client) to perform each translation, sending carefully constructed system prompts that include do-not-translate term lists, language-specific term mappings, and detailed formatting rules for preserving Markdown structure.
The script employs a chunking strategy where each source file's content is split by code blocks and section headers before being sent for translation. Code blocks are extracted and replaced with CODE_BLOCK_NNN placeholders so they are not translated, then reinserted after translation. This approach preserves code fidelity while allowing the model to focus on prose. When ENABLE_SMALL_CHUNK_TRANSLATION is True, chunks are further split at section boundaries to stay within a configurable line limit.
Concurrency is managed via ThreadPoolExecutor with up to 6 parallel workers. A git-based staleness check (git_last_commit_timestamp) compares the last commit timestamps of the English source and its Japanese counterpart to skip files whose translations are already up to date. The script supports both full-directory traversal and targeted file translation via --file and --file-list arguments, and it operates in either only-changes or full mode.
Usage
Use this script when you need to regenerate or update the translated documentation for the SDK. It is typically run as part of a CI/CD pipeline or manually by a maintainer after English documentation is updated. The --mode only-changes flag (default) ensures only stale translations are regenerated, saving API costs and time. The --file and --file-list arguments allow targeted translation of specific pages.
Code Reference
Source Location
- Repository: Openai_Openai_agents_python
- File: docs/scripts/translate_docs.py
- Lines: 1-527
Signature
def translate_file(file_path: str, target_path: str, lang_code: str) -> None: ...
def translate_single_source_file(
file_path: str, *, check_translation_outdated: bool = True
) -> None: ...
def translate_source_files(
file_paths: list[str], *, check_translation_outdated: bool = True
) -> None: ...
def built_instructions(target_language: str, lang_code: str) -> str: ...
def main(): ...
Import
# CLI invocation (not imported as a library)
# python docs/scripts/translate_docs.py
I/O Contract
Inputs
| Name | Type | Required | Description |
|---|---|---|---|
| --file | str (repeatable) | No | Specific file(s) to translate, relative to the docs directory |
| --file-list | str | No | Path to a newline-delimited file containing paths to translate |
| --mode | str ("only-changes" or "full") | No | Translation mode; "only-changes" (default) skips up-to-date translations |
| OPENAI_API_KEY | env var | Yes | API key for the OpenAI client |
| OPENAI_MODEL | env var | No | Model to use (defaults to "gpt-5.2") |
Outputs
| Name | Type | Description |
|---|---|---|
| Translated .md files | Markdown files | Written to docs/{lang_code}/ directories (ja/, ko/, zh/) mirroring the source structure |
| stdout | Console output | Progress messages indicating which files are being translated or skipped |
Usage Examples
Translate All Changed Documentation
python docs/scripts/translate_docs.py --mode only-changes
Translate a Specific File
python docs/scripts/translate_docs.py --file docs/quickstart.md
Translate All Documentation (Full Mode)
python docs/scripts/translate_docs.py --mode full
Translate Files from a List
python docs/scripts/translate_docs.py --file-list changed_files.txt