Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
181 lines (122 loc) · 11.7 KB

CONTRIBUTING.md

File metadata and controls

181 lines (122 loc) · 11.7 KB
description 貢献ガイドライン

貢献ガイドライン

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

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

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

翻訳の進め方

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

翻訳提案の手順

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

  1. このGitHubリポジトリをフォークします。Git submoduleを含むため、リポジトリをgit cloneする際に--recursiveオプションを付けてください。
  2. ドキュメントの実体は、主にMarkdownファイルおよびコンパイラのソースコード内のコメントの2種類から構成されています。それぞれ、下記の注意書きに従って翻訳作業をお願いします。
    • ./crates/typst-library/src/内の.rsファイル群は、Typstのコンパイラのソースコードです。ソースコード内に含まれている、既存のコメントを直接書き換えて翻訳してください。
      • 例1：Reference > Foundationsを翻訳する際は、./crates/typst-library/src/foundations/mod.rsのコメントを編集してください。
      • 例2：Reference > Foundations > Argumentsを翻訳する際は、./crates/typst-library/src/foundations/args.rsのコメントを編集してください。
    • ./docs内のMarkdownファイル群は、Typstのチュートリアルや入門ガイドなど、言語リファレンス以外のページの本体です。既存のMarkdownファイルを直接書き換えて翻訳してください。
    • 上記いずれの場合においても、website/translation-status.jsonの該当箇所を"translated"に変更してください。
  3. 翻訳の際の文体や表記は翻訳ガイドラインを参照してください。
    • 翻訳ガイドラインに最低限沿っているかを確認する補助ツールとしてtextlintを導入しております。Pull Requestが作成されると、GitHub Actionsにてtextlintによる確認が入ります。textlintの処理が警告無く完了するように翻訳文を文章校正してください。
    • ドキュメントの最新バージョンへの追従は管理者が一括で行っているため、日本語ドキュメントと公式ドキュメントのバージョンが異なる場合でも、日本語ドキュメントで管理されている原文を優先してください。
  4. 翻訳作業の途中でも、Draft Pull Requestを作成して、翻訳の進捗状況を共有することもできます。
  5. 翻訳作業が終わったら、Pull Requestを作成し、送信してください。

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

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

技術的な詳細

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

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

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

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

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

TL;DR

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

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

mise trust
mise install

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

mise run generate

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

mise run preview

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

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

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

Note: 以下の内容はmise v2025.5.6に基づいています。内容の不備を発見した場合は、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 installを実行して、miseで管理されているツールをインストールおよびアクティベートします。

mise install

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

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

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

mise run generate-docs

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

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

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

mise run generate-web

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

mise run preview

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

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

mise run generate

文章校正

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

mise run textlint-html

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

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

mise run textlint-md

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

mise run textlint-md-fix

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

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

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

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