From 3a41d8c63b9db559b0e6853b94689b94e7e0a228 Mon Sep 17 00:00:00 2001 From: 3w36zj6 <52315048+3w36zj6@users.noreply.github.com> Date: Mon, 23 Feb 2026 15:15:25 +0900 Subject: [PATCH 1/8] =?UTF-8?q?docs:=20GitHub=20Copilot=E3=81=AE=E3=82=AB?= =?UTF-8?q?=E3=82=B9=E3=82=BF=E3=83=A0=E6=8C=87=E7=A4=BA=E3=82=92=E8=BF=BD?= =?UTF-8?q?=E5=8A=A0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .github/copilot-instructions.md | 45 +++++++++++++++++++++++++++++++++ 1 file changed, 45 insertions(+) create mode 100644 .github/copilot-instructions.md diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 0000000000..12b20b8742 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,45 @@ +# Copilot instructions + +このリポジトリは、[Typst](https://typst.app/)の公式ドキュメントを日本語に翻訳するプロジェクトおける、コーディングエージェント用の初期セットアップガイドです。エージェントは作業を開始する前に必ずこのファイルを参照し、記載された手順や制約に従ってください。 + +## リポジトリの概要 + +- リポジトリの目的は、Typstの公式ドキュメントを日本語へ翻訳し、Webサイトとして公開することです。 +- 依存ツールの管理やタスクランナーとしてmiseを使用します。RustやNode.jsなどのランタイム、jqなどのツールは`mise`で管理されます。 +- Node.jsのパッケージ管理はBunを使用します。 +- GitHub Actions（`website.yml`）では、miseタスクを実行し、ビルド、textlint、デプロイを行います。 + +### 主要なディレクトリの構成 + +- `docs/`: 翻訳対象のMarkdownドキュメントとドキュメントのジェネレーター（typst-docs）。チュートリアル系の文章はここで管理されます。ページ名や見出しの翻訳、リンク解決などは`docs/src/`に書かれたRustコードに依存しており、翻訳者は必要に応じてこのコードを調整します。 +- `crates/`: 翻訳対象のrustdocドキュメント。リファレンス系の文章はここで管理されます。rustdocのみを編集対象とし、コード本体は変更しません。 +- `website/`: Webサイトのメタデータと静的サイトジェネレーター（typst-docs-web）。翻訳状況は`website/translation-status.json`で管理されます。 + +## 開発の流れ + +開発や検証は、リポジトリのルートから`mise run`コマンドを使用して行います。 + +### よく使うコマンド + +- `mise run generate`: `docs.json`を再生成し静的Webサイトをビルドします。ドキュメント編集後は必ず実行してください。 +- `mise run preview`: ローカルの開発サーバーを起動し、プレビュー（http://localhost:4173/docs/）を開始します。 +- `mise run textlint-md`: Markdownの文章をtextlintで校正します。 +- `mise run textlint-html`: 生成されたHTMLの文章をtextlintで校正します。 + +## Pull Request作成時の確認事項 + +- `mise run generate`を実行し、ビルドエラーが出ないことを確認する。 +- `mise run textlint-md`および`mise run textlint-html`を実行して警告を解消する。 +- 訳語や文法が`TRANSLATING_GUIDELINES.md`や`docs/glossary.md`に沿っているか確認する。 +- `website/translation-status.json`の翻訳状況を更新する。 + +## エージェントへの補足 + +- `docs.json`と`assets/`は自動生成されるので、編集やコミットをしてはいけません。 +- `TRANSLATING_GUIDELINES.md`と`docs/glossary.md`で必ず訳語ルールを確認してください。 +- 日本語の表現はtextlintの指摘を尊重してください。設定は`prh.yaml`や`.textlintrc`にあります。 +- miseタスクの詳細は`mise.toml`にあります。 +- 人間向けの貢献ガイドは`CONTRIBUTING.md`にあります。 +- `target/`, `node_modules/`フォルダは検索時は無視してください。 + +これらの指示を信頼し、足りない情報や誤りがあれば検索や調査を行ってください。 From 11d7db5366003829265e42738a1e92be57cd0ee7 Mon Sep 17 00:00:00 2001 From: 3w36zj6 <52315048+3w36zj6@users.noreply.github.com> Date: Mon, 23 Feb 2026 15:28:02 +0900 Subject: [PATCH 2/8] =?UTF-8?q?docs:=20=E7=BF=BB=E8=A8=B3=E3=82=B9?= =?UTF-8?q?=E3=82=AF=E3=83=AA=E3=83=97=E3=83=88=E3=81=AE=E3=83=97=E3=83=AD?= =?UTF-8?q?=E3=83=B3=E3=83=97=E3=83=88=E3=82=92=E7=A7=BB=E8=A1=8C?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .github/copilot-instructions.md | 10 ++++- translate.py | 75 --------------------------------- 2 files changed, 9 insertions(+), 76 deletions(-) delete mode 100644 translate.py diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 12b20b8742..5b5789230e 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -26,6 +26,15 @@ - `mise run textlint-md`: Markdownの文章をtextlintで校正します。 - `mise run textlint-html`: 生成されたHTMLの文章をtextlintで校正します。 +## 翻訳の基本方針 + +- `TRANSLATING_GUIDELINES.md`および`docs/glossary.md`を必ず確認し、プロジェクト固有の訳語ルールと方針に厳密に従ってください。 +- 日本語における標準的なIT技術用語・プログラミング用語を使用して翻訳してください。 +- 日本語の表現習慣を考慮して、語順を変更し、文の成分を補足して、文が日本語の文脈に合った流暢さを保つようにしてください。 +- 文脈に応じて固有名詞や多義語の翻訳を決定してください。直接的な日本語の対応語がない単語は原文を保持し、可能な場合は注釈を提供してください。 +- 流暢で読みやすく、元の情報が完全に保持されるように翻訳してください。 +- コードブロック中の記述は翻訳しないでください。 + ## Pull Request作成時の確認事項 - `mise run generate`を実行し、ビルドエラーが出ないことを確認する。 @@ -36,7 +45,6 @@ ## エージェントへの補足 - `docs.json`と`assets/`は自動生成されるので、編集やコミットをしてはいけません。 -- `TRANSLATING_GUIDELINES.md`と`docs/glossary.md`で必ず訳語ルールを確認してください。 - 日本語の表現はtextlintの指摘を尊重してください。設定は`prh.yaml`や`.textlintrc`にあります。 - miseタスクの詳細は`mise.toml`にあります。 - 人間向けの貢献ガイドは`CONTRIBUTING.md`にあります。 diff --git a/translate.py b/translate.py deleted file mode 100644 index 540eda0fee..0000000000 --- a/translate.py +++ /dev/null @@ -1,75 +0,0 @@ -import argparse -import openai -import tiktoken - -def translate_markdown(api_key, model, base_url, sysprompt, input_file, last_output_file=None): - # OpenAI API の認証情報 - openai.api_key = api_key - openai.base_url = base_url - - # Markdown ファイルを読み込む - with open(input_file, 'r', encoding='utf-8') as file: - content = file.read() - - # 途中で切れた前回の出力を Markdown から読み込む - if last_output_file is not None: - with open(last_output_file, 'r', encoding='utf-8') as file: - last_output = file.read() - - prompt_template = f""" -以下は英語の技術文書の一部です。これを日本語に翻訳してください。ただし、次のsystem promptの要求に注意してください: {content} -""" - messages = [ - {"role": "system", "content": sysprompt}, - {"role": "user", "content": prompt_template} - ] - if last_output_file is not None: - # see: https://zenn.dev/lambta/articles/1124a6aa22ff91 - messages.append({"role": "assistant", "content": last_output}) - - # OpenAI API の呼び出し - stream = openai.chat.completions.create( - model=model, - messages=messages, - stream=True, - max_tokens=4096, - ) - response = "" - for chunk in stream: - if chunk.choices[0].delta.content is not None: - print(chunk.choices[0].delta.content, end="") - response += chunk.choices[0].delta.content - # overwrite the original file - # with open(input_file, 'w', encoding='utf-8') as file: - # file.write(response) - -if __name__ == "__main__": - parser = argparse.ArgumentParser(description="Translate Markdown files using OpenAI API.") - parser.add_argument("-k", "--api-key", required=True, help="OpenAI API key") - parser.add_argument("-m", "--model", default="gpt-3.5-turbo-16k", help="Model to be used for translation. gpt-3.5-turbo-16k and gpt-4-1106-preview are recommended.") - parser.add_argument("-b", "--base-url", default="https://api.openai.com/v1/", help="Base URL for the OpenAI API") - parser.add_argument("-s", "--sysprompt", default=""" -以下の条件に従い、英文の技術文書を日本語に翻訳してください。訳文のみを返してください。 -1. 日本語における標準的なIT技術用語・プログラミング用語を使用して翻訳してください。 -2. 日本語の表現習慣を考慮して、語順を変更し、文の成分を補足して、文が日本語の文脈に合った流暢さを保つようにしてください。 -3. 文脈に応じて固有名詞や多義語の翻訳を決定してください。直接的な日本語の対応語がない単語は原文を保持し、可能な場合は注釈を提供してください。 -4. 流暢で読みやすく、元の情報が完全に保持されるように翻訳してください。 -5. コードブロック中の記述は翻訳しないでください。 -""", help="System prompt to be used for translation") - parser.add_argument("-f", "--file", required=True, help="Path to the Markdown file to be translated") - parser.add_argument("-l", "--last-output", default=None, required=False, help="Path to the Markdown file that ChatGPT generated last time. If this is specified, ChatGPT will continue from the last output.") - - args = parser.parse_args() - - translate_markdown(args.api_key, args.model, args.base_url, args.sysprompt, args.file, args.last_output) - -""" -使い方： - -# 初回実行。これだけだと出力が途中で途切れてしまうので、次回以降の実行に利用するために途中までの出力を保存しておく -$ python ./translate.py -k ${api-key} -f input.md > chunk_output.md - -# 2回目以降。ファイル全体を翻訳し終えるまで、このワンライナーを繰り返し実行し続ける -# これを続けていくと、いずれ chunk_output.md が input.md 全体の翻訳になる。その時点でワンライナーの再実行を取りやめる -$ python ./translate.py -k ${api-key} -f input.md -l chunk_output.md >> chunk_output.md -""" \ No newline at end of file From 18032a73687013754e3fdb0fe1375efc8439ad25 Mon Sep 17 00:00:00 2001 From: 3w36zj6 <52315048+3w36zj6@users.noreply.github.com> Date: Mon, 23 Feb 2026 15:36:43 +0900 Subject: [PATCH 3/8] =?UTF-8?q?docs:=20=E6=96=87=E8=A8=80=E3=82=92?= =?UTF-8?q?=E4=BF=AE=E6=AD=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .github/copilot-instructions.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 5b5789230e..27739f1ef6 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -1,6 +1,6 @@ # Copilot instructions -このリポジトリは、[Typst](https://typst.app/)の公式ドキュメントを日本語に翻訳するプロジェクトおける、コーディングエージェント用の初期セットアップガイドです。エージェントは作業を開始する前に必ずこのファイルを参照し、記載された手順や制約に従ってください。 +このリポジトリは、[Typst](https://typst.app/)の公式ドキュメントを日本語に翻訳するプロジェクトにおける、コーディングエージェント用の初期セットアップガイドです。エージェントは作業を開始する前に必ずこのファイルを参照し、記載された手順や制約に従ってください。 ## リポジトリの概要 @@ -45,7 +45,7 @@ ## エージェントへの補足 - `docs.json`と`assets/`は自動生成されるので、編集やコミットをしてはいけません。 -- 日本語の表現はtextlintの指摘を尊重してください。設定は`prh.yaml`や`.textlintrc`にあります。 +- 日本語の表現はtextlintの指摘を尊重してください。設定は`prh.yaml`や`.textlintrc.js`にあります。 - miseタスクの詳細は`mise.toml`にあります。 - 人間向けの貢献ガイドは`CONTRIBUTING.md`にあります。 - `target/`, `node_modules/`フォルダは検索時は無視してください。 From b4d13d7605449ba0a5c410193c4c3b972b3bc2d4 Mon Sep 17 00:00:00 2001 From: 3w36zj6 <52315048+3w36zj6@users.noreply.github.com> Date: Mon, 23 Feb 2026 16:04:01 +0900 Subject: [PATCH 4/8] =?UTF-8?q?docs:=20=E5=88=9D=E5=9B=9E=E3=82=BB?= =?UTF-8?q?=E3=83=83=E3=83=88=E3=82=A2=E3=83=83=E3=83=97=E6=89=8B=E9=A0=86?= =?UTF-8?q?=E3=82=92=E8=BF=BD=E5=8A=A0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .github/copilot-instructions.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 27739f1ef6..23e677b27c 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -15,6 +15,27 @@ - `crates/`: 翻訳対象のrustdocドキュメント。リファレンス系の文章はここで管理されます。rustdocのみを編集対象とし、コード本体は変更しません。 - `website/`: Webサイトのメタデータと静的サイトジェネレーター（typst-docs-web）。翻訳状況は`website/translation-status.json`で管理されます。 +## 初回セットアップ + +このリポジトリは`website/typst-docs-web`をGitサブモジュールとして含んでいます（`.gitmodules` を参照）。初めてクローンする場合は以下のいずれかを実行してください。 + +```bash +git clone --recursive +``` + +もしすでにクローン済みであれば： + +```bash +git submodule update --init --recursive +``` + +また、`mise run`を使う前に一度だけ以下を実行してください（詳細は `CONTRIBUTING.md`を参照）。 + +```bash +mise trust # このリポジトリの`mise.toml`を信頼 +mise install # Rust, Node.js, jqなどのツールをインストール +``` + ## 開発の流れ 開発や検証は、リポジトリのルートから`mise run`コマンドを使用して行います。 From 2842ab89cb46de484e42b9d46813e9e1edefb389 Mon Sep 17 00:00:00 2001 From: 3w36zj6 <52315048+3w36zj6@users.noreply.github.com> Date: Mon, 23 Feb 2026 16:04:18 +0900 Subject: [PATCH 5/8] =?UTF-8?q?docs:=20=E3=83=89=E3=82=AD=E3=83=A5?= =?UTF-8?q?=E3=83=A1=E3=83=B3=E3=83=88=E7=94=9F=E6=88=90=E3=81=AB=E9=96=A2?= =?UTF-8?q?=E3=81=99=E3=82=8B=E3=83=91=E3=82=B9=E3=82=92=E4=BF=AE=E6=AD=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- CONTRIBUTING.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 407285d4ce..a64158b251 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -107,7 +107,7 @@ mise install ドキュメントデータのJSONファイルは、typst-docsによりTypstのソースコード内のコメントおよび`docs/`にあるMarkdownファイル群から生成されます。 -`mise run generate-docs`を実行すると、ドキュメントデータのJSONファイルが`assets/docs.json`に生成されます。 +`mise run generate-docs`を実行すると、ドキュメントデータのJSONファイルがリポジトリルートの`docs.json`に生成されます。 ```sh mise run generate-docs @@ -117,7 +117,7 @@ mise run generate-docs Webサイトの生成にはNode.jsとViteとHonoを使用しています。また、パッケージ管理にBunを使用しています。 -`mise run generate-web`を実行すると、`assets/docs.json`を基にWebサイトのデータが`website/dist/`に生成されます。 +`mise run generate-web`を実行すると、`docs.json`を基にWebサイトのデータが`website/dist/`に生成されます。 ```sh mise run generate-web From 610817ba880a3b28775ac5f7d73e2f84cc773602 Mon Sep 17 00:00:00 2001 From: 3w36zj6 <52315048+3w36zj6@users.noreply.github.com> Date: Mon, 23 Feb 2026 16:18:39 +0900 Subject: [PATCH 6/8] =?UTF-8?q?docs:=20Web=E3=82=B5=E3=82=A4=E3=83=88?= =?UTF-8?q?=E7=94=9F=E6=88=90=E3=81=AE=E5=87=BA=E5=8A=9B=E5=85=88=E3=83=91?= =?UTF-8?q?=E3=82=B9=E3=82=92=E4=BF=AE=E6=AD=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a64158b251..842a5aa1bd 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -117,7 +117,7 @@ mise run generate-docs Webサイトの生成にはNode.jsとViteとHonoを使用しています。また、パッケージ管理にBunを使用しています。 -`mise run generate-web`を実行すると、`docs.json`を基にWebサイトのデータが`website/dist/`に生成されます。 +`mise run generate-web`を実行すると、`docs.json`を基にWebサイトのデータが`website/typst-docs-web/dist/`に生成されます。 ```sh mise run generate-web From b7fa40fb6258b2396f7a84cbcc7ea479b7a4ebb9 Mon Sep 17 00:00:00 2001 From: 3w36zj6 <52315048+3w36zj6@users.noreply.github.com> Date: Mon, 23 Feb 2026 16:30:58 +0900 Subject: [PATCH 7/8] =?UTF-8?q?docs:=20=E3=83=97=E3=83=AC=E3=83=93?= =?UTF-8?q?=E3=83=A5=E3=83=BC=E3=82=B3=E3=83=9E=E3=83=B3=E3=83=89=E3=81=AE?= =?UTF-8?q?=E8=AA=AC=E6=98=8E=E3=82=92=E4=BF=AE=E6=AD=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .github/copilot-instructions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 23e677b27c..c04692227c 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -43,7 +43,7 @@ mise install # Rust, Node.js, jqなどのツールをインストール ### よく使うコマンド - `mise run generate`: `docs.json`を再生成し静的Webサイトをビルドします。ドキュメント編集後は必ず実行してください。 -- `mise run preview`: ローカルの開発サーバーを起動し、プレビュー（http://localhost:4173/docs/）を開始します。 +- `mise run preview`: ビルド済みの成果物をプレビューするサーバー（`http://localhost:4173/docs/`）を起動します。 - `mise run textlint-md`: Markdownの文章をtextlintで校正します。 - `mise run textlint-html`: 生成されたHTMLの文章をtextlintで校正します。 From 0cfa4a34059343d60d48828089567b3264e1f669 Mon Sep 17 00:00:00 2001 From: 3w36zj6 <52315048+3w36zj6@users.noreply.github.com> Date: Mon, 23 Feb 2026 16:38:26 +0900 Subject: [PATCH 8/8] =?UTF-8?q?docs:=20=E3=82=AF=E3=83=AD=E3=83=BC?= =?UTF-8?q?=E3=83=B3=E6=89=8B=E9=A0=86=E3=81=AB=E5=85=B7=E4=BD=93=E7=9A=84?= =?UTF-8?q?=E3=81=AAURL=E3=82=92=E8=BF=BD=E5=8A=A0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .github/copilot-instructions.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index c04692227c..8e16cbbf44 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -20,7 +20,11 @@ このリポジトリは`website/typst-docs-web`をGitサブモジュールとして含んでいます（`.gitmodules` を参照）。初めてクローンする場合は以下のいずれかを実行してください。 ```bash -git clone --recursive +# HTTPS +git clone --recursive https://github.com/typst-jp/docs.git + +# SSH +git clone --recursive git@github.com:typst-jp/docs.git ``` もしすでにクローン済みであれば：