Sarashina Translate APIでブログの技術記事を英語にしてみた

ブログに英語版を追加した。サイト側の言語切り替えを作ったあと、2026年に書いた技術記事51本を一つずつ英語の記事にする作業が残った。短い案内文だけなら手で書けるが、コードやリンクの多い長文をまとめて訳すには別の方法が欲しい。そこでSarashinaのTranslate APIを使ってみた。

結果から書くと、本文を英語にするところまでは進められた。一方で、返ってきたテキストをそのままHugoへ入れることはできなかった。Markdownのリンク、ショートコード、コード例を原文と照合する作業の方が、思ったより重要だった。

長い記事をどう渡したか

Translate APIはjaからenへの翻訳に対応する。リクエストのtextは一つで、上限は空白や改行も含めてUnicodeのコードポイントで5000文字。利用したsarashina3-translateの制限は1分あたり6リクエストだった。文字数の仕様とレート制限を見て、記事を段落の境界で分け、1回の入力を上限より小さくした。呼び出しの間隔も空け、429が返ったときは待ってから再試行した。

APIキーは環境変数SARASHINA_API_KEYから読む小さなヘルパーに渡した。キーの値を記事やリポジトリ、コマンドの引数へ書かないためだ。翻訳する前に、front matterのdateやdraftなどの設定は取り出しておき、titleとdescription、本文だけを翻訳対象にした。英語側のタグは、既存のタグに対応する表記を選んで組み直した。

本文中のコードフェンスは最初から英訳の対象にしなかった。実行例の識別子や記号が変わると、説明とコードが食い違う。数式とインラインコードも目印に置き換えてから翻訳し、返答後に戻した。Mermaidの図のラベルと、手順を示すtextブロックは、本文を訳し終えたあとに別途英語へ直した。

翻訳後に壊れたもの

最初に目立ったのはリンクだった。本文の意味は通っていても、Markdownのリンク記法だけが消えたり、URL中のコミットIDの一部が変わったりした。この原稿の英語版でも、APIの返答からMarkdownリンクが外れていた。Hugoのlinkショートコードも、消えた箇所と入れ子になった箇所があった。長いOmoikaneの記事では、HTMLタグ名の説明が生の<script>になり、Hugoのビルドが止まった。ここはコード表記に戻した。

そのため、原文と英訳でURLとMarkdownリンク先の出現回数を照合し、数式、インラインコード、ショートコード、コードフェンスも確認した。足りないリンクは前後の段落を見て戻し、余計なURLや壊れた入れ子は手で直した。最後にHugo Extended 0.164.0でビルドし、51本すべての英語HTMLが生成されることを確認した。変更とCIはブログのPR #137に残っている。例えばOmoikaneの記事の英語版は、元記事と同じURLの日付部分を持つ別ページになった。

使ってみて

自分が困ったのは、英訳の一文を作るところより、記事として保ちたい構造をどこまでAPIへ任せられるかだった。Translate APIの応答は翻訳済みのテキストで、MarkdownやHugoの構文を保持する契約ではない。長文の技術記事では、翻訳を呼ぶ前に保護する箇所を決め、返答後に原文と照合する工程が必要だった。

今回はリンクや構文が残っていることと、サイトがビルド・表示できることを確認した。英訳の意味の正確さを全51本について採点する評価セットは作っていない。今後、個々の記事で説明が分かりにくい箇所が見つかれば、日本語の原文とコードを見直して直していく。