{"route":"/ja-JP/about/contributing/","title":"貢献ガイドライン","description":"貢献ガイドライン\n","part":null,"outline":[{"id":"翻訳の進め方","name":"翻訳の進め方","children":[{"id":"翻訳提案の手順","name":"翻訳提案の手順","children":[]},{"id":"技術的な詳細","name":"技術的な詳細","children":[]},{"id":"ローカル環境でwebページを生成","name":"ローカル環境でWebページを生成","children":[{"id":"tl-dr","name":"TL;DR","children":[]},{"id":"miseによる開発環境のセットアップ","name":"miseによる開発環境のセットアップ","children":[]},{"id":"typstのソースコードからドキュメントデータの-jsonファイルを生成","name":"TypstのソースコードからドキュメントデータのJSONファイルを生成","children":[]},{"id":"ドキュメントデータのjsonファイルから-webサイトを生成","name":"ドキュメントデータのJSONファイルからWebサイトを生成","children":[]},{"id":"webサイトの生成までを一括実行","name":"Webサイトの生成までを一括実行","children":[]},{"id":"文章校正","name":"文章校正","children":[]},{"id":"dev-containerによる開発環境のセットアップ","name":"Dev Containerによる開発環境のセットアップ","children":[]}]}]}],"body":{"kind":"html","content":"

貢献ガイドライン

\n

Note: 当プロジェクトのREADMEや「日本語版について」、Typst公式のライセンスやコントリビューション・ガイドもあわせてご参照ください。

\n

Typst日本語ドキュメント翻訳プロジェクトにご興味をお持ちいただき、どうもありがとうございます。

\n

このプロジェクトは、Typst GmbHの許諾を得て、最新の公式のドキュメントより翻訳を行うことで、非公式な日本語ドキュメントを提供することを目的としています。まさに、あなたのようなボランティアの皆様のご協力の元、成り立っています。当ガイドラインをご一読の上、翻訳・校正・提案およびその他の作業にご参加いただければ幸いです。

\n

翻訳の進め方

\n

翻訳はGitHub上の当リポジトリを中心に行います。実際の翻訳作業やそれに対する議論や提案などは、主にGitHubのIssueやPull Request機能を通じて行います。また、Discordサーバー「くみはんクラブ」の#typst-翻訳チャンネルでも、質問の対応などが可能です。

\n

翻訳提案の手順

\n

Warning: ここに記載されている内容は改訂中です。現在の手順は最新のPull Requestを参照してください。

\n
    \n
  1. このGitHubリポジトリをフォークします。Git submoduleを含むため、リポジトリをgit cloneする際に--recursiveオプションを付けてください。
    2. \n
  2. ドキュメントの実体は、主にMarkdownファイルおよびコンパイラのソースコード内のコメントの2種類から構成されています。それぞれ、下記の注意書きに従って翻訳作業をお願いします。\n\n
    3. \n
  3. 翻訳の際の文体や表記は翻訳ガイドラインを参照してください。\n\n
    4. \n
  4. 翻訳作業の途中でも、Draft Pull Requestを作成して、翻訳の進捗状況を共有することもできます。
    5. \n
  5. 翻訳作業が終わったら、Pull Requestを作成し、送信してください。
    6. \n
\n

ご質問などがある場合は、「くみはんクラブ」のDiscordサーバーに参加してご連絡ください。

\n

もちろん、Discordサーバーに参加していない方からのPull Requestも大いに歓迎します。

\n

技術的な詳細

\n

./website/のREADMEを参照してください。

\n

ローカル環境でWebページを生成

\n

当プロジェクトの開発ツールおよびコマンドはmiseで一元管理しています。導入していない場合は、Getting Started | mise-en-placeに従ってインストールしてください。

\n

コマンドラインでの操作を避けたい方やDockerで作業したい方へ向けて、Dev Containerの環境もご用意しております。

\n

Note: Windowsのネイティブ環境で実行する場合には、開発者モードに設定する必要があります。その他Windowsに起因する潜在的なトラブルを回避するため、WindowsユーザーにはWSLやDev Containerの使用を推奨します。

\n

TL;DR

\n

Note: こちらの説明は要約版です。詳細を知りたい場合は、次以降の見出しを参照してください。

\n

当プロジェクトのルートディレクトリに移動し、以下のコマンドを実行します。このコマンドは初回のみ実行する必要があります。

\n
\nmise trust\nmise install\n
\n

Webサイトを再生成するには、以下のコマンドを実行します。

\n
\nmise run generate\n
\n

Webサイトをローカルサーバーでプレビューするには、以下のコマンドを実行します。

\n
\nmise run preview\n
\n

翻訳ガイドラインに従った体裁になっているかどうかを確認するには、以下のコマンドを実行します。

\n
\nmise run textlint-html  # Rustソースコードを翻訳した場合\nmise run textlint-md    # Markdownファイルを翻訳した場合\n
\n

miseによる開発環境のセットアップ

\n

Note: 以下の内容はmise v2025.5.6に基づいています。内容の不備を発見した場合は、Issueを立ててください。

\n

miseが導入されている環境で初めて当プロジェクトのルートディレクトリに移動すると、以下のように構成ファイルを信頼することを求められます。

\n
\nmise ERROR Config file /path/to/typst-jp.github.io/mise.toml is not trusted.\nTrust it with `mise trust`.\nmise ERROR Run with --verbose or MISE_VERBOSE=1 for more information\n
\n

この場合は、指示に従ってmise trustを実行してください。mise trustの詳細は、mise trust | mise-en-placeを参照してください。

\n
\nmise trust\n
\n

次に、mise installを実行して、miseで管理されているツールをインストールおよびアクティベートします。

\n
\nmise install\n
\n

TypstのソースコードからドキュメントデータのJSONファイルを生成

\n

ドキュメントデータのJSONファイルは、typst-docsによりTypstのソースコード内のコメントおよびdocs/にあるMarkdownファイル群から生成されます。

\n

mise run generate-docsを実行すると、ドキュメントデータのJSONファイルがリポジトリルートのdocs.jsonに生成されます。

\n
\nmise run generate-docs\n
\n

ドキュメントデータのJSONファイルからWebサイトを生成

\n

Webサイトの生成にはNode.jsとViteとHonoを使用しています。また、パッケージ管理にBunを使用しています。

\n

mise run generate-webを実行すると、docs.jsonをもとにWebサイトのデータがwebsite/typst-docs-web/dist/に生成されます。

\n
\nmise run generate-web\n
\n

生成されたWebサイトをプレビューするには、mise run previewを実行します。

\n
\nmise run preview\n
\n

Webサイトの生成までを一括実行

\n

mise run generateを実行すると、generate-docsおよびgenerate-webを一括で実行します。

\n
\nmise run generate\n
\n

文章校正

\n

翻訳ガイドラインに従った体裁へと校正するための補助ツールとしてtextlintの設定も整備しております。\nmise run textlint-htmlを実行すると、生成されたWebサイトのHTMLコードをtextlintで校正します。

\n
\nmise run textlint-html\n
\n

現在、Rustのソースコードを直接textlintで解析することはできません。これは、Rustのrustdocに対応したtextlintプラグインがまだ存在しないためです。そのため、当面の対応として、出力されたHTMLファイルをtextlintで解析しています。\nそのため、textlintの警告が出た該当箇所のRustコードを手動で修正して、再度mise run generateを実行してください。\ntextlintの警告内容が不適当であると思われる場合にはIssueやPull Requestにてご報告お願いいたします。

\n

Markdownファイルを翻訳した場合には、mise run textlint-mdを実行します。

\n
\nmise run textlint-md\n
\n

直接textlintで校正するMarkdownファイルに関しては、mise run textlint-md-fixを実行することで、自動修正も可能です。\nファイルを上書きするため、Gitで現状を記録した状態で実施することを推奨します。

\n
\nmise run textlint-md-fix\n
\n

Dev Containerによる開発環境のセットアップ

\n

Dockerコンテナー上に上記と同一の環境を構築して作業することも可能です。\n以下の操作はDockerがインストール済み、かつDockerデーモンを起動していることが前提となります。\nこのプロジェクトではDev Containerもご使用いただけます。\nVisual Studio Codeにおける操作フロー例は以下の通りです。

\n
    \n
  1. Ctrl+Shift+Pを押してから> Dev Containers: Reopen in Containerを実行します。
    2. \n
  2. Webサーバーが起動したらブラウザで http://localhost:5173 にアクセスします。
    3. \n
  3. 翻訳したファイルの変更を反映させるためにはCtrl+Shift+Bで再ビルドしてください。
    4. \n
  4. 体裁を確認したい場合、Ctrl+Shift+Pを押してから> Tasks: Run taskを実行し以下のいずれかを選択します。\n\n
    5. \n
  5. 自動修正を実施したい場合も同様に以下から選択します。\n\n
    6. \n
\n

> Tasks: Run taskはDocker環境でなく、miseで環境構築した際にも使用できます。

"}}