Zenn
📑

ドキュメント翻訳プロジェクトを立ち上げると技術のキャッチアップもできる

2022/12/01に公開
Svelte
translation
SvelteKit
idea

Svelte Advent Calendar 2022 1日目の記事です。

前書き

皆さんはSvelteというフロントエンドフレームワークをご存知でしょうか。雑に紹介すると、ReactやVueと同じカテゴリに属するものです。また、SvelteKitというSvelteを使ったアプリケーションフレームワークもあります。こちらはReactにとってのNext、VueにとってのNuxtにあたります。

https://svelte.jp/

https://kit.svelte.jp/

Svelteはパフォーマンスが良く、軽量で、わかりやすく、公式ドキュメントやチュートリアルが充実しているなど様々な面で優れており、Stack Overflow Developer Survey や State of JavaScript などのテック系のサーベイにおいて、該当の部門で1位を取るなど、近年注目を集めています
(もっとSvelteについて細かく紹介したいところですが、 今回の記事の趣旨とは異なるため割愛します)。

当記事では、Svelteのドキュメントの日本語翻訳プロジェクトを立ち上げて取り組んできた結果、Svelteだけでなく周辺技術にもキャッチアップすることができたという私の体験談を紹介させていただきます。

ドキュメント翻訳自体は翻訳対象の技術について詳しくなれるのでそれ自体メリットがありますが、翻訳プロジェクトを立ち上げると他にもメリットがあることをお伝えできれば幸いです。

翻訳をスタートした経緯は以前書いたこちらの記事をご参照ください。
https://zenn.dev/tomoam/articles/6c81ced3fd47b7

サマリ

ドキュメント翻訳プロジェクトを立ち上げると、翻訳作業だけでなく、そのソースコードを読んだりビルドやデプロイ先を管理したりもする。そのため様々な技術に触れる機会を得ることができる。

最初から翻訳する手順やホスティング先を気にすることがないような、翻訳の準備が整っているテクノロジーの場合は、この体験談は当てにならないかもしれません。

経緯

Svelteには素晴らしいi18nライブラリがいくつかありますが(svelte-i18n や Svelte Intl Precompile)、Svelteのドキュメントサイト自体にはその仕組みは入っていません。検討はされていましたが、私たちが翻訳を開始したときから現在に至るまで、SvelteのコアチームはSvelteKitの開発に注力しており、意見をまとめてそれを実装することにリソースを割く余裕はなかったのだと思います。

日本語翻訳プロジェクトでそういった仕組みを入れてコントリビュートしようかとも考えましたが、ReactやVueの日本語翻訳のようにリポジトリをフォークして別サイトとして立ち上げたほうが良いと考えました。

こちらはReactの日本語翻訳をされている方の記事です。技術系のドキュメント翻訳をする方は必見です！
https://zenn.dev/smikitky/articles/0d250f7367eda9

リポジトリをフォークして別サイトで立ち上げるとなると、以下のことを調査・検討しなければなりません。

  1. originからいい感じに追従できるようなforkの方法
  2. ビルド
    • package.json やソースの読み込み
  3. デプロイ
    • 既存がどこにどうやってデプロイしているか
    • デプロイ先のドキュメント読み込み、デプロイ用の設定ファイル修正など
    • もし別のところにデプロイするならその学習が必要
  4. CJK圏固有の問題に対処
    • html タグの lang 属性を ja に変えたり
    • URL のハッシュフラグメントに対応したり
    • IME周りの挙動に対応したり
  5. その他
    • 翻訳側では不要な CI 設定(GitHub Actionsなど)の削除
    • 記事を書いているときには思い出せないなにか
  6. 1~5 について、origin 側で変更された場合に追従していくこと

このように、ドキュメントを翻訳することそのもの以外にも、ビルド・デプロイ周りや言語に関する対応など、サイトを立ち上げるのに必要なことをやらなければなりません。しかも、それを行うのは最初だけではありません。originがなにか変更をするとそれに追従していく必要があります。特にSvelteは、公式サイトを使って色んなプラットフォームを試したりドッグフーディングしたりしているので、色々なものを使う機会に恵まれました。

ここからは、私が触れることになった技術を抜粋して紹介していきたいと思います。

キャッチアップできた技術

Gitのリポジトリ分割(subtree, filter-branch, filter-repo)

翻訳開始当時、Svelteのリポジトリには Svelteのソースコードとドキュメントサイトのソースとコンテンツが1つのリポジトリに入っていました[1]。翻訳対象の .md ファイルが少し深いディレクトリに置かれているためコントリビューターが対象のファイルを探しにくくなり、手間になってしまうかと考えました。

  • 翻訳開始当時の Svelte のリポジトリイメージ
