Typstドキュメント日本語化プロジェクトに参加しよう
はじめに
Typstとは、学術用途のために新たに生まれたマークアップベースの組版システムです。
より詳細な概要はこちらをご参照ください。
実はこのサイト、以下のGitHubリポジトリで有志の手によって翻訳されているものです。
組版システム Typst の非公式な日本語ドキュメントです。Typst GmbH の許諾を得て作成されています。
このリポジトリは中国語版からフォークして作成され、2024年10月時点での最新版である Typst v0.12.0 の公式ドキュメントを元に日本語訳を行います。
この記事は、私がこのリポジトリに対して行ってきた翻訳作業の流れを解説することで、翻訳者やレビュアーを増やしたいというモチベーションのもと作成されたものです。
基本的には貢献ガイドラインをお読みいただければ、作業可能なようにはなっています。
ここでは参加者の拡大を狙ってGitHub初心者もターゲットとして入れたかったため、その行間を埋めるような話をしていきます。
本プロジェクト参加で得られるもの
いきなりやってみましょうと言っても、このコスパやタイパが求められる時代に、実際に手を動かせる人はなかなかいないでしょう。
そのため、はじめにこのTypst翻訳作業で得られるメリットを主張したく思います。
1. Typstを深く理解できる
Typstに限りませんが、学習したことを言語化してアウトプットすることは、その理解を深めます。翻訳作業では正しい翻訳をするために公式ドキュメントを読み込みます。その過程で、流し読みでは気づかなかった機能や構造を把握することが多々あります。
また、ときには直訳ではうまくいかず、自分の言葉に直すこともあるでしょう。このように、学習とアウトプットが同時に、かつ自分で1から書くよりかは格段に楽に行うことができます。
私はこの活動を通じて本家Typstのコントリビューターとなることができました。
2. 英語と日本語の能力が向上する
翻訳作業では当然ながら英語リーディングの能力が身につきます。Typstの公式ドキュメントは短い文が多く、また、多くのネイティブスピーカーの貢献者もいることから、ある程度読みやすい英語になっている感覚です。しかしながら、前述のとおりときには直訳ではわかりにくい文章も混ざっており、翻訳者として英語と日本語ともに言語能力向上の強力なトレーニングとなります。
こう聞くとハードルが高く思う読者も居られるかと思いますが、心配ありません。後述しますが、翻訳に迷ったときにはGitHubやDiscordを通じて同じ活動をしている仲間にヘルプを出し、助言をもらうこともできます。
3. GitHubの使い方がわかる
この読者の中にオープンソースへのコントリビューションをしたことがある人がどの程度居られるでしょうか？想定読者としては単に執筆作業をする人と広く、そうなると自分のソースコードをGitで管理をしている人も実際のところそこまで多くはないと思っています。
また個人的にGit管理をする経験とチームでGitHubを使用することの間には、また一段ギャップがあると考えております。Typstドキュメント日本語化プロジェクトでは、類似の日本語翻訳プロジェクトを参考にして、プロジェクト運用のノウハウが集められております。一方で、少しずつではありますがさらなる改善も進められており、十分に追える速度でその発展を見ることができます。自分にはなかったアイデアにたくさん触れることができ、少なくとも私は大変勉強になっております。
準備
この記事の読者層としてGitとGitHubをなんとなく使える（使ったことがある）くらいのレベルの方を想定しています。すでにGitHubを使えている人は次章のコントリビューションの流れまで読み飛ばしてください。
Git
基本的なGitの環境整備やGitの操作についてはここでは割愛します。以下のGitコマンドが使えることが望ましいです。
- clone
- switch (または checkout)
- add
- commit
- push
上記コマンドが使えなくても、GUIソフトやエディター機能で同等の操作ができれば問題ありません。「Gitの使い方」などでWeb検索をかけると記事や動画がたくさん見つかる思います。未経験者だと情報が多いように感じますが、上記のレベルまでは割とすぐに習得できるはずです。
GitHub
まずはアカウントを作成してください。SSHキーも登録しておき、GitHubへのSSH cloneができる状態にしておきましょう。以下のページを開きましょう。
ログイン状態となっていれば、右上のアイコンが自分のものになっているかと思います。後に説明しますが、この画像のIssues、Pull requests、Forkを使います。（Starは押していただければ喜びます。）
コントリビューションの流れ
意思表明 (任意)
はじめに、どのページの翻訳作業を行うかを検討します。全体の翻訳の進捗具合は以下のIssueで確認できます。 必須ではありませんが、どのページの翻訳に取り組むかを事前にお知らせすることで、他の方と作業がかぶることを防げます。お知らせする方法は2通りあります。
- Issueを立てる
まだ不慣れなうちはこちらの方法を推奨します。
リポジトリのIssuesタブのページにあるNew Issueから「✨ 翻訳ドキュメントの新規追加の提案」のGet startedをクリックしましょう。
タイトルにはどのページを翻訳するかの概要を記入して、対象ドキュメントには本家のURLをコピペしてください。 - Pull Requestを立てる
Pull Requestの出し方はあとで説明しますが、翻訳が完了していない状態でもPull Requestを作成しても構いません。まだ作業完了していないことを周知するためには、Pull Requestの状態をDraftとしてください。
Forkを最新の状態にする
まずForkをまだしていない場合には、リポジトリのForkからForkをしましょう。Copy the main branch onlyにチェックが入ったままで大丈夫です。Forkすると、typst-jpではなく、ご自身のアカウントにあるリポジトリのページが開いているかと思います。
見分け方として、リポジトリ名の下にforked from typst-jp/typst-jp.github.ioという文字があり、そのさらに下にContributeとSync forkのボタンがあることを確認してください。ここでSync forkのボタンを押したときに、Fork元と差分があると教えてもらえますので、それを取り込んでmainブランチを最新の状態としてください。
作業ブランチの作成
Forkしたリポジトリをcloneしましょう。<> CodeからSSHのURLをコピーしてcloneするとよいでしょう。すでにclone済みであればローカルの方をmainブランチにswitchしてpullをするだけでよいです。その後、このmainブランチを元に作業ブランチを作成を作成してください。
git switch main
git pull
git switch -c 作業ブランチ名
作業ブランチ名はご自身が認識できる範囲でご自由につけていただければ大丈夫です。基本的には、Typstドキュメント日本語版から未翻訳のページを選び、そのページを翻訳するものとわかると良いでしょう。どうつけてよいか迷うための方に個人的な名付け方をお示しすると、例えば https://typst.app/docs/reference/model/figure/ を翻訳する場合には、作業ブランチ名をtrans/model-figureなどとしています。
翻訳を行う
該当のファイルを編集してください。翻訳や生成AIなどのツールもどんどん活用いただいてかまいません。
内容については翻訳ガイドラインを参照いただけますと幸いです。レビューが入りますのでそこまで神経質に頑張る必要はありませんが、遵守していただけますとレビュアーが助かります。
翻訳作業自体のコツについては、次章でご説明します。作業が完了したら、作業ブランチに変更をcommitしてForkしたリポジトリにpushしてください。コミット名も不自然のない範囲で自由にしただいて構いません。コミットツリーが参考になるかと思います。
仕上がりの確認
翻訳したページの仕上がりを確認するために、環境が必要となります。
現在、環境構築を3つの方法がありますが、いずれか1つができれば問題ありません。また、あくまでページの仕上がりを確認する目的だけであるため、どうしても難しい場合にはスキップしてしまっても構いません。
miseによる環境構築
コマンドライン操作が苦でなければ一番オススメです。開発環境構築ツールであるmiseを使用します。以下、ネイティブとWSLのUbuntu 22.04にて実行確認を行いました。
前提としてRustをインストールしてください。
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
miseのインストールは以下で行えます。
curl https://mise.run | sh
echo 'eval "$(~/.local/bin/mise activate bash)"' >> ~/.bashrc
source ~/.bashrc
つぎに環境構築を行います。cloneしたディレクトリで以下のコマンドを入力してください。
mise trust
mise install
ページの生成と可視化を同時に行いたい場合には以下のコマンドを実行してください。
mise run generate && mise run preview
生成されたページは http://localhost:8000/docs で確認できます。
もし、コードを編集した場合には、その編集を反映させるために上記のコマンドをCtrl+Cで停止して再度実行したあと、ブラウザを更新してください。
Devcontainerによる環境構築
できるだけGUI操作したい場合にオススメな方法です。DockerとVS Codeをインストールしてください。
Dockerを起動させた状態で、VS Codeの一番左下「><」のような青いボタンを押し「コンテナで再度開く(Reopen in Container)」を選択してください。しばらく待つと環境構築およびページ生成が完了します。VS Codeの右下に通知も来ますが、生成されたページは http://localhost:3000/docs で確認できます（もしプルリクエスト#86が通れば http://localhost:8000/docs になるかもしれません）。コードの編集を反映させるためには、Ctrl+Shift+Pを押して「Tasks: Run Task」から「gen: typst-jp documentation」を実行したあと、ブラウザを更新してください。
ローカル環境を構築
あまりオススメしません。RustとPythonとNode.jsのすべての環境を自身で整えられる人はmiseによる構築ができると思われ、凝ったことをやらないのであればDevcontainerによる構築が楽だからです。うまく行かない場合にレビュアー側で再現チェックするためにも、環境を合わせておくことが望ましいです。ご協力のほどよろしくお願いいたします。
Pull requestを出す
作業ブランチがリポジトリにpushされると、GitHubのページでCompare & pull requestのボタンが現れます。このボタン、もしくはContributeのボタンからプルリクエストを作成してください。
あとは、プルリクエスト上でレビュアーによる確認や議論を経て、typst-jp.github.ioリポジトリーのmainブランチにマージされれば作業完了です。お疲れ様でした。
翻訳作業のコツ
どのページを翻訳すればよいか？
よく見られるところから翻訳していただくと、多くの読者が助かると思います。tutorialやそこにあるリンク先などが考えられます。私は最近は図を表示するためのfigureやimageを翻訳いたしました。
まずは文量が少ないところから参加してみたいという方は、左の目次のリファレンスにある以下のページなどに取り組んでみてはいかがでしょうか？
実はこれら、Definitionsの上だけ翻訳すれば完了となります。
また、Issuesにあるgood first issueもオススメです。翻訳のIssueが減ってきたら私の方でまた選定してgood first issueを足そうと思います。
もちろん、ご自身の好みのページを翻訳していただいても構いません。
どのファイルを編集すればよいか？
貢献ガイドラインの抜粋ですが、書き換える場所はRustコードのコメントアウトの部分か、Markdownファイルを直接書き換えます。
./crates/typst/src/内の.rsファイル群は、Typstのコンパイラのソースコードです。ソースコード内に含まれている、既存のコメントを直接書き換えて翻訳してください。
- 例1：Reference > Foundationsを翻訳する際は、
./crates/typst/src/foundations/mod.rsのコメントを編集してください。- 例2：Reference > Foundations > Argumentsを翻訳する際は、
./crates/typst/src/foundations/args.rsのコメントを編集してください。./docs内のMarkdownファイル群は、Typstのチュートリアルや入門ガイドなど、言語リファレンス以外のページの本体です。既存のMarkdownファイルを直接書き換えて翻訳してください。
具体的にはリファレンスのLIBRARYのファイル一式は1番にあたり、その他は2番の対応になるかと思います。
1番の対応に関する注意としてはmod.rsとはRustのモジュールファイルを意味します。関数によってはfigureのように./crates/typst/src/model/figure.rsだけを編集すれば良い場合もあれば、imageのようにモジュールとして記述したファイル ./crates/typst/src/visualize/image/mod.rs と合わせて、それが使用している ./crates/typst/src/visualize/image/raster.rs も合わせて翻訳する必要がある場合もあります。
そこまで難しく考える必要はなく、翻訳したい公式ドキュメントの文をコピーしてVS CodeのCtrl+Shift+Fやgrepで全ファイル検索をかけてあげれば簡単に見つかります。
翻訳に迷ったときの手段
翻訳ガイドラインで、主要なものを簡単に抜粋すると、
- 「です」「ます」調で、句点は「。」読点は「、」を使用する。
- 和文と欧文の間には半角スペースを挿入しないこと。
- コードやコマンドなどの技術的な表現は原文のままとする。
などが書かれています。
また、Typstの用語をどう翻訳したらよいか迷ったときには、用語集も参考になるかと思います。
また重要なこととして以下を引用します。
本スタイルマニュアルは絶対的なルールではなく、翻訳全体の整合性を保つための基本方針として提供しているものです。そのため、本マニュアルの内容に必ず従う義務はなく、ケース・バイ・ケースで適用して翻訳を行ってください。本マニュアルの内容に疑問がある場合は、IssueやPull Requestなどで他の翻訳者に意見を求めることもできます。
ここにあるように翻訳作業は、他の参加者と相談しながら柔軟に進めることができます。
コニュニケーション手段としては以下が考えられます。
- GitHub
IssueやPull Requestで相談することが推奨されます。情報がGitHubで一元管理されるため、情報がさかのぼりやすく、過去にあった議論の引用も容易です。 - Discord
本プロジェクトの発祥として、「くみはんクラブ」というDiscordがあります。ここにTyspt翻訳チャンネルがあるので、ここに投稿することでも回答が得られるでしょう。しかし、くみはんクラブの参加者でないと閲覧できないため、さかのぼりたい情報であれば要約してGitHubに（だれかが）記載することになります。まとまっていないけど気軽に発信できる、多くの人に通知を飛ばせるという面では非常によい場所です。 - X
いわゆる旧Twitterです。Discord以上に気軽に発信できると思います。メンションなどをしない場合には、プロジェクト参加者に届く保証がないところはデメリットですが、上記と比べると一番広く人に見てもらえるところではあります。
要約すると、連絡の手段はたくさんありますので、やりやすい方法でご相談ください。
おわりに
今回はTypstドキュメント日本語化プロジェクトの紹介と、現状での作業の進め方について共有しました。
Gitが少し触ったくらいの人でも、この記事の手順通りにすれば本プロジェクトに参加できるようになったかと思います。まずはこの情報を元に手を動かしてみてください。実際に体験することでTypstや言語にとどまらず、GitHubを用いたプロジェクト推進の汎用的なノウハウを手に入れることができます。
翻訳作業に慣れてきたら、ぜひレビュアーにもチャレンジいただけますと大変助かります。参加者各々、時期による繁忙があり、使える時間も有限です。いろいろな形で少しでもご参加いただける方々を増やし、冗長性を増すことで絶え間なく技術が受け継がれていくことを心より願っております。この活動を通して、皆様にとっても何かの気づきの一助となれば幸いです。
Discussion