I added an English version to my blog. After implementing the language switch on the site, I still had to turn 51 technical articles from 2026 into individual English posts. I could write short introductions by hand, but I needed another way to translate long articles full of code and links. So I tried Sarashina and its Translate API.
The API helped me translate the prose. I could not paste its output straight into Hugo, though. Checking the Markdown links, shortcodes, and code examples against the Japanese originals took more work than I expected.
Handling long articles
The Translate API supports Japanese (ja) to English (en). Each request accepts one text value of up to 5,000 Unicode code points, including spaces and line breaks. The sarashina3-translate service was limited to six requests per minute. I read the character count specification and rate limits, split articles at paragraph boundaries, and kept each request below the limit. I spaced out the calls and waited before retrying when I received a 429 response.
A small helper read the API key from SARASHINA_API_KEY. That kept the key out of the articles, repository, and command-line arguments. Before translation, I separated front matter fields such as date and draft. I translated the title, description, and body, then mapped the tags to English names.
At first I excluded fenced code blocks from translation. If an identifier or symbol in executable code changes, its explanation can become inaccurate. I replaced mathematical expressions and inline code with placeholders before sending the prose, then restored them afterward. Once the body was translated, I separately translated Mermaid diagram labels and procedural text blocks.
What broke afterward
Links were the first obvious problem. Sometimes the prose still made sense while the Markdown link syntax disappeared. The API response for this article’s English version also dropped the Markdown links. In other cases, part of a commit ID inside a URL changed. Hugo’s link shortcode sometimes disappeared or became incorrectly nested. In the long Omoikane article, a reference to an HTML tag became raw <script> markup and stopped Hugo’s build. I changed it back to code formatting.
I compared the occurrence counts of URLs and Markdown link destinations in the Japanese and English versions. I also checked mathematical expressions, inline code, shortcodes, and fenced code blocks. I restored missing links using the surrounding paragraphs and manually fixed extra URLs and broken nesting. Finally, I built the site with Hugo Extended 0.164.0 and confirmed that all 51 posts generated English HTML. The changes and CI are in blog PR #137. For example, the English Omoikane article is a separate page with the same date portion in its URL as the Japanese post.
What I learned from this run
My main difficulty was deciding how much of the article structure I could leave to the API. The Translate API returns translated text; its interface does not promise to preserve Markdown or Hugo syntax. For long technical articles, I needed to decide what to protect before making a request and compare the result with the original afterward.
I checked that links and syntax survived and that the site built and displayed the articles. I did not create an evaluation set to score the semantic accuracy of all 51 English translations. When I find an unclear explanation in an individual article, I will check it against the Japanese source and code and correct it.