【個人開発】爆速で英語ドキュメントを日本語に翻訳しました【JStack×Next.js×Vercel×Upstash】

はじめに

こんにちは、react-router 好きの @guppy0356 です。

今回は JStack という素敵なフレームワークのドキュメント翻訳プロジェクトについてご紹介します。このプロジェクトを通じて得られた知識や直面した困難、そして新しい気づきを共有できればと思います。

なぜ JStack のドキュメントを翻訳したのか？

JStack は非常に魅力的なフレームワークだと感じたのですが、現在の状況として日本語の情報が不足しています。より多くの日本のエンジニアに JStack の魅力を知ってもらうため、わたしが所属する JISOU のワタナベ氏が発起人となり日本語訳プロジェクトを joschan21 氏に連絡をしました。すると、JStack に日本語訳を追加する時間を取るのが難しそうな回答でした

hey! really appreciate the offer, it means a lot. i’ve got a ton of ideas i’m trying to build out for jstack, and time’s pretty limited — so if we were going to make a japanese version happen, i feel like i’d need to be involved to do it right, and i just don’t have the bandwidth right now. hope that makes sense!

Github Issue: https://github.com/upstash/jstack/issues/67#issuecomment-2785951745

これはもったいないとおもい、わたしが最終課題として新たにプロジェクトを立ち上げて翻訳を行いました

実際に翻訳したドキュメントはこちらで公開しています。

技術スタック

• Vercel
• Next.js
• Upstash Vector
• Github Actions

機能一覧

コンテンツ管理と検索の仕組みは今後のポートフォリオ作成に役立つと考え JStack のドキュメントサイトをリバースエンジニアリングすることで仕組みを理解して、新プロジェクトに組み込むことで定着を図りました。

コンテンツ管理

ドキュメントは content-collections を使って管理していることがわかりました。これはドキュメントを mdx ファイルで作成して、デザインはコンポーネントで管理する方法です。デザインと分けることでドキュメントの作成に集中できる学びがありました。

デザインのコンポーネントは、各 HTML タグにどのコンポーネントを使うか定義を追加していきます。次の例では、a タグは <Link> コンポーネントを使ってあらかじめ tailwind css でマークアップを済ませています。

<MDXContent
  components={{
    a: ({ children, ...props }) => {
      return (
        <Link
          className="inline underline underline-offset-4 text-muted-light font-medium"
          href={props.href ?? "#"}
          target="_blank"
          rel="noopener noreferrer"
          {...props}
        >
          {children}
        </Link>
      )
    },
  }}
  code={document.mdx}
/>

検索

Upstash のベクトルデータベースを使って全文検索を実現してることがわかりました。全文検索は ElasticSearch を使うのがあたりまえでしたがベクトルデータベースを使うのは新しい気付きでした。

プロジェクトで直面した困難

プロジェクトが常に順調だったわけではありません。2 つの困難に直面しました。

1. JStackドキュメントへの多言語切り替え機能の組み込み
   JStackのドキュメントはNext.jsの構造に依存しており、この多言語切り替え機能を組み込むためにはNext.jsの深い理解が不可欠でした。また、ドキュメントをローカルで動かすための環境変数の設定に予想以上の時間がかかりました。JStack自体の使い方に関するドキュメントは充実しているものの、JStackの公式サイトを開発するためのREADMEが不足していたため、この点で苦労しました。
2. Cloudflare Workersへのデプロイ失敗
   ドキュメントにはCloudflare Workersへのデプロイ方法が記載されていましたが、その通りに実行してもデプロイがうまくいきませんでした。ただし、これは私の設定不足が原因の可能性が高いと反省しています。

プロジェクトからの気づき

これらの経験から、いくつかの重要な気づきがありました。

• デプロイは早期から
  デプロイはプロジェクトの終盤にやりがちですが、プロジェクト開始時からGitHub Actionsなどで自動デプロイを設定しておけば、デプロイに関する問題を早期に気づき、対応できたかもしれません。
• ドキュメント翻訳は最高の学習方法
  新しいフレームワークを学ぶ上で、ドキュメントの翻訳は非常に効率的な学習方法だと実感しました。詳細まで読み込み、実際に手を動かすことで、深い理解が得られます。
• Next.jsでのドキュメント作成はポートフォリオになる
  今回のようにNext.jsでドキュメントサイトを構築することは、そのまま自身の技術力を示すポートフォリオになります。特にログイン機能を持たないシンプルなサイトは手軽に作成でき、個人的にも嬉しいポイントでした。

新しい技術への取り組み

今回のプロジェクトでは、いくつかの新しいツールやアプローチも試しました。

• CLINEを使ったマークアップ生成
  私はマークアップ作業が苦手なのですが、AIツールのCLINEを活用することで効率的にマークアップを作成できました。
  • jstack-ja-template
  • 具体的には、以下のようなプロンプトで精度高くマークアップを生成してくれました

@https://jstack.app/docs/introduction/jstack
このサイトのマークアップをつくって

• CLINEによる翻訳のたたき台作成
  翻訳作業もCLINEに依頼しました。完璧な翻訳ではありませんが、たたき台としては十分な品質で、その後の修正作業を大幅に効率化できました。

ここまで読んでくれた方へ

「個人開発で売れるサービスをつくるぞ！」とやっきになりがちなのですが、翻訳サイトをポートフォリオとして開発するのはアリな選択肢です。正しい情報を伝えるために技術検証をするので周辺知識を身につけることができます。わたしも今回の翻訳プロジェクトを通して、CloudFlare Workers や Vercel へのデプロイ方法を手を動かすことで身につけることができました。

わたしは数年前に react を挫折しましたが、いまは AI ツールで苦手な分野は手伝ってもらいながらプロジェクトを進めることができるので「ちょっとやってみるか」と気軽に始めてみてはどうでしょうか。

今後のアクション

JStack の日本語ドキュメントの品質維持と更新に努めていきます 本家の更新があった際には、GitHubのissueを作成してキャッチアップしやすくする仕組みを構築していく予定です

JISOUのメンバー募集中！

プログラミングコーチングJISOUでは、新たなメンバーを募集しています。
日本一のアウトプットコミュニティでキャリアアップしませんか？
興味のある方は、ぜひホームページをのぞいてみてください！
▼▼▼