Feature-Sliced DesignのドキュメントをCursorで和訳してみたところ、正式な日本語版として採用された
最近、人気になりつつある、フロントエンドアーキテクチャの設計方法論であるFeature-Sliced DesignのドキュメントをCursorコードエディタで翻訳してみたところ、翻訳は正式な日本語版になりました！Cursorでの翻訳過程について本記事で共有したいと思います！
前提
社内では、フロントエンドのアーキテクチャとして、長くbulletproof-reactが使われましたが、コードベースや機能が多くなるに連れて、プロジェクト内のナビゲーションやメンテナンスが必然的に難しくなるという問題がありました。それは主にbulletproof-reactのような解決策がアーキテクチャ設計に関する明確なルールや規約を提供していないからだと思っています。そのコードベースの拡張性を改善できる方法として、Feature-Sliced Design（FSD）導入の提案をしました。そして後ほど、社内の幹部会議で導入が話題に上げられ、最終的に新規プロジェクトにFSDを採用することになりました。
FSDの導入後、ある程度の期間が経ってから、新しいアーキテクチャを使ってみた社内の開発者からのフィードバックが集められ、「学習コストが高い」という声があったものの、「使いやすい」、「機能に関するコードをどこに置けばいいか、迷うのが少なくなった」という意見も結構いただいたので、これでフロント開発のコストが長期的にかなり抑えられるのではないかと思いました。しかし、唯一の難点として残っていたのは、Feature-Sliced Designのドキュメントは英語で書かれたことです。FSDの基礎概念やルールを日本語で説明する記事が割と多く公開されていますが、公式ドキュメントの細かいところやFSD使用例の解説が依然として少ないままなので、英語の苦手なメンバーだと、方法論の学習は少々ハードルが高そうでした。
ChatGPTとかでドキュメントを翻訳するという選択肢がありましたが、いくつかの難点が浮上してしまいました。
- 翻訳に使用される用語の手動修正をできるだけ少なくするため、予めFSDに関する記事一覧をモデルに読み込ませ、学習させてから、翻訳をしたかったけど、ChatGPTで容易にモデルに外部URLの内容を読み込ませることができない。そのステップを省くと、後で「メソドロジー」を「方法論」に修正することや、「層」を「レイヤー」に修正することなどの地獄が待っている
- 翻訳精度を上げるため、できれば翻訳済みで、修正済みのファイルの内容もモデルに参照して欲しかったけど、全部をその都度ChatGPTに貼り付けるのが骨が折れそうだった
それで、その難点を解決する方法がないか、考えてみたところ、社内で大人気のCursorAIコードエディタを使った方法を思いつきました！使用したCursor機能一覧は下記のようです。
-
Docs、サードパーティライブラリのドキュメントをAIに読み込ませるための機能 -
Codebase Answers、コードベース全体に関する質問をAIに投げかけることができる機能
これから詳しく上記の機能を活かした方法について説明します。
翻訳過程
準備
まずは、以下を準備します。
- Cursor（有料プランを使用したが、一部は無料プランでできるかも）
- FSDリポジトリのフォーク
- FSDの正しい用語を参照するためのzenn記事一覧
Cursorの翻訳環境設定
Docsの設定
次は、準備したzenn記事一覧をCursorのDocsに追加します。
AIモデル
ドキュメントのボリュームが比較的に多いので、モデルは安価なgpt-4o-miniにします。
日本語版フォルダの準備
ドキュメントリポジトリをフォークしてから、i18nフォルダ内でenフォルダの複製を作ります。それはコードエディタのgit差分比較のところで、翻訳後、マークダウンの構造が保たれているかどうかなどをチェックするためです。詳しくは後で説明します。
作業自体はenの中で行います。
プロンプト作成
プロンプトには、先ほど作った用語参照用のDocsと翻訳するファイルを入れます。まずは、シンプルなJSONファイルから始めます。
和訳
CMD＋Enterキーを押すことで、Codebase Answers機能が使用され、モデルは前に翻訳されたファイルも参照できるため、用語的な統一感が得られます。上のプロンプトを実行したら、変更されたファイルが表示されます。
ファイル全体が翻訳される場合、チャットからファイル内容をコピーして、ファイルに貼り付けた方が、変更適用ボタンを押して、ファイル更新を待つより早いです。
次は、ドキュメント内で一番大きな2000行以上のマークダウンファイルを翻訳してみましょう。
約1分後、1910行のところで翻訳が止まりました。恐らく、モデルの限界でしょう。でも1910行というのは、大した行数ですね。これから続けるには、少々工夫が必要です。モデルは一つのチャット内で覚えられるコンテキスト量の限界に達しているので、残りの部分は新しいチャットで片付けなければいけません。1910行までのコードをファイルから削除してから、プロンプトを新規チャットで再実行します。翻訳済みの部分を削除することによって、モデルへの負荷を軽減することができます。
完了です！2回目のプロンプトで2000行以上のファイルが完全に翻訳されました。まだまだAIモデルの限界が感じられますが、これからさらにAIの進化で上限が上がるでしょう。最後に、出力された翻訳部分を２つのチャットからコピーして、組み合わせます。
これで和訳に欠けている部分や構造に異常がないかを、git差分を見て、確認しましょう。それはできるのは、日本語版フォルダの準備の段階でenフォルダ内で和訳をすることにしたからです。最初からjaフォルダで翻訳をしたら、前の状態と比較はできなかったですね。
見事に出来ていますね！文章だけでなく、コード内の単語もちゃんと和訳されています。
次はファイル全体を熟読して、不自然なところとかを修正する作業です。このやり方で全部のファイルを翻訳する流れですね。後はi18nの日本語版フォルダをちゃんとenからjaに改名して、en_originをenに、元の名前に戻しておくことです。
最後はi18nの設定に日本語を追加してから、npm run start:jaでローカルサーバーを立ち上げて、翻訳結果を見ましょう。
いいですね！修正済みのコードはこちらで見られます。
フォークからプルリクエストを作成する
後は簡単ですね。訳されたドキュメントでPRを作成して、PRの承認を待つことだけです。
Cursorをドキュメント翻訳に使った感想
CursorとAIの活用は、ライブラリなどのドキュメント翻訳の加速化に非常に役立てるんだなと実感しました！しかし、翻訳自体は、上質であるものの、まだまだAIによる不自然なところがちょこちょこ発生してしまいます。その数少ない不自然なところだけを修正する必要が残っていますね。今回のFSD翻訳は全然完璧から遠いですが、その辺はコミュニティの力で少しずつ改善できればと思います！
最終的に和訳が無事に出来、これで社内のメンバーや社外の開発者には、和訳が少しでもFSDの学習の手助けになれば、嬉しいです！
Discussion