.
├── .github
├── scripts
├── site       # <- ドキュメントサイト用のディレクトリ
│   ├── content
│   │   ├── blog      # <- 翻訳対象のmdファイルがあるディレクトリ
│   │   ├── docs      # <- 翻訳対象のmdファイルがあるディレクトリ
│   │   ├── examples
│   │   ├── faq       # <- 翻訳対象のmdファイルがあるディレクトリ
│   │   └── tutorial  # <- 翻訳対象のmdファイルがあるディレクトリ
│   ├── scripts
│   ├── src
│   ├── static
│   etc...(package.jsonやデプロイ用の設定ファイルなど諸々)
│
├── src
├── test
│
etc...(README.md や package.json など諸々)

https://github.com/svelte-jp/svelte-site-jp/tree/990c21f7f32772f84a14ad36dbae07086883e10d

そのため、上記の site ディレクトリ配下のみ残すように分割してマージがいい感じにできるようにしたいと考えました。ただし、単にcloneして翻訳に使用しないファイルを削除してしまうと origin(svelte公式)からfork先(日本語翻訳用リポジトリ)にマージするのが手間になってしまいます。

そこで、git でそういったことができないか調べ subtree、filter-branch、filter-repo を試し、色々検討した結果、filter-branch[2] を使用するようにしました。

  • filter-branch で site 配下だけを残したリポジトリ
.
├── content
│   ├── blog      # <- 翻訳対象のmdファイルがあるディレクトリ
│   ├── docs      # <- 翻訳対象のmdファイルがあるディレクトリ
│   ├── examples
│   ├── faq       # <- 翻訳対象のmdファイルがあるディレクトリ
│   └── tutorial  # <- 翻訳対象のmdファイルがあるディレクトリ
├── scripts
├── src
├── static
etc...(package.jsonやデプロイ用の設定ファイルなど諸々)

ちょっとすっきり！

普段から git をバリバリ使いこなしている方からすればこういったコマンドは使えて当たり前かもしれませんが、私はそれぞれのコマンドをオプションを試しながらしっかり使ったことがなかったので勉強になりました。また、コマンドの使い方だけでなく、自分以外の方にも貢献してもらうリポジトリでこういったことを検討できたのは良い経験になりました。

余談ですが、今現在はリポジトリを分割しないそのまま fork した状態に戻しました。filter-branch したリポジトリだとマージに一手間かかってしまうのが面倒だったからです。ただ、リポジトリの構成を途中で変えたことでコントリビューターの方々を惑わせてしまったので、反省しています。リポジトリの構成をいじると他の人が困る、ということを学ぶ機会にもなりました。

pnpm

SvelteKitリポジトリには、SvelteKit本体のプロジェクト、ドキュメントサイト用のプロジェクト、各ホスティングサービス向けのadapterプロジェクトなどがあり、いわゆるモノレポになっており、それらをオーガナイズするために pnpm が使用されています。

https://pnpm.io/

日本語翻訳で使用するdependencyやscriptを足したり、個人的にローカルでビルドしたSvelteやViteをkitにリンクさせたりすることがあったので、 pnpm のドキュメントを読み、正しく設定する必要がありました。

これによって pnpm の速さを体感することができ、今では pnpm が使えるところは個人でも業務でも突っ込んでます。また、私はモノレポ自体が未経験だったのですが、その勘所を掴むことができました。

Turborepo

ある日、SvelteKitのリポジトリに Turborepo が導入されました。CI時にキャッシュを使って不必要なビルドを減らす目的で導入されたようです。

https://turbo.build/repo

Turborepoのドキュメントを読みましたが、正直よくわかっていません。日本語翻訳ドキュメントのリポジトリではCIの設定を削除してしまっているのでTurborepoのメリットを感じることができませんでした。とはいえ、仕事でもテストの実行時間を短縮できたら良いとは思っているので要勉強ですね。今の私にわかっているのは turbo run するとかっこよく FULL TURBO と表示されることくらいです。

FlexSearch

Sveltekitの公式サイトにはFlexSearchを活用した全文検索機能が付いています。

https://github.com/nextapps-de/flexsearch

検索、こいつは厄介ですね。英語なら上手く動いても、日本語文章でいい感じに検索できるかはわかりません。そもそも私にとって検索とは「とりあえず Elasticsearch に Kuromoji 入れときゃなんとかなるやろ、あとは詳しい人にお願いしよう」というものだったので、なかなかハードルが高いものでしたです(現在進行系)。

