Skip to content

Latest commit

 

History

History
141 lines (91 loc) · 8.39 KB

CONTRIBUTING.md

File metadata and controls

141 lines (91 loc) · 8.39 KB
Raw

貢献ガイドライン

Note

当プロジェクトのREADMEや「はじめに：Typst Japan Communityより」、Typst公式のライセンスやコントリビューション・ガイドも併せてご参照ください。

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

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

翻訳の進め方

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

翻訳提案の手順

Warning

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

  1. このGitHubリポジトリをフォークします。
  2. ドキュメントの実体は、主にMarkdownファイルおよびコンパイラのソースコード内のコメントの2種類から構成されています。それぞれ、下記の注意書きに従って翻訳作業をお願いします。
    1. ./crates/typst/src/内の.rsファイル群は、Typstのコンパイラのソースコードです。ソースコード内に含まれている、既存のコメントを直接書き換えて翻訳してください。
    2. ./docs内のMarkdownファイル群は、Typstのチュートリアルや入門ガイドなど、言語リファレンス以外のページの本体です。既存のMarkdownファイルを直接書き換えて翻訳してください。
  3. 翻訳の際の文体や表記は翻訳ガイドラインを参照してください。ドキュメントの最新バージョンへの追従は管理者が一括で行っているため、日本語ドキュメントと公式ドキュメントのバージョンが異なる場合でも、日本語ドキュメントで管理されている原文を優先してください。
  4. 翻訳作業の途中でも、Draft Pull Requestを作成して、翻訳の進捗状況を共有することができます。
  5. 翻訳作業が終わったら、Pull Requestを作成し、送信してください。

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

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

技術的な詳細

中国語版を参照してください。

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

当プロジェクトはtypst/typstの派生リポジトリであり、Webページを生成するためにはRustが必要です。導入していない場合は、Install Rust - Rust Programming Languageに従ってインストールしてください。

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

TL;DR

Note

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

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

mise trust
mise install

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

mise run generate

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

mise run preview

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

Note

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

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

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

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

mise trust

miseの設定ファイルでPythonのvirtualenvの自動アクティベートを有効にしていますが、この時点では.venv/ディレクトリが作成されていないため、WARNが発生するはずです。

mise trusted /path/to/typst-jp.github.io/.mise.toml
mise WARN  no venv found at: /path/to/typst-jp.github.io/.venv

To create a virtualenv manually, run:
python -m venv /path/to/typst-jp.github.io/.venv

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

mise install

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

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

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

mise run generate-docs

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

Webサイトの生成にはPythonとJinja2を使用しています。また、パッケージ管理にuvを使用しています。

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

mise run generate-web

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

mise run preview

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

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

mise run generate

Dev Containerについて

Warning

Dev Containerは現在miseに対応していません。そのため、Dev Containerを使用する場合は、.mise.tomlを参考に手動で上記の手順を実行してください。

上記のローカル環境を構築するDockerfileも整備しております。詳細は.devcontainer/README.mdをご参照ください。