We are building a Markdown-aware translation utility that preserves formatting, code blocks, and domain terminology across languages. This helps teams localize developer docs or multilingual application copy without breaking structure. I will show you the exact Python code to run it on Oxlo.ai, where request-based pricing keeps long-document translation costs predictable regardless of file size.
What you'll need
- Python 3.10 or newer
- An Oxlo.ai API key from https://portal.oxlo.ai
- The OpenAI SDK:
pip install openai
Step 1: Verify the connection with a one-off translation
Before building the utility, confirm that the Oxlo.ai endpoint responds correctly. I use Qwen 3 32B here because it handles multilingual reasoning well.
from openai import OpenAI
client = OpenAI(base_url="https://api.oxlo.ai/v1", api_key="YOUR_OXLO_API_KEY")
response = client.chat.completions.create(
model="qwen-3-32b",
messages=[
{"role": "user", "content": "Translate the following text from English to Spanish: 'The API key must be rotated every 90 days.'"},
],
)
print(response.choices[0].message.content)
Step 2: Define the system prompt
A generic translation often strips tone or mangles technical terms. I define a strict system prompt and test it immediately so the model preserves Markdown and leaves inline code untouched.
from openai import OpenAI
client = OpenAI(base_url="https://api.oxlo.ai/v1", api_key="YOUR_OXLO_API_KEY")
SYSTEM_PROMPT = """You are a professional technical translator.
Rules:
1. Preserve all Markdown syntax exactly, including headers, lists, links, and code fences.
2. Do not translate text inside inline code backticks or code blocks.
3. Maintain the original tone: formal, concise, and precise.
4. If a term is ambiguous, choose the most common technical meaning or transliterate if no equivalent exists.
5. Output only the translated text, with no preamble or explanation."""
text = "## Authentication\n\nPass your `API key` in the header. Requests without a valid key will return `401 Unauthorized`."
response = client.chat.completions.create(
model="qwen-3-32b",
messages=[
{"role": "system", "content": SYSTEM_PROMPT},
{"role": "user", "content": f"Translate the following text into Spanish.\n\n{text}"},
],
temperature=0.3,
)
print(response.choices[0].message.content)
Step 3: Build a reusable Translator class
Now I wrap the call in a class that accepts a glossary mapping. This keeps terminology consistent across large documents.
from openai import OpenAI
SYSTEM_PROMPT = """You are a professional technical translator.
Rules:
1. Preserve all Markdown syntax exactly, including headers, lists, links, and code fences.
2. Do not translate text inside inline code backticks or code blocks.
3. Maintain the original tone: formal, concise, and precise.
4. If a term is ambiguous, choose the most common technical meaning or transliterate if no equivalent exists.
5. Output only the translated text, with no preamble or explanation."""
class Translator:
def __init__(self, api_key: str, target_lang: str = "Spanish"):
self.client = OpenAI(base_url="https://api.oxlo.ai/v1", api_key=api_key)
self.target_lang = target_lang
self.model = "qwen-3-32b"
def translate(self, text: str, glossary: dict | None = None) -> str:
glossary_block = ""
if glossary:
glossary_block = "\nUse the following glossary strictly:\n" + "\n".join(
f"{k} -> {v}" for k, v in glossary.items()
)
user_msg = f"Translate the following text into {self.target_lang}.{glossary_block}\n\n{text}"
response = self.client.chat.completions.create(
model=self.model,
messages=[
{"role": "system", "content": SYSTEM_PROMPT},
{"role": "user", "content": user_msg},
],
temperature=0.3,
)
return response.choices[0].message.content.strip()
if __name__ == "__main__":
t = Translator(api_key="YOUR_OXLO_API_KEY")
result = t.translate("The cold start delay is negligible on Oxlo.ai.")
print(result)
Step 4: Add back-translation validation
To catch hallucinations or drift, I pass the translated text through a second pass back into English. If the meaning diverges, I flag it for manual review.
from openai import OpenAI
SYSTEM_PROMPT = """You are a professional technical translator.
Rules:
1. Preserve all Markdown syntax exactly, including headers, lists, links, and code fences.
2. Do not translate text inside inline code backticks or code blocks.
3. Maintain the original tone: formal, concise, and precise.
4. If a term is ambiguous, choose the most common technical meaning or transliterate if no equivalent exists.
5. Output only the translated text, with no preamble or explanation."""
class Translator:
def __init__(self, api_key: str, target_lang: str = "Spanish"):
self.client = OpenAI(base_url="https://api.oxlo.ai/v1", api_key=api_key)
self.target_lang = target_lang
self.model = "qwen-3-32b"
def translate(self, text: str, glossary: dict | None = None) -> str:
glossary_block = ""
if glossary:
glossary_block = "\nUse the following glossary strictly:\n" + "\n".join(
f"{k} -> {v}" for k, v in glossary.items()
)
user_msg = f"Translate the following text into {self.target_lang}.{glossary_block}\n\n{text}"
response = self.client.chat.completions.create(
model=self.model,
messages=[
{"role": "system", "content": SYSTEM_PROMPT},
{"role": "user", "content": user_msg},
],
temperature=0.3,
)
return response.choices[0].message.content.strip()
def validate(self, original: str, translated: str) -> dict:
back_prompt = (
"Translate the following text back into English. "
"Preserve meaning as closely as possible. "
"Output only the back-translated text.\n\n" + translated
)
back = self.client.chat.completions.create(
model=self.model,
messages=[
{"role": "system", "content": "You are a precise back-translation engine."},
{"role": "user", "content": back_prompt},
],
temperature=0.0,
)
back_text = back.choices[0].message.content.strip()
check_prompt = (
f"Original: {original}\nBack-translation: {back_text}\n"
"Does the back-translation convey the same core meaning as the original? "
"Answer ONLY with PASS or FAIL, then a one-sentence reason."
)
check = self.client.chat.completions.create(
model=self.model,
messages=[{"role": "user", "content": check_prompt}],
temperature=0.0,
)
result = check.choices[0].message.content.strip()
status = "PASS" if result.startswith("PASS") else "FAIL"
return {
"back_translation": back_text,
"status": status,
"details": result,
}
if __name__ == "__main__":
t = Translator(api_key="YOUR_OXLO_API_KEY", target_lang="German")
original = "The request-based pricing model is ideal for long-context workloads."
translated = t.translate(original)
validation = t.validate(original, translated)
print("Translated:", translated)
print("Validation:", validation)
Step 5: Process a Markdown file with chunking
Large files exceed context limits if stuffed into a single prompt. I split by double newlines to keep paragraphs intact, translate each chunk, and write the result to a new file. A production version should use a Markdown parser to respect code fences and list blocks.
import os
from openai import OpenAI
SYSTEM_PROMPT = """You are a professional technical translator.
Rules:
1. Preserve all Markdown syntax exactly, including headers, lists, links, and code fences.
2. Do not translate text inside inline code backticks or code blocks.
3. Maintain the original tone: formal, concise, and precise.
4. If a term is ambiguous, choose the most common technical meaning or transliterate if no equivalent exists.
5. Output only the translated text, with no preamble or explanation."""
class Translator:
def __init__(self, api_key: str, target_lang: str = "Spanish"):
self.client = OpenAI(base_url="https://api.oxlo.ai/v1", api_key=api_key)
self.target_lang = target_lang
self.model = "qwen-3-32b"
def translate(self, text: str, glossary: dict | None = None) -> str:
glossary_block = ""
if glossary:
glossary_block = "\nUse the following glossary strictly:\n" + "\n".join(
f"{k} -> {v}" for k, v in glossary.items()
)
user_msg = f"Translate the following text into {self.target_lang}.{glossary_block}\n\n{text}"
response = self.client.chat.completions.create(
model=self.model,
messages=[
{"role": "system", "content": SYSTEM_PROMPT},
{"role": "user", "content": user_msg},
],
temperature=0.3,
)
return response.choices[0].message.content.strip()
def validate(self, original: str, translated: str) -> dict:
back_prompt = (
"Translate the following text back into English. "
"Preserve meaning as closely as possible. "
"Output only the back-translated text.\n\n" + translated
)
back = self.client.chat.completions.create(
model=self.model,
messages=[
{"role": "system", "content": "You are a precise back-translation engine."},
{"role": "user", "content": back_prompt},
],
temperature=0.0,
)
back_text = back.choices[0].message.content.strip()
check_prompt = (
f"Original: {original}\nBack-translation: {back_text}\n"
"Does the back-translation convey the same core meaning as the original? "
"Answer ONLY with PASS or FAIL, then a one-sentence reason."
)
check = self.client.chat.completions.create(
model=self.model,
messages=[{"role": "user", "content": check_prompt}],
temperature=0.0,
)
result = check.choices[0].message.content.strip()
status = "PASS" if result.startswith("PASS") else "FAIL"
return {
"back_translation": back_text,
"status": status,
"details": result,
}
def translate_file(
input_path: str,
output_path: str,
translator: Translator,
glossary: dict | None = None,
):
with open(input_path, "r", encoding="utf-8") as f:
source = f.read()
if source.startswith("---"):
parts = source.split("---", 2)
header = f"---{parts[1]}---"
body = parts[2].strip()
else:
header = ""
body = source
chunks = body.split("\n\n")
translated_chunks = []
for chunk in chunks:
if not chunk.strip():
translated_chunks.append("")
continue
if chunk.strip().startswith("
```
"):
translated_chunks.append(chunk)
continue
translated = translator.translate(chunk, glossary=glossary)
translated_chunks.append(translated)
body_out = "\n\n".join(translated_chunks)
with open(output_path, "w", encoding="utf-8") as f:
if header:
f.write(header + "\n\n")
f.write(body_out)
if __name__ == "__main__":
t = Translator(
api_key=os.environ["OXLO_API_KEY"],
target_lang="Japanese",
)
glossary = {
"request-based pricing": "リクエストベースの課金",
"cold start": "コールドスタート",
}
translate_file("README.md", "README_ja.md", t, glossary=glossary)
print("Done. Check README_ja.md.")
Run it
Set your API key and run the script against a sample Markdown file.
$ export OXLO_API_KEY="sk-oxlo.ai-..."
$ echo -e '## Quick Start\n\nInstall the SDK with `pip install openai`. No cold starts occur on popular models.' > README.md
$ python translator.py
Done. Check README_ja.md.
With the glossary above, the output in README_ja.md should look like this:
## クイックスタート
SDKは `pip install openai` でインストールします。人気モデルではコールドスタートは発生しません。
Wrap-up
Wire the script into a GitHub Action so documentation auto-translates on every push to main. If you need deeper reasoning across long-context documents, swap in kimi-k2.6, or use deepseek-v3.2 on Oxlo.ai to stay within the free tier while you prototype.
Top comments (0)