FlexSearch のドキュメントを読んでみましたが、うーん難しい。torkenize の設定を forward から reverse にしたらなんとなく上手く動いてそうに見える・・・いやだめだ・・・トークナイザをいじらないと・・・くそ、俺は検索のことを何もわかってない・・・

というわけでこの本を買いました。歴史の話とかもすごい面白いので検索に困ってない人にもおすすめ。

https://www.lambdanote.com/products/ir-system-ebook

Google Cloud Run

ここからは少しデプロイ先のプラットフォームの話が続きます。

翻訳開始当時、SvelteのドキュメントサイトはGoogle Cloud Runにデプロイされ、CDNはCloudflareでした。

https://cloud.google.com/run/docs/overview/what-is-cloud-run?hl=ja

当時はいわゆるEdgeが今ほど発展していなかったと思います。そのためSvelteの公式サイトでは、SSR/Hydrationをよしなにやるためにサーバーサイドを含むNode.jsアプリを丸ごとコンテナ化してCloud Runにデプロイし、CDNを使ってGoogle Cloudへのアクセス量を減らして無料枠内に収める、みたいな感じで対応していたと思います。

私自身は業務でGoogle Cloudを使用しておりCloud Architectの資格を取得するくらいには経験があったものの、Cloud Runを使ったことはなかったので素振りをする良い機会になりました。

これまた余談ですが、日本語サイトも数日間はCloud Runで運用したものの、「CDNの設定合ってるかな」「これ本当に無料枠に収まるのかな」「いたずらでDoS攻撃とか来ても大丈夫かな」と不安になってしまい、途中でHerokuに移行しました。Cloud Runで運用したいたときは爆速だったのですが、Herokuの無料プランだとレイテンシが結構あり、せっかくSvelteで作られてるのに遅く感じられてしまうのでCloudflare側で色々頑張った覚えがあります。ユーザーが快適にドキュメントを見られないせいで使ってもらえなくなるのは避けたかったので。

そして、後述しますが、現在は公式サイトはVercelでホストされており、日本語翻訳サイトもVercelでホストされています。

Vercel と Netlify

SvelteKitがパブリックベータになった頃、Svelteの公式サイトはVercelに、SvelteKitの公式サイトはNetlifyにホストされるようになりました (後にSvelteKitの公式サイトもVercelに移行)。

https://vercel.com/

https://www.netlify.com/

翻訳サイトもこれに追従するため、それぞれのドキュメントを読み、設定し、デプロイ。どちらも細かいところに手が届くようになっていて感動したのを覚えています。

「Netlifyの無料プランは日本リージョンないから遅い」という噂も確認することができ、ユーザーに近いところにマシンがあることの重要性を体感できたのも収穫でした。

Cloudflare Workers

Svelteチームはドキュメントサイトを使って様々な技術を試しています。Cloudflare Workersもその一例です。

https://workers.cloudflare.com/

Svelteのドキュメントサイトでは、Cloudflare WorkersをCMSのように使用しています。ドキュメントやチュートリアルなどのコンテンツを Workers KV に保存し、Cloudflare Workersで構築したAPIでそれを呼び出す、というような形です。日本語翻訳サイトでも同じように構成しています。

「どうしてわざわざそんなことを？静的なサイトなんだからそんなことしなくても良くない？」と思うかもしれませんが、フレームワークの開発者たちが新しい技術の潮流を確かめるのは重要なことかと思います。新しい機能や今後の方針に影響するからです。

Svelteのドキュメントサイトで行われていることはもちろん、Cloudflare Workersでは他にも様々なことを行うことができます。私はこれを実践してみるまで「Edgeってなに？」状態だったのですが、その凄さの片鱗を垣間見ることができました。

まとめ

もちろん、ドキュメントの翻訳自体も、翻訳対象の技術について詳しくなれるのでおすすめです。
翻訳プロジェクトを立ち上げると、翻訳対象の技術だけでなくその周辺の技術にも触れることができます。

もしかしたらこういった体験ができる翻訳プロジェクトは少ないかもしれません。しかし、手間を減らすにはどうしたらよいか、ユーザーにより良い体験をしてもらうにはどうしたらよいか、コントリビューターが作業しやすいようにするにはどうしたらよいか、そういったことを考えていくと、改善点とそれを解決する手段が見つかるはずで、それが技術のキャッチアップにつながっていくのだと思います。

最後に、Svelteのドキュメントの日本語翻訳はコントリビューターの方々のおかげで実現されていることをお伝えします。この場を借りて、改めてコントリビューターの皆様に感謝を申し上げます。

脚注

  1. 現在はサイトのソースは別のリポジトリになっています ↩︎

  2. git filter-branch は非推奨となっており、コミュニティ代替の git filter-repo を使うと良いみたいです ↩︎

Discussion