Skip to content

Improve translation prompt guidance #1647

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Sep 3, 2025
Merged

Improve translation prompt guidance #1647

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 29 additions & 3 deletions docs/scripts/translate_docs.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -136,6 +136,27 @@ def built_instructions(target_language: str, lang_code: str) -> str:
- Fenced code blocks delimited by ``` or ~~~, including all comments inside them.
- Link URLs inside `[label](URL)` – translate the label, never the URL.

#########################
## HARD CONSTRAINTS ##
#########################
- Never insert spaces immediately inside emphasis markers. Use `**bold**`, not `** bold **`.
- Preserve the number of emphasis markers from the source: if the source uses `**` or `__`, keep the same pair count.
- Ensure one space after heading markers: `##Heading` -> `## Heading`.
- Ensure one space after list markers: `-Item` -> `- Item`, `*Item` -> `* Item` (does not apply to `**`).
- Trim spaces inside link/image labels: `[ Label ](url)` -> `[Label](url)`.

###########################
## GOOD / BAD EXAMPLES ##
###########################
- Good: This is **bold** text.
- Bad: This is ** bold ** text.
- Good: ## Heading
- Bad: ##Heading
- Good: - Item
- Bad: -Item
- Good: [Label](https://example.com)
- Bad: [ Label ](https://example.com)

#########################
## LANGUAGE‑SPECIFIC ##
#########################
Expand All @@ -159,6 +180,7 @@ def built_instructions(target_language: str, lang_code: str) -> str:
## EXTRA GUIDELINES ##
#########################
{specific_instructions}
- When translating Markdown tables, preserve the exact table structure, including all delimiters (|), header separators (---), and row/column counts. Only translate the cell contents. Do not add, remove, or reorder columns or rows.

#########################
## IF UNSURE ##
Expand All @@ -173,7 +195,11 @@ def built_instructions(target_language: str, lang_code: str) -> str:

1. Read the input markdown text given by the user.
2. Translate the markdown file into {target_language}, carefully following the requirements above.
3. Self-review your translation to ensure high quality, focusing on naturalness, accuracy, and consistency while avoiding unnecessary changes or spacing.
3. Perform a self-review to check for the following common issues:
- Naturalness, accuracy, and consistency throughout the text.
- Spacing inside markdown syntax such as `*` or `_`; `**bold**` is correct whereas `** bold **` is not.
- Unwanted spaces inside link or image labels, such as `[ Label ](url)`.
- Headings or list markers missing a space after their marker.
4. If improvements are necessary, refine the content without changing the original meaning.
5. Continue improving the translation until you are fully satisfied with the result.
6. Once the final output is ready, return **only** the translated markdown text. No extra commentary.
Expand Down Expand Up @@ -208,7 +234,7 @@ def translate_file(file_path: str, target_path: str, lang_code: str) -> None:
code_block_chunks.append(line)
if in_code_block is True:
code_blocks.append("\n".join(code_block_chunks))
current_chunk.append(f"CODE_BLOCK_{(len(code_blocks) - 1):02}")
current_chunk.append(f"CODE_BLOCK_{(len(code_blocks) - 1):03}")
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this is optional, but it's good

code_block_chunks.clear()
in_code_block = not in_code_block
continue
Expand Down Expand Up @@ -250,7 +276,7 @@ def translate_file(file_path: str, target_path: str, lang_code: str) -> None:

translated_text = "\n".join(translated_content)
for idx, code_block in enumerate(code_blocks):
translated_text = translated_text.replace(f"CODE_BLOCK_{idx:02}", code_block)
translated_text = translated_text.replace(f"CODE_BLOCK_{idx:03}", code_block)

# FIXME: enable mkdocs search plugin to seamlessly work with i18n plugin
translated_text = SEARCH_EXCLUSION + translated_text
Expand Down