Skip to content

Conversation

@3w36zj6
Copy link
Member

@3w36zj6 3w36zj6 commented Oct 2, 2025

このPRでは、「Typstドキュメント日本語版」のプロジェクトそのものについてを紹介するセクションを追加します。プロジェクトそのものについての説明を一元管理することによってメンテナンスが簡単になり、Webサイトの利用者にも情報を伝えやすくなると考えます。

@3w36zj6 3w36zj6 requested a review from Copilot October 2, 2025 13:19
Copy link
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull Request Overview

This PR adds a new "About" section to the Japanese Typst documentation website to centralize information about the translation project itself. This reorganization improves maintainability and makes project information more accessible to users.

  • Adds a new "About" section with project overview and contribution guidelines
  • Reorganizes the main overview page to reference the new About section
  • Updates README to focus on project description rather than detailed contributor information

Reviewed Changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 1 comment.

Show a summary per file
File Description
docs/about/welcome.md New main About page with project overview and FAQ
docs/about/contributing.md Symlink to CONTRIBUTING.md for contribution guidelines
docs/about/translating_guidelines.md Symlink to TRANSLATING_GUIDELINES.md for translation guidelines
docs/src/lib.rs Adds about_pages function and integration
docs/src/link.rs Adds $about link resolver
docs/overview.md Simplified to reference new About section
website/translation-status.json Adds translation status for new About pages
docs/src/html.rs Adds LinkType::Shortcut support
CONTRIBUTING.md Adds frontmatter for markdown processing
TRANSLATING_GUIDELINES.md Adds frontmatter for markdown processing
README.md Streamlined project description and contributor section

Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.

## FAQ

### 機械翻訳やLLMの性能が上がっている中で、なぜ人力で翻訳するのですか?

Copy link

Copilot AI Oct 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The first FAQ question about machine translation vs human translation is missing an answer. This leaves the FAQ section incomplete and unhelpful to users.

Suggested change
機械翻訳や大規模言語モデル(LLM)は近年大きく進歩していますが、専門的な用語や文脈、ニュアンスの正確な伝達、文化的な配慮などの点で、まだ人間の翻訳者には及びません。特に技術文書では、誤訳や曖昧な表現がユーザーの混乱や誤解につながる可能性があります。そのため、本プロジェクトでは品質を重視し、原文の意図や日本語としての自然さを担保するために人力で翻訳・校正を行っています。機械翻訳も参考にしつつ、最終的な品質管理は人間が担っています。

Copilot uses AI. Check for mistakes.
ご質問などがある場合は、[「くみはんクラブ」のDiscordサーバー](https://discord.gg/9xF7k4aAuH)に参加してご連絡ください
このプロジェクトは、上流の[typst/typst](https://github.com/typst/typst)を含めた全ての貢献者によって支えられています

## 翻訳参加者
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

メンテナーの一覧表示を手動で管理するのはメンテナンスの観点で面倒なので、外部サービスを利用する形に変更しました。
上流の貢献者が混ざった形で表示されますが、そもそも上流ありきのプロジェクトであることと、直接の貢献者はPull Requestの一覧で確認できるため問題はないと思います。管理者についてはCODEOWNERSファイルのように宣言的に管理する方が望ましいです。

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

コミットを伴わない貢献者の区分があるので、「日本語版について」のページに簡単なクレジット表記をする方針が良い気がします。

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

英語ドキュメントを別ファイルとして分離すると、内容が更新されずに放置される懸念があり、メンテナンスの観点で面倒なため、READMEに日本語と英語を併記する形に変更しました。


実際に作動している Web 版は、以下の URL から閲覧できます。
> https://typst-jp.github.io/docs/
プロジェクトの詳細は、[日本語版について](https://typst-jp.github.io/docs/about/)をご覧ください。
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

メンテナンスの観点でREADMEの内容は最低限とし、Webサイトの「日本語版について」に誘導する形に変更しました。


> [!NOTE]
> For English version, please refer to [README.en.md](README.en.md).
[Typst Documentation](https://typst.app/docs/)のコミュニティ主導の日本語版。
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

「非公式」という表現だけでは誤解を招く懸念があるため、「コミュニティ主導の」という表現にしています。


## FAQ

### 機械翻訳やLLMの性能が上がっている中で、なぜ人力で翻訳するのですか?
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

個人的にこのセクションは書いておきたいと考えていますが、良い文章の案はありますでしょうか?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilotの案が大体良さそうですが、それに加えてLLM関連サービスがウェブ検索して回答を作成するようになっていることから日本語ドキュメントを作成しておくと日本語の回答がより安定するという恩恵が受けられるという点があります。

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

個人的には、シンプルに、読者が各々で機械翻訳やLLMを使用しなくても、直接日本語情報を参照できることも大きいと思います。これはTypstに触れる心理的ハードルを下げ、日本語ユーザーの増加を促進できます。結果として日本語ユーザーが増えれば、日本語特有の組版機能や利用事例の改善にもつながります。

もう一点としては、用語集にあるように、この活動で(当コミュニティ内ではありますが)専門用語や表現を統一し、日本語でTypst情報を共有できる言葉の基盤を作れます。これにより質問・解説記事・教材なども整合性を保ちやすくなるはずです。

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

具体的には以下のような文ではいかがでしょうか?

Suggested change
### 機械翻訳やLLMの性能が上がっている中で、なぜ人力で翻訳するのですか?
### 機械翻訳や大規模言語モデル(LLM)の性能が上がっている中で、なぜ人力で翻訳するのですか?
機械翻訳やLLMは近年大きく進歩していますが、専門的な用語や文脈、ニュアンスの正確な伝達、文化的な配慮などの点で、まだ人間の翻訳者には及びません。
特に技術文書では、誤訳や曖昧な表現がユーザーの混乱や誤解につながる可能性があります。
そのため、本プロジェクトでは品質を重視し、原文の意図や日本語としての自然さを担保するために人力で翻訳・校正を行っています。
機械翻訳も参考にしつつ、最終的な品質管理は人間が担っています。
日本語を第一言語とするユーザーは、機械翻訳を介さずに直接情報へアクセスできるようになり、Typstに触れる心理的なハードルが下がります。
その結果、日本語ユーザーの増加が期待され、日本語特有の組版機能や利用事例の改善にもつながる可能性があります。
また、この活動を通じて(当コミュニティ内ではありますが)専門用語や表現を統一し、日本語でTypstの情報を共有できる言葉の基盤を築いています。
これにより、質問・解説記事・教材などの整合性を保ちやすくなり、Typst日本語ユーザー全体の理解が深まります。
さらに、近年のLLMはウェブ上の情報を参照して回答を生成する傾向があるため、日本語ドキュメントを整備しておくこと自体が、将来的にLLMによる日本語回答の質向上にも寄与します。


ご不明な点があれば、[くみはんクラブ]のDiscordサーバーにてお気軽にご連絡ください。

## FAQ
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

プロジェクトの知名度が上がってきたことを踏まえて、追加で書いておくべきだと思われる内容があればご教示ください。

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

いまいまは特に思いつきません。

[くみはんクラブ]: https://discord.gg/9xF7k4aAuH
[Typst Documentation]: https://typst.app/docs/

[Typstドキュメント日本語版]」は、組版全般の日本語での議論や情報交換のためのDiscordサーバー「[くみはんクラブ]」の有志によって構成された「[Typst Japanese Community]」が、[Typst GmbH](https://typst.app/legal/) の許諾を得た上でメンテナンスしている、Typstの公式ドキュメント「[Typst Documentation]」のコミュニティ主導の日本語版です。
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

プロジェクトの成り立ちを知らない人向けの文章を想定していますが、良い言い回しがあればご指摘ください。

このWebサイトは、[Typst GmbH](https://typst.app/legal/) の許諾を得て、非公式日本語コミュニティ「[Typst Japanese Community](https://github.com/typst-jp/)」のボランティアたちが[公式ドキュメント](https://typst.app/docs/)を翻訳したものです。まだ翻訳途上ですので、翻訳されていない部分や誤訳などがたくさんあり、また情報が古くなる可能性もあるため、ご了承ください。最新の情報は[公式ドキュメント](https://typst.app/docs/)をご覧ください。ただし、本Webサイトには、公式ドキュメントにはない日本語の組版に特化した情報やコンテンツも掲載される予定です。

皆様がTypstをご利用になる上で、本サイトの情報が一助になれば幸いです。
「Typstドキュメント日本語版」のプロジェクトの詳細は、[日本語版について]($about)をご覧ください。
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

READMEと同様にメンテナンスの観点で文章は最小限にしています。

@3w36zj6
Copy link
Member Author

3w36zj6 commented Oct 2, 2025

「貢献ガイドライン」と「翻訳ガイドライン」については、一旦シンボリックリンクで/docs/配下に配置しました。
これらはWebサイト上以外の方法で読まれることを想定しているため、サイト内リンクの省略記法を使用していませんが、Webサイト上でのみ読まれることを想定してファイルを移動することもできると思います。こちらご意見はありますでしょうか?


[Typstドキュメント日本語版]」は、組版全般の日本語での議論や情報交換のためのDiscordサーバー「[くみはんクラブ]」の有志によって構成された「[Typst Japanese Community]」が、[Typst GmbH](https://typst.app/legal/) の許諾を得た上でメンテナンスしている、Typstの公式ドキュメント「[Typst Documentation]」のコミュニティ主導の日本語版です。

本プロジェクトは現在進行中のため、未翻訳の箇所や誤訳が残っている場合があります。また、情報が古くなることもあるため、バージョン情報にはご注意ください。ご利用の際は[Typst Documentation]の最新情報とあわせてご参照ください。
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

各ページの「原文(英語)を開く」リンクを教えてあげた方が親切ですかね?
将来的に仕様が変わる懸念があれば依存関係は作らない方が良いような気もしますが。

「ご利用の際は」→「必要に応じて」に変更した意図は、必須の感じを薄れさせたかったからです。
序文で「本プロジェクトは現在進行中のため、未翻訳の箇所や誤訳が残っている場合があります。」と主張しているため、最後の文はオプションとして、そこまで強く言わなくてもよいかなと思った次第です。

Suggested change
本プロジェクトは現在進行中のため、未翻訳の箇所や誤訳が残っている場合があります。また、情報が古くなることもあるため、バージョン情報にはご注意ください。ご利用の際は[Typst Documentation]の最新情報とあわせてご参照ください。
本プロジェクトは現在進行中のため、未翻訳の箇所や誤訳が残っている場合があります。また、情報が古くなることもあるため、バージョン情報にはご注意ください。必要に応じて、各ページの「原文(英語)を開く」から[Typst Documentation]の最新情報とあわせてご参照ください。

@kimushun1101
Copy link
Member

「貢献ガイドライン」と「翻訳ガイドライン」については、一旦シンボリックリンクで/docs/配下に配置しました。 これらはWebサイト上以外の方法で読まれることを想定しているため、サイト内リンクの省略記法を使用していませんが、Webサイト上でのみ読まれることを想定してファイルを移動することもできると思います。こちらご意見はありますでしょうか?

ひとまず、こちらの対応で問題ないと思います。
基本的にGitHubを使う人がGitHubやクローンしたソースコードを見ることで想定されているものだと思います。Webサイト上で見ることはあくまでオプションという立ち位置でよいと思います。オプションとはいえアクセスがしやすいのは大変助かります。

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants