docs: 貢献ガイトと翻訳ガイドを分割 (#82)

Co-authored-by: Shunsuke KIMURA <[email protected]>

CONTRIBUTING.md

@@ -1,4 +1,4 @@
-# 翻訳ガイドライン
+# 貢献ガイドライン
 
 > [!NOTE]
 > 当プロジェクトの[README](./README.md)や「[はじめに：Typst Japan Communityより](https://typst-jp.github.io/docs/)」、[Typst公式](https://typst.app/)の[ライセンス](https://github.com/typst/typst/blob/main/LICENSE)や[コントリビューション・ガイド](https://github.com/typst/typst/blob/main/CONTRIBUTING.md)も併せてご参照ください。
@@ -7,22 +7,22 @@ Typst日本語ドキュメント翻訳プロジェクトにご興味をお持ち
 
 このプロジェクトは、[Typst GmbH](https://typst.app/legal/)の許諾を得て、最新の[公式のドキュメント](https://typst.app/docs/)より翻訳を行うことで、非公式な日本語ドキュメントを提供することを目的としています。まさに、あなたのようなボランティアの皆様のご協力の元、成り立っています。当ガイドラインをご一読の上、翻訳・校正・提案及びその他の作業にご参加いただければ幸いです。
 
-この翻訳ガイドラインは、翻訳に参加する皆様に、翻訳の進め方に対する説明やより良質な翻訳を行うためのガイダンスを提供します。
-
 ## 翻訳の進め方
 
 翻訳は[GitHub上の当リポジトリ](https://github.com/typst-jp/typst-jp.github.io)を中心に行います。実際の翻訳作業やそれに対する議論や提案などは、主にGitHubの[Issue](https://github.com/typst-jp/typst-jp.github.io/issues)や[Pull Request](https://github.com/typst-jp/typst-jp.github.io/pulls)機能を通じて行います。また、[Discordサーバー「くみはんクラブ」](https://discord.gg/9xF7k4aAuH)の`#typst-翻訳`チャンネルでも、質問の対応や合意の形成などを行うことがあります。
 
 ### 翻訳提案の手順
 
+> [!WARNING]
+> ここに記載されている内容は改訂中です。現在の手順は最新の[Pull Request](https://github.com/typst-jp/typst-jp.github.io/pulls?q=sort%3Aupdated-desc+is%3Apr+is%3Aopen)を参照してください。
+
 1. このGitHubリポジトリをフォークします。
-2. ドキュメントの実体は、主にMarkdownおよびYAMLの2種類のファイルから構成されています。それぞれ、下記の注意書きに従って翻訳作業をお願いします。
-    1. `./docs/i18n/**/`内のYAMLファイル群は、Typstの言語リファレンスの本体です。その中に含まれている、**既存の`*-ja.yaml`ファイルを直接書き換えて翻訳してください**。**`*-en.yaml`や`*-zh.yaml`は翻訳しないでください**。
-        - 例：[Reference > Model](https://typst.app/docs/reference/model/)を翻訳する際は、`./docs/i18n/category/model-ja.yaml`を編集してください。`model-en.yaml`や`model-zh.yaml`は放置してください。
+2. ドキュメントの実体は、主にMarkdownファイルおよびコンパイラのソースコード内のコメントの2種類から構成されています。それぞれ、下記の注意書きに従って翻訳作業をお願いします。
+    1. `./crates/typst/src/`内の`.rs`ファイル群は、Typstのコンパイラのソースコードです。ソースコード内に含まれている、**既存のコメントを直接書き換えて翻訳してください**。
+        - 例1：[Reference > Foundations](https://typst.app/docs/reference/foundations/)を翻訳する際は、`./crates/typst/src/foundations/mod.rs`のコメントを編集してください。
+        - 例2：[Reference > Foundations > Arguments](https://typst.app/docs/reference/foundations/arguments/)を翻訳する際は、`./crates/typst/src/foundations/args.rs`のコメントを編集してください。
     2. `./docs`内のMarkdownファイル群は、Typstのチュートリアルや入門ガイドなど、言語リファレンス以外のページの本体です。**既存のMarkdownファイルを直接書き換えて翻訳してください**。
-    それに加えて、`./docs/src/lib.rs`ファイルの[`urlify`関数](https://github.com/search?q=repo%3Atypst-jp/typst-jp.github.io%20urlify&type=code)を編集して、中国語版の記事タイトルを日本語版のものに書き換えてください。このプロセスを抜かすと、WebページのURLが正しく生成されません。
-    3. 「サードパーティパッケージ」のページの翻訳を追加する場合は、`./static/assets/index2ja.json`も編集する必要があります。
-3. 翻訳の際は、[後述のガイドライン](#スタイルマニュアル)を参照し、[v0.12.0時点での公式ドキュメント](https://github.com/typst/typst/tree/v0.12.0/docs)から翻訳してください。
+3. 翻訳の際の文体や表記は[翻訳ガイドライン](./TRANSLATING_GUIDELINES.md)を参照してください。ドキュメントの最新バージョンへの追従は管理者が一括で行っているため、日本語ドキュメントと公式ドキュメントのバージョンが異なる場合でも、日本語ドキュメントで管理されている原文を優先してください。
 4. 翻訳作業の途中でも、Draft Pull Requestを作成して、翻訳の進捗状況を共有することができます。
 5. 翻訳作業が終わったら、Pull Requestを作成し、送信してください。
 
@@ -139,55 +139,3 @@ mise run generate
 > Dev Containerは現在miseに対応していません。そのため、Dev Containerを使用する場合は、`.mise.toml`を参考に手動で上記の手順を実行してください。
 
 上記のローカル環境を構築するDockerfileも整備しております。詳細は[.devcontainer/README.md](.devcontainer/README.md)をご参照ください。
-
-## スタイルマニュアル
-
-スタイルマニュアルでは、当プロジェクトにおける翻訳の品質確保のための、統一したスタイルの参照基準を提供します。具体的には、基本、文体、表記、用語の4つの観点から、翻訳の際に留意すべき事項を示します。
-
-本スタイルマニュアルは絶対的なルールではなく、翻訳全体の整合性を保つための基本方針として提供しているものです。そのため、本マニュアルの内容に必ず従う義務はなく、ケース・バイ・ケースで適用して翻訳を行ってください。本マニュアルの内容に疑問がある場合は、IssueやPull Requestなどで他の翻訳者に意見を求めることもできます。
-
-### 基本
-
-1. 翻訳は、原則として説明文章や表などに限ります。コードやコマンドなどの技術的な表現は、原文のままとします。
-3. コード記述例の中に出てくる英文のコメントは、日本語に翻訳する必要はありません。
-4. 既存の翻訳を参照し、一貫性を保つようにしてください。
-5. 疑問点、不明点などがある場合は、必要に応じて、積極的にIssuesやDiscordなどで議論・相談してください。
-6. 構成や段分けなどについては、原文の構成をなるべく保つようにしてください。
-
-### 文体
-
-文体については、以下のガイドラインに従ってください。
-
-1. 基本的に「です」「ます」調の敬体を使用すること。ただし、引用、見出し、箇条書きなどに関しては、その限りではありません。
-2. 一般的に用いられる現代日本語共通語に基づき、平易的な表現を心がけること。
-
-### 表記
-
-約物および日本語の表記については、以下のルールに従ってください。
-
-1. 和欧混植がなされている訳文において、和文と欧文の間には半角スペースを手動で挿入しないこと。
-2. 和文において、句点は「。」を、読点は「、」を使用し、他の記号も原則として全角を使用すること。
-3. コロン「：」やセミコロン「；」は、原則として使用しないこと。ただし、「例：」など、文中以外で用いる場合はその限りではありません。
-4. 数字や欧文（ラテン文字、キリル文字、ギリシア文字など）は、原則として半角を使用すること。
-5. 原則、現代仮名遣いおよび常用漢字表に基づいた表記を使用すること。送り仮名や仮名書き、ひらがな・カタカナの使い分けは、一般的な書き方に従ってください。ただし、引用、特定の用語や固有名詞については、その限りではありません。
-
-### 用語
-
-用語については、以下のガイドラインに従ってください。
-
-1. [用語集](https://typst-jp.github.io/docs/glossary/)を参照すること。
-    1. 用語集にあってかつ適切と思われる場合は、その通りに翻訳してください。
-    2. 用語集にあっても不適切と思われる場合は、IssueやDiscordで相談してください
-    3. 必要と思われるのに用語集にない場合は、既存の翻訳を参照し、追加を提案してください。
-2. 用語と用語でないものを、柔軟に見分けて訳し分けること。
-3. 現代日本語の一般的な、わかりやすい用語を使用すること。
-
-### 参考
-
-* [JTFスタイルガイド](https://www.jtf.jp/tips/styleguide)
-* [ウィキペディア日本語版のスタイルマニュアル](https://ja.wikipedia.org/wiki/Wikipedia:%E3%82%B9%E3%82%BF%E3%82%A4%E3%83%AB%E3%83%9E%E3%83%8B%E3%83%A5%E3%82%A2%E3%83%AB)
-* [ウィキペディア日本語版の表記ガイド](https://ja.wikipedia.org/wiki/Wikipedia:%E8%A1%A8%E8%A8%98%E3%82%AC%E3%82%A4%E3%83%89)
-* [Microsoft Localization Style Guides](https://learn.microsoft.com/ja-jp/globalization/reference/microsoft-style-guides)
-* [WordPress 翻訳ハンドブック](https://ja.wordpress.org/team/handbook/translation/)
-* [Vue.js 公式サイト日本語翻訳ガイド](https://github.com/vuejs-translations/docs-ja/blob/main/.github/CONTRIBUTING.md)
-* [ja.react.dev 翻訳スタイルガイド](https://github.com/reactjs/ja.react.dev/wiki/%E7%BF%BB%E8%A8%B3%E3%82%B9%E3%82%BF%E3%82%A4%E3%83%AB%E3%82%AC%E3%82%A4%E3%83%89)

TRANSLATING_GUIDELINES.md

@@ -0,0 +1,55 @@
+# 翻訳ガイドライン
+
+この翻訳ガイドラインは、翻訳に参加する皆様に、翻訳の進め方に対する説明やより良質な翻訳を行うためのガイダンスを提供します。
+
+## スタイルマニュアル
+
+スタイルマニュアルでは、当プロジェクトにおける翻訳の品質確保のための、統一したスタイルの参照基準を提供します。具体的には、基本、文体、表記、用語の4つの観点から、翻訳の際に留意すべき事項を示します。
+
+本スタイルマニュアルは絶対的なルールではなく、翻訳全体の整合性を保つための基本方針として提供しているものです。そのため、本マニュアルの内容に必ず従う義務はなく、ケース・バイ・ケースで適用して翻訳を行ってください。本マニュアルの内容に疑問がある場合は、IssueやPull Requestなどで他の翻訳者に意見を求めることもできます。
+
+### 基本
+
+1. 翻訳は、原則として説明文章や表などに限ります。コードやコマンドなどの技術的な表現は、原文のままとします。
+3. コード記述例の中に出てくる英文のコメントは、日本語に翻訳する必要はありません。
+4. 既存の翻訳を参照し、一貫性を保つようにしてください。
+5. 疑問点、不明点などがある場合は、必要に応じて、積極的にIssuesやDiscordなどで議論・相談してください。
+6. 構成や段分けなどについては、原文の構成をなるべく保つようにしてください。
+
+### 文体
+
+文体については、以下のガイドラインに従ってください。
+
+1. 基本的に「です」「ます」調の敬体を使用すること。ただし、引用、見出し、箇条書きなどに関しては、その限りではありません。
+2. 一般的に用いられる現代日本語共通語に基づき、平易的な表現を心がけること。
+
+### 表記
+
+約物および日本語の表記については、以下のルールに従ってください。
+
+1. 和欧混植がなされている訳文において、和文と欧文の間には半角スペースを手動で挿入しないこと。
+2. 和文において、句点は「。」を、読点は「、」を使用し、他の記号も原則として全角を使用すること。
+3. コロン「：」やセミコロン「；」は、原則として使用しないこと。ただし、「例：」など、文中以外で用いる場合はその限りではありません。
+4. 数字や欧文（ラテン文字、キリル文字、ギリシア文字など）は、原則として半角を使用すること。
+5. 原則、現代仮名遣いおよび常用漢字表に基づいた表記を使用すること。送り仮名や仮名書き、ひらがな・カタカナの使い分けは、一般的な書き方に従ってください。ただし、引用、特定の用語や固有名詞については、その限りではありません。
+
+### 用語
+
+用語については、以下のガイドラインに従ってください。
+
+1. [用語集](https://typst-jp.github.io/docs/glossary/)を参照すること。
+    1. 用語集にあってかつ適切と思われる場合は、その通りに翻訳してください。
+    2. 用語集にあっても不適切と思われる場合は、IssueやDiscordで相談してください
+    3. 必要と思われるのに用語集にない場合は、既存の翻訳を参照し、追加を提案してください。
+2. 用語と用語でないものを、柔軟に見分けて訳し分けること。
+3. 現代日本語の一般的な、わかりやすい用語を使用すること。
+
+### 参考
+
+* [JTFスタイルガイド](https://www.jtf.jp/tips/styleguide)
+* [ウィキペディア日本語版のスタイルマニュアル](https://ja.wikipedia.org/wiki/Wikipedia:%E3%82%B9%E3%82%BF%E3%82%A4%E3%83%AB%E3%83%9E%E3%83%8B%E3%83%A5%E3%82%A2%E3%83%AB)
+* [ウィキペディア日本語版の表記ガイド](https://ja.wikipedia.org/wiki/Wikipedia:%E8%A1%A8%E8%A8%98%E3%82%AC%E3%82%A4%E3%83%89)
+* [Microsoft Localization Style Guides](https://learn.microsoft.com/ja-jp/globalization/reference/microsoft-style-guides)
+* [WordPress 翻訳ハンドブック](https://ja.wordpress.org/team/handbook/translation/)
+* [Vue.js 公式サイト日本語翻訳ガイド](https://github.com/vuejs-translations/docs-ja/blob/main/.github/CONTRIBUTING.md)
+* [ja.react.dev 翻訳スタイルガイド](https://github.com/reactjs/ja.react.dev/wiki/%E7%BF%BB%E8%A8%B3%E3%82%B9%E3%82%BF%E3%82%A4%E3%83%AB%E3%82%AC%E3%82%A4%E3%83%89)