From af5dd440047621d3876ee4d64c8c6a1e539cb619 Mon Sep 17 00:00:00 2001 From: "localizeflow[bot]" Date: Fri, 6 Feb 2026 12:36:03 +0000 Subject: [PATCH] chore(i18n): sync translations with latest source changes (chunk 1/1, 6 changes) --- translations/ja/.co-op-translator.json | 2 +- translations/ja/AGENTS.md | 346 +++++++++--------- translations/zh-HK/.co-op-translator.json | 2 +- translations/zh-HK/AGENTS.md | 408 +++++++++++----------- translations/zh-TW/.co-op-translator.json | 2 +- translations/zh-TW/AGENTS.md | 344 +++++++++--------- 6 files changed, 551 insertions(+), 553 deletions(-) diff --git a/translations/ja/.co-op-translator.json b/translations/ja/.co-op-translator.json index b5107f4a7..b22557c3a 100644 --- a/translations/ja/.co-op-translator.json +++ b/translations/ja/.co-op-translator.json @@ -493,7 +493,7 @@ }, "AGENTS.md": { "original_hash": "a362efd06d64d4134a0cfe8515a86d34", - "translation_date": "2026-02-06T11:10:34+00:00", + "translation_date": "2026-02-06T12:35:58+00:00", "source_file": "AGENTS.md", "language_code": "ja" }, diff --git a/translations/ja/AGENTS.md b/translations/ja/AGENTS.md index 8391ffdbd..87c62751a 100644 --- a/translations/ja/AGENTS.md +++ b/translations/ja/AGENTS.md @@ -2,27 +2,27 @@ ## プロジェクト概要 -これは初心者に対してウェブ開発の基礎を教えるための教育カリキュラムリポジトリです。カリキュラムはMicrosoft Cloud Advocatesによって開発された包括的な12週間のコースで、JavaScript、CSS、HTMLをカバーする24の実践的なレッスンが含まれています。 +これは、初心者にウェブ開発の基本を教えるための教育カリキュラムリポジトリです。このカリキュラムは、Microsoft Cloud Advocatesによって開発された包括的な12週間のコースで、JavaScript、CSS、HTMLをカバーする24の実践的なレッスンが含まれています。 -### 主要コンポーネント +### 主な構成要素 -- **教育コンテンツ**：プロジェクトベースのモジュールに整理された24の構造化されたレッスン -- **実践プロジェクト**：テラリウム、タイピングゲーム、ブラウザー拡張機能、スペースゲーム、バンキングアプリ、コードエディタ、AIチャットアシスタント -- **インタラクティブクイズ**：レッスン前後評価用の3問ずつ計48のクイズ -- **多言語対応**：GitHub Actionsを用いた50以上の言語への自動翻訳 -- **技術スタック**：HTML、CSS、JavaScript、Vue.js 3、Vite、Node.js、Express、Python（AIプロジェクト用） +- **教育コンテンツ**: プロジェクトベースのモジュールに編成された24の構造化されたレッスン +- **実践プロジェクト**: テラリウム、タイピングゲーム、ブラウザー拡張機能、スペースゲーム、バンキングアプリ、コードエディター、AIチャットアシスタント +- **インタラクティブクイズ**: 各レッスン前後の評価として3問×48クイズ +- **多言語対応**: GitHub Actionsによる50以上の言語への自動翻訳 +- **技術スタック**: HTML、CSS、JavaScript、Vue.js 3、Vite、Node.js、Express、Python（AIプロジェクト向け） ### アーキテクチャ -- レッスンベースの構造を持つ教育リポジトリ -- 各レッスンフォルダにはREADME、コード例、解答が含まれる -- quiz-appや他の様々なレッスンプロジェクトは独立したディレクトリ -- GitHub Actions（co-op-translator）を使った翻訳システム -- Docsifyによるドキュメント提供とPDF形式での利用可能 +- レッスンベースの構造を持つ教育用リポジトリ +- 各レッスンフォルダにはREADME、コード例、解答例を含む +- 独立したプロジェクトは別ディレクトリ（quiz-app、各種レッスンプロジェクト） +- GitHub Actions（co-op-translator）を用いた翻訳システム +- Docsifyで提供され、PDFでも利用可能なドキュメント ## セットアップコマンド -このリポジトリは主に教育コンテンツの利用を目的としています。特定プロジェクトで作業する場合： +このリポジトリは主に教育コンテンツの閲覧用です。特定のプロジェクトを扱う場合は以下を参照してください。 ### メインリポジトリセットアップ @@ -31,17 +31,17 @@ git clone https://github.com/microsoft/Web-Dev-For-Beginners.git cd Web-Dev-For-Beginners ``` -### Quiz App セットアップ（Vue 3 + Vite） +### クイズアプリセットアップ (Vue 3 + Vite) ```bash cd quiz-app npm install -npm run dev # 開発サーバーを起動 -npm run build # 本番用にビルド -npm run lint # ESLint を実行 +npm run dev # 開発サーバーを起動する +npm run build # 本番用にビルドする +npm run lint # ESLintを実行する ``` -### バンクプロジェクト API（Node.js + Express） +### バンクプロジェクトAPI (Node.js + Express) ```bash cd 7-bank-project/api @@ -51,12 +51,12 @@ npm run lint # ESLintを実行する npm run format # Prettierでフォーマットする ``` -### ブラウザー拡張プロジェクト +### ブラウザー拡張機能プロジェクト ```bash cd 5-browser-extension/solution npm install -# ブラウザ固有の拡張機能の読み込み手順に従う +# ブラウザ固有の拡張機能読み込み手順に従ってください ``` ### スペースゲームプロジェクト @@ -67,7 +67,7 @@ npm install # index.htmlをブラウザで開くか、Live Serverを使用してください ``` -### チャットプロジェクト（Python バックエンド） +### チャットプロジェクト (Pythonバックエンド) ```bash cd 9-chat-project/solution/backend/python @@ -80,29 +80,29 @@ python api.py ### コンテンツ寄稿者向け -1. リポジトリを自身のGitHubアカウントにフォークする -2. フォークをローカルにクローンする -3. 変更用の新しいブランチを作成する -4. レッスン内容やコード例を変更する -5. 関連するプロジェクトディレクトリでコード変更をテストする -6. コントリビューションガイドラインに従いプルリクエストを送る +1. **リポジトリをフォーク**し、ご自身のGitHubアカウントに +2. **フォークしたリポジトリをクローン** +3. **変更用の新しいブランチを作成** +4. レッスンコンテンツやコード例を編集 +5. 関連プロジェクトディレクトリでコード変更をテスト +6. 寄稿ガイドラインに従いプルリクエストを提出 ### 学習者向け -1. リポジトリをフォークまたはクローンする +1. リポジトリをフォークまたはクローン 2. レッスンディレクトリを順に進む 3. 各レッスンのREADMEを読む -4. https://ff-quizzes.netlify.app/web/ でレッスン前クイズを完了する -5. レッスンフォルダ内のコード例を実践する -6. 課題やチャレンジに取り組む -7. レッスン後クイズを受ける +4. https://ff-quizzes.netlify.app/web/ でレッスン前クイズに挑戦 +5. レッスンフォルダ内のコード例を実施 +6. 課題やチャレンジを完了 +7. レッスン後クイズに挑戦 ### ライブ開発 -- **ドキュメンテーション**：リポジトリルートで `docsify serve` を実行（ポート3000） -- **クイズアプリ**：quiz-appディレクトリで `npm run dev` -- **プロジェクト**：HTMLプロジェクトはVS CodeのLive Server拡張を利用 -- **APIプロジェクト**：各APIディレクトリで `npm start` +- **ドキュメント**: ルートで `docsify serve` を実行（ポート3000） +- **クイズアプリ**: quiz-appディレクトリで `npm run dev` +- **プロジェクト**: HTMLプロジェクトはVS Code Live Server拡張使用推奨 +- **APIプロジェクト**: それぞれのAPIディレクトリで `npm start` ## テスト手順 @@ -119,79 +119,79 @@ npm run build # ビルドが成功することを確認する ```bash cd 7-bank-project/api npm run lint # コードスタイルの問題をチェックする -node server.js # サーバーがエラーなく起動することを確認する +node server.js # エラーなしでサーバーが起動するか確認する ``` -### 一般的なテスト方針 +### 一般的なテストアプローチ -- 本リポジトリは包括的な自動テストはありません -- 手動テストでは以下を重視： - - コード例がエラーなく実行されること - - ドキュメント内リンクが正しく動作すること - - プロジェクトのビルドが正常に完了すること - - コード例がベストプラクティスに沿っていること +- 本リポジトリは包括的な自動テストを備えていません +- 手動テストは以下に焦点を当てています： + - コード例がエラーなく動作すること + - ドキュメント内のリンクが正常に機能すること + - プロジェクトのビルドが成功すること + - 例がベストプラクティスに従っていること -### 提出前のチェック +### プルリク前チェック -- package.jsonがあるディレクトリで `npm run lint` を実行 -- マークダウンリンクの有効性を確認 -- ブラウザやNode.jsでコード例をテスト -- 翻訳が構造を保持していることをチェック +- package.jsonのあるディレクトリで `npm run lint` を実行 +- マークダウンリンクの検証 +- ブラウザまたはNode.jsでコード例をテスト +- 翻訳が正しい構造を維持しているか確認 ## コードスタイルガイドライン ### JavaScript -- モダンなES6+構文を使用 -- 各プロジェクト提供の標準ESLint設定に準拠 -- 教育的に分かりやすい意味のある変数名、関数名を使う -- 学習者向けに概念を説明するコメントを追加 -- Prettierが設定されている場合は整形を行う +- 最新のES6+構文を使用 +- 各プロジェクトの標準ESLint設定に従う +- 教育目的で意味の明確な変数・関数名を使用 +- 学習者向けに概念説明のコメントを付記 +- Prettierでフォーマット（設定がある場合） ### HTML/CSS -- セマンティックなHTML5要素を使用 -- レスポンシブデザイン原則を適用 -- 明確なクラス命名規則 -- CSS技法を説明するコメントを記述 +- セマンティックHTML5要素の使用 +- レスポンシブデザイン原則 +- 明確なクラス名付け規則 +- CSS技術の説明コメントを追加 ### Python -- PEP 8スタイルガイドに従う -- 分かりやすい教育的コード例 -- 学習の助けとなる型ヒントを適宜使用 +- PEP 8スタイルガイドライン準拠 +- 教育的で分かりやすいコード例 +- 学習に役立つ場合はタイプヒントを使用 -### マークダウンドキュメント +### Markdownドキュメント - 明確な見出し階層 - 言語指定されたコードブロック - 追加リソースへのリンク -- `images/` ディレクトリ内のスクリーンショット等の画像 -- 画像にはアクセシビリティのための代替テキストを設定 +- `images/`フォルダ内のスクリーンショットや画像 +- 画像のアクセシビリティ用altテキスト ### ファイル構成 -- レッスンは連番付き（1-getting-started-lessons、2-js-basicsなど） -- 各プロジェクトには `solution/` と多くは `start/` や `your-work/` ディレクトリを含む -- 画像はレッスン別の `images/` フォルダに保存 -- 翻訳ファイルは `translations/{language-code}/` 構造で配置 +- レッスンは連番付け（1-getting-started-lessons、2-js-basicsなど） +- 各プロジェクトに `solution/` と多くの場合 `start/` または `your-work/` ディレクトリあり +- 画像はレッスン固有の `images/` フォルダーに保存 +- 翻訳は `translations/{language-code}/` フォルダ構造 ## ビルドとデプロイ ### クイズアプリのデプロイ（Azure Static Web Apps） -quiz-appはAzure Static Web Apps向けに設定されています： +quiz-appはAzure Static Web Apps用に構成されています： ```bash cd quiz-app npm run build # dist/ フォルダーを作成します -# main ブランチへのプッシュ時に GitHub Actions ワークフローでデプロイします +# main ブランチへのプッシュ時に GitHub Actions ワークフローを通じてデプロイします ``` -Azure Static Web Apps設定： -- **アプリ位置**：`/quiz-app` -- **出力位置**：`dist` -- **ワークフロー**：`.github/workflows/azure-static-web-apps-ashy-river-0debb7803.yml` +Azure Static Web Appsの構成： +- **App location**: `/quiz-app` +- **Output location**: `dist` +- **Workflow**: `.github/workflows/azure-static-web-apps-ashy-river-0debb7803.yml` ### ドキュメントPDF生成 @@ -204,59 +204,59 @@ npm run convert # docs から PDF を生成する ```bash npm install -g docsify-cli # Docsifyをグローバルにインストールする -docsify serve # localhost:3000でサービスを提供する +docsify serve # localhost:3000でサーブする ``` ### プロジェクト別ビルド -各プロジェクトディレクトリには独自のビルド手順がある場合あり： -- Vueプロジェクト：`npm run build` でプロダクションバンドル生成 -- 静的プロジェクト：ビルド不要、ファイルを直接提供 +各プロジェクトディレクトリに固有のビルド手順がある場合があります： +- Vueプロジェクト：`npm run build` で本番用バンドル作成 +- 静的プロジェクト：ビルド不要で直接ファイル提供 ## プルリクエストガイドライン -### タイトル形式 +### タイトルフォーマット -明確で変更内容がわかるタイトルを使用： -- `[Quiz-app] レッスンXの新クイズ追加` -- `[Lesson-3] テラリウムプロジェクトの誤字修正` -- `[Translation] レッスン5のスペイン語翻訳追加` -- `[Docs] セットアップ手順の更新` +変更箇所が分かりやすい明確なタイトルを使用： +- `[Quiz-app] レッスンXの新クイズを追加` +- `[Lesson-3] テラリウムプロジェクトのタイプミス修正` +- `[Translation] レッスン5のスペイン語翻訳を追加` +- `[Docs] セットアップ手順を更新` ### 必須チェック -PR提出前に以下を実行： +PR提出前に以下を確認： 1. **コード品質**： - - 影響を受けるプロジェクトディレクトリで `npm run lint` - - すべての警告・エラーを修正 + - 変更対象プロジェクトディレクトリで `npm run lint` + - すべてのエラーと警告を修正 -2. **ビルド検証**： - - 必要に応じて `npm run build` - - ビルドエラーがないことを確認 +2. **ビルド確認**： + - 必要に応じて `npm run build` 実行 + - ビルドエラーなしを確認 3. **リンク検証**： - - 全マークダウンリンクの検証 + - すべてのマークダウンリンクをテスト - 画像参照の動作確認 4. **コンテンツレビュー**： - - 誤字脱字の校正 + - 誤字脱字チェック - コード例が正確で教育的であること - - 翻訳が原文の意味を保っていること + - 翻訳が原文の意味を維持していること -### 寄稿条件 +### 寄稿要件 - Microsoft CLAに同意（初回PRで自動チェック） -- [Microsoftオープンソース行動規範](https://opensource.microsoft.com/codeofconduct/)に従う -- 詳細は[CONTRIBUTING.md](./CONTRIBUTING.md)参照 -- 可能であればPR説明に関連Issue番号を記載 +- [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/) に従う +- 詳細は [CONTRIBUTING.md](./CONTRIBUTING.md) を参照 +- 可能な場合はPR説明にIssue番号を記載 ### レビュー手順 -- メンテナとコミュニティによるレビュー -- 教育的明瞭性を重視 -- コード例は最新のベストプラクティスに従うこと -- 翻訳は正確性と文化的適合性をチェック +- 守備者とコミュニティによるレビュー +- 教育的明瞭さを最優先 +- コード例は最新のベストプラクティスに準拠 +- 翻訳は正確さと文化的適切さをチェック ## 翻訳システム @@ -264,19 +264,19 @@ PR提出前に以下を実行： - GitHub Actionsのco-op-translatorワークフローを使用 - 50以上の言語に自動翻訳 -- メインディレクトリのソースファイルを翻訳 -- 翻訳ファイルは `translations/{language-code}/` ディレクトリに置かれる +- ソースファイルはメインディレクトリ +- 翻訳ファイルは `translations/{language-code}/` 配下 -### 手動による翻訳改善の追加 +### 手動翻訳改善の追加 -1. `translations/{language-code}/` 内のファイルを見つける -2. 構造を保持しつつ改善を行う -3. コード例が動作する状態を維持 -4. ローカライズされたクイズ内容もテスト +1. `translations/{language-code}/` 内のファイルを特定 +2. 構造を維持したまま改善 +3. コード例は機能したままであることを確認 +4. ローカライズされたクイズもテスト ### 翻訳メタデータ -翻訳ファイルにはメタデータヘッダーが含まれる： +翻訳ファイルにはメタデータヘッダーを含みます： ```markdown **免責事項**： -本書類はAI翻訳サービス[Co-op Translator](https://github.com/Azure/co-op-translator)を使用して翻訳されています。正確さを目指しておりますが、自動翻訳には誤りや不正確な部分が含まれる可能性があることをご留意ください。原文が権威ある情報源として優先されるべきです。重要な情報につきましては、専門の人間による翻訳を推奨します。本翻訳の利用により発生した誤解や誤訳について、当方は一切の責任を負いかねます。 +本書類はAI翻訳サービス「Co-op Translator」（https://github.com/Azure/co-op-translator）を使用して翻訳されています。正確性を期しておりますが、自動翻訳には誤りや不正確な部分が含まれる場合があります。原文の言語による文書が正式な情報源とみなされるべきです。重要な情報については、専門の人間による翻訳を推奨します。本翻訳の利用により生じた誤解や誤訳について、当方は一切の責任を負いかねます。 \ No newline at end of file diff --git a/translations/zh-HK/.co-op-translator.json b/translations/zh-HK/.co-op-translator.json index 518e6f234..5d2d3b998 100644 --- a/translations/zh-HK/.co-op-translator.json +++ b/translations/zh-HK/.co-op-translator.json @@ -493,7 +493,7 @@ }, "AGENTS.md": { "original_hash": "a362efd06d64d4134a0cfe8515a86d34", - "translation_date": "2026-02-06T11:08:07+00:00", + "translation_date": "2026-02-06T12:33:42+00:00", "source_file": "AGENTS.md", "language_code": "zh-HK" }, diff --git a/translations/zh-HK/AGENTS.md b/translations/zh-HK/AGENTS.md index f5a86a07a..185351a5c 100644 --- a/translations/zh-HK/AGENTS.md +++ b/translations/zh-HK/AGENTS.md @@ -1,47 +1,47 @@ # AGENTS.md -## 專案概述 +## Project Overview -這是一個用於教導初學者網頁開發基礎的教育課程資源庫。課程為為期12週的完整課程，由微軟雲端倡導者開發，包含24堂實作課程，涵蓋 JavaScript、CSS 與 HTML。 +這是一個用於教導初學者網頁開發基礎的教育課程資源庫。課程為一個由微軟雲端推廣者所開發的完整12週課程，包含24堂涵蓋 JavaScript、CSS 及 HTML 的實作課程。 -### 主要組成部分 +### Key Components -- **教育內容**：24堂結構化課程，依專案模組編排 -- **實作專案**：溫室、打字遊戲、瀏覽器擴充功能、太空遊戲、銀行應用、程式碼編輯器與 AI 聊天助手 -- **互動測驗**：48組測驗，每組3題（課前／課後評估） -- **多語言支援**：透過 GitHub Actions 自動翻譯成超過50種語言 -- **技術使用**：HTML、CSS、JavaScript、Vue.js 3、Vite、Node.js、Express、Python（AI 專案） +- **教育內容**：24堂結構化課程，分項目模組進行 +- **實作專案**：溫室、生字遊戲、瀏覽器擴充功能、太空遊戲、銀行應用程式、程式碼編輯器及 AI 聊天助理 +- **互動測驗**：48個測驗，每個測驗3題（課前及課後評估） +- **多語言支援**：透過 GitHub Actions 自動翻譯超過50種語言 +- **技術**：HTML、CSS、JavaScript、Vue.js 3、Vite、Node.js、Express、Python（AI專案用） -### 架構 +### Architecture -- 以課程為架構的教育資源庫 -- 每堂課資料夾包含說明文件、程式碼範例與解答 -- 獨立專案置於獨立目錄中（quiz-app、各堂專案） -- 使用 GitHub Actions（co-op-translator）進行翻譯系統 -- 文件以 Docsify 呈現，並提供 PDF 格式 +- 教育資源庫，採課程為單位架構 +- 每堂課資料夾包含 README、程式碼範例及解答 +- 獨立專案於不同資料夾（quiz-app、各課程專案） +- 使用 GitHub Actions (co-op-translator) 實現翻譯系統 +- 文件採用 Docsify 呈現，並提供 PDF 格式 -## 安裝指令 +## Setup Commands -此資源庫主要用作教育內容閱讀。若需使用特定專案： +此資源庫主要用於教育內容的瀏覽。針對特定專案的操作： -### 主要資源庫安裝 +### Main Repository Setup ```bash git clone https://github.com/microsoft/Web-Dev-For-Beginners.git cd Web-Dev-For-Beginners ``` -### 測驗應用安裝（Vue 3 + Vite） +### Quiz App Setup (Vue 3 + Vite) ```bash cd quiz-app npm install -npm run dev # 啟動開發伺服器 -npm run build # 建立生產版本 +npm run dev # 開始開發伺服器 +npm run build # 為生產環境構建 npm run lint # 執行 ESLint ``` -### 銀行專案 API（Node.js + Express） +### Bank Project API (Node.js + Express) ```bash cd 7-bank-project/api @@ -51,15 +51,15 @@ npm run lint # 執行 ESLint npm run format # 使用 Prettier 格式化 ``` -### 瀏覽器擴充功能專案 +### Browser Extension Projects ```bash cd 5-browser-extension/solution npm install -# 遵循瀏覽器專用的擴充功能載入指示 +# 遵循瀏覽器專用擴充功能載入指示 ``` -### 太空遊戲專案 +### Space Game Projects ```bash cd 6-space-game/solution @@ -67,7 +67,7 @@ npm install # 在瀏覽器中打開 index.html 或使用 Live Server ``` -### 聊天專案（Python 後端） +### Chat Project (Python Backend) ```bash cd 9-chat-project/solution/backend/python @@ -76,205 +76,205 @@ pip install openai python api.py ``` -## 開發工作流程 +## Development Workflow -### 對內容貢獻者 +### For Content Contributors -1. **Fork 本資源庫**到您的 GitHub 帳戶 -2. **在本機 Clone 您的 Fork** -3. **建立新分支**以便進行修改 +1. **將資源庫 Fork 到你的 GitHub 帳號** +2. **在本機複製你的 Fork** +3. **為你的變更建立新分支** 4. 修改課程內容或程式碼範例 -5. 在相關專案資料夾測試程式碼修改 -6. 依照貢獻指南提交 Pull Request +5. 在相關專案資料夾測試程式碼變更 +6. 依照貢獻指南提交 Pull Requests -### 對學習者 +### For Learners -1. Fork 或 Clone 資源庫 -2. 按順序瀏覽各課程資料夾 -3. 閱讀每堂課的 README 檔案 -4. 完成 https://ff-quizzes.netlify.app/web/ 中課前測驗 -5. 實作課程資料夾內的程式碼範例 -6. 完成作業與挑戰任務 -7. 參加課後測驗 +1. Fork 或複製此資源庫 +2. 依序進入各課程資料夾 +3. 閱讀每堂課的 README 文件 +4. 完成 https://ff-quizzes.netlify.app/web/ 的課前測驗 +5. 進行課程資料夾中的程式碼實作 +6. 完成作業及挑戰 +7. 進行課後測驗 -### 實時開發 +### Live Development -- **文件服務**：在根目錄執行 `docsify serve`（使用 3000 埠） -- **測驗應用**：於 quiz-app 目錄執行 `npm run dev` -- **專案**：靜態 HTML 項目可使用 VS Code Live Server 外掛 -- **API 專案**：分別目錄中執行 `npm start` +- **文件伺服器**：於根目錄執行 `docsify serve`（使用埠號3000） +- **Quiz App**：於 quiz-app 資料夾執行 `npm run dev` +- **專案**：使用 VS Code Live Server 擴充功能執行 HTML 專案 +- **API 專案**：於相應 API 資料夾執行 `npm start` -## 測試說明 +## Testing Instructions -### 測驗應用測試 +### Quiz App Testing ```bash cd quiz-app npm run lint # 檢查代碼風格問題 -npm run build # 確認編譯成功 +npm run build # 驗證構建是否成功 ``` -### 銀行 API 測試 +### Bank API Testing ```bash cd 7-bank-project/api npm run lint # 檢查代碼風格問題 -node server.js # 驗證伺服器啟動時無錯誤 +node server.js # 驗證服務器啟動無錯誤 ``` -### 一般測試流程 +### General Testing Approach -- 此為教育用資源庫，無全面自動化測試 -- 手動測試重點有： - - 程式碼範例無錯誤運行 - - 文件中連結均可正常運作 - - 專案成功 build - - 範例遵守最佳實務 +- 這是一個教育資源庫，無完整自動化測試 +- 手動測試重點包括： + - 程式碼範例正常執行無錯誤 + - 文件內的連結正常運作 + - 專案建置成功完成 + - 範例遵循最佳實務 -### 提交前檢查項目 +### Pre-submission Checks -- 在有 package.json 目錄下執行 `npm run lint` -- 驗證 markdown 鏈接有效 -- 在瀏覽器或 Node.js 中測試程式碼範例 -- 確保翻譯內容維持正確結構 +- 在包含 package.json 的資料夾執行 `npm run lint` +- 驗證 Markdown 連結有效 +- 於瀏覽器或 Node.js 測試程式碼範例 +- 確認翻譯內容結構維護正確 -## 程式碼風格指引 +## Code Style Guidelines ### JavaScript - 使用現代 ES6+ 語法 -- 遵循專案內提供的標準 ESLint 配置 -- 使用具意義變數與函式命名以利教學理解 -- 添加注釋以講解概念給學習者 -- 透過 Prettier 格式化（若已配置） +- 遵循專案內標準 ESLint 設定 +- 使用有意義的變數與函式名稱，方便教學 +- 加入注解解釋概念給學習者 +- 在有設定時使用 Prettier 格式化 ### HTML/CSS -- 使用語意化 HTML5 元素 -- 採用響應式設計原則 -- 清晰的 class 命名規範 -- 添加 CSS 技巧說明注釋以利學習者 +- 採用語意化 HTML5 元素 +- 響應式設計原則 +- 清晰的類別命名規則 +- 注解說明 CSS 技巧給學習者 ### Python -- 遵守 PEP 8 標準 -- 清楚且具教學意義的程式碼範例 -- 在適用處添加型別提示協助學習 +- 遵循 PEP 8 風格指引 +- 清晰且具教育意義的程式碼範例 +- 適時加入型態提示以協助學習 -### Markdown 文件 +### Markdown Documentation -- 清晰的標題層級 -- 帶語言標識的程式碼區塊 -- 附上額外資源連結 -- `images/` 資料夾中的截圖與圖片 -- 圖片備註文字以改善無障礙 +- 清楚的標題階層 +- 語言標示的程式碼區塊 +- 連結至額外資源 +- 螢幕截圖及圖片放於 `images/` 資料夾 +- 圖片備註文字以提升無障礙 -### 檔案組織 +### File Organization -- 課程依序編號（1-getting-started-lessons、2-js-basics 等） -- 專案中常有 `solution/` 及 `start/` 或 `your-work/` 目錄 -- 圖片存放於對應課程的 `images/` 資料夾 -- 翻譯位於 `translations/{language-code}/` 結構 +- 課程依序編號（1-getting-started-lessons，2-js-basics，等等） +- 每個專案有 `solution/` 等資料夾，通常還有 `start/` 或 `your-work/` +- 圖片存放在各課程的 `images/` 資料夾 +- 翻譯置於 `translations/{language-code}/` 結構中 -## 建置與部署 +## Build and Deployment -### 測驗 App 部署（Azure Static Web Apps） +### Quiz App Deployment (Azure Static Web Apps) -quiz-app 已配置用於 Azure Static Web Apps 部署： +quiz-app 已設定用於 Azure Static Web Apps 部署： ```bash cd quiz-app npm run build # 建立 dist/ 資料夾 -# 在推送至主分支時透過 GitHub Actions 工作流程部署 +# 於推送至 main 時，透過 GitHub Actions 工作流程部署 ``` Azure Static Web Apps 配置： -- **App 位置**：`/quiz-app` -- **輸出目錄**：`dist` +- **應用程式位置**：`/quiz-app` +- **輸出位置**：`dist` - **工作流程**：`.github/workflows/azure-static-web-apps-ashy-river-0debb7803.yml` -### 文件 PDF 產生 +### Documentation PDF Generation ```bash npm install # 安裝 docsify-to-pdf npm run convert # 從 docs 生成 PDF ``` -### Docsify 文件 +### Docsify Documentation ```bash -npm install -g docsify-cli # 全域安裝 Docsify -docsify serve # 在 localhost:3000 提供服務 +npm install -g docsify-cli # 全局安裝 Docsify +docsify serve # 在 localhost:3000 上提供服務 ``` -### 專案特定建置 +### Project-specific Builds -每個專案目錄可能有獨立建置流程： -- Vue 專案：`npm run build` 產生生產包 -- 靜態專案：無建置步驟，直接提供靜態檔案 +每個專案資料夾可能有獨立建置流程： +- Vue 專案：`npm run build` 產生生產版本包 +- 靜態專案：無建置步驟，直接提供檔案服務 -## Pull Request 準則 +## Pull Request Guidelines -### 標題格式 +### Title Format -使用明確、描述性標題說明變更領域： -- `[Quiz-app] 新增第X堂課測驗` -- `[Lesson-3] 修正溫室專案錯字` -- `[Translation] 新增第5課西班牙語翻譯` -- `[Docs] 更新安裝說明` +使用清楚、描述性的標題，指示修改範圍： +- `[Quiz-app] Add new quiz for lesson X` +- `[Lesson-3] Fix typo in terrarium project` +- `[Translation] Add Spanish translation for lesson 5` +- `[Docs] Update setup instructions` -### 必要檢查 +### Required Checks -提交 PR 前： +提交 PR 前須: 1. **程式碼品質**： - - 於受影響的專案目錄跑 `npm run lint` - - 修正所有 lint 錯誤與警告 + - 於相關專案資料夾執行 `npm run lint` + - 修正所有 lint 錯誤及警告 2. **建置驗證**： - - 若有，執行 `npm run build` + - 如有需要執行 `npm run build` - 確認無建置錯誤 3. **連結驗證**： - - 測試所有 markdown 連結 - - 確認圖片引用正確 + - 測試所有 Markdown 連結 + - 確認圖片參考可用 4. **內容審核**： - - 校對拼寫與文法 - - 確保程式碼範例正確且具教學價值 - - 核對翻譯內容忠實原意 + - 拼字及文法校對 + - 確認程式碼範例正確且具備教育意義 + - 確認翻譯保持原意 -### 貢獻要求 +### Contribution Requirements -- 同意微軟 CLA（首次 PR 會自動檢查） +- 同意微軟 CLA（首個 PR 會自動檢查） - 遵守 [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/) -- 詳見 [CONTRIBUTING.md](./CONTRIBUTING.md) -- 如適用，在 PR 描述中引用 issue 編號 +- 參考 [CONTRIBUTING.md](./CONTRIBUTING.md) 詳細指南 +- 如有相關 issue，請在 PR 描述內提及 issue 編號 -### 審查機制 +### Review Process -- PR 將由維護者及社群檢視 -- 優先考慮教育清晰度 -- 程式碼範例應符合現行最佳實務 -- 翻譯檢視準確性與文化適切性 +- PR 由維護者及社群共同審核 +- 優先考量教育清晰度 +- 程式碼範例應遵循現代最佳實務 +- 翻譯內容須審核準確性及文化適切性 -## 翻譯系統 +## Translation System -### 自動翻譯 +### Automated Translation - 使用 GitHub Actions 與 co-op-translator 工作流程 -- 自動翻譯成超過 50 種語言 -- 原始檔置於主要目錄 -- 翻譯檔在 `translations/{language-code}/` 目錄 +- 自動翻譯成50多種語言 +- 原始檔案位於主要目錄 +- 翻譯檔案位於 `translations/{language-code}/` 資料夾 -### 手動翻譯改良 +### Adding Manual Translation Improvements -1. 定位於 `translations/{language-code}/` 中的檔案 -2. 在維持結構的條件下進行改善 -3. 確保程式碼範例仍可正常運作 -4. 測試本地化測驗內容 +1. 尋找 `translations/{language-code}/` 中檔案 +2. 在保留結構下做改善 +3. 確保程式碼範例依然可用 +4. 測試任何本地化的測驗內容 -### 翻譯元資料 +### Translation Metadata 翻譯檔包含元資料標頭： ```markdown @@ -289,120 +289,120 @@ CO_OP_TRANSLATOR_METADATA: --> ``` -## 除錯與故障排除 +## Debugging and Troubleshooting -### 常見問題 +### Common Issues -**測驗應用啟動失敗**： +**Quiz app 無法啟動**： - 檢查 Node.js 版本（建議 v14+） -- 刪除 `node_modules` 與 `package-lock.json`，重新執行 `npm install` +- 刪除 `node_modules` 及 `package-lock.json`，重新執行 `npm install` - 檢查埠號衝突（預設：Vite 使用 5173 埠） **API 伺服器無法啟動**： -- 確認 Node.js 版本符合最低要求（node >=10） -- 確認埠號是否被佔用 -- 確保所有相依套件已執行 `npm install` +- 確認 Node.js 版本符合最低需求（node >=10） +- 檢查埠號是否已被占用 +- 確保執行了 `npm install` 安裝所有依賴 -**瀏覽器擴充無法載入**： +**瀏覽器擴充功能無法載入**： - 確認 manifest.json 格式正確 -- 檢查瀏覽器控制台錯誤訊息 -- 依照瀏覽器特定的安裝說明操作 +- 查看瀏覽器主控台錯誤訊息 +- 依瀏覽器特定安裝步驟操作 **Python 聊天專案問題**： -- 確認 OpenAI 套件安裝：`pip install openai` -- 檢查 GITHUB_TOKEN 環境變數設置 -- 確認具備 GitHub Models 存取權限 +- 確認已安裝 openai 套件：`pip install openai` +- 檢查 GITHUB_TOKEN 環境變數是否設定 +- 確認 GitHub Models 的存取權限 -**Docsify 無法提供文件**： +**Docsify 文件無法服務**： - 全域安裝 docsify-cli：`npm install -g docsify-cli` - 從資源庫根目錄執行 -- 確認存在 `docs/_sidebar.md` 檔案 +- 檢查 `docs/_sidebar.md` 是否存在 -### 開發環境建議 +### Development Environment Tips -- HTML 專案使用 VS Code 與 Live Server 擴充套件 -- 安裝 ESLint 與 Prettier 擴充以維持格式一致 -- 使用瀏覽器 DevTools 除錯 JavaScript +- 使用 VS Code 並安裝 Live Server 擴充功能作 HTML 專案開發 +- 安裝 ESLint 和 Prettier 擴充保持格式一致 +- 利用瀏覽器開發者工具除錯 JavaScript - Vue 專案可安裝 Vue DevTools 瀏覽器擴充 -### 效能考量 +### Performance Considerations -- 超過 50 種語言翻譯檔數量龐大，完整 clone 容量大 -- 只工作於內容時可用淺層 clone：`git clone --depth 1` -- 編輯英文內容時可排除搜尋翻譯檔 -- 建置流程首次執行時可能較慢（npm install、Vite build） +- 大量翻譯檔案（50+ 語言）導致完整 clone 容量大 +- 只工作於內容時可使用淺層 clone：`git clone --depth 1` +- 針對英文內容開發時排除翻譯目錄搜尋 +- 初次執行建置流程時（npm install、Vite build）可能較慢 -## 安全性考量 +## Security Considerations -### 環境變數 +### Environment Variables -- API 金鑰絕不可提交至資源庫 -- 使用 `.env` 文件（已包含於 `.gitignore`） -- 在專案 README 中說明必需之環境變數 +- API 金鑰切勿提交至資源庫 +- 使用 `.env` 檔案（已加入 `.gitignore`） +- 在專案 README 中說明所需環境變數 -### Python 專案 +### Python Projects - 使用虛擬環境：`python -m venv venv` -- 持續更新相依套件 -- GitHub Token 應有最小必要權限 +- 保持依賴為最新版本 +- GitHub token 撥放最小權限 -### GitHub Models 存取 +### GitHub Models Access -- 使用個人存取權杖（PAT）以存取 GitHub Models -- 將 Token 儲存為環境變數 -- 切勿提交 Token 或憑證 +- 需個人存取權杖（PAT）取得 GitHub Models 權限 +- 權杖應以環境變數保存 +- 嚴禁提交權杖或憑證 -## 額外說明 +## Additional Notes -### 目標受眾 +### Target Audience -- 對網頁開發全然新手者 -- 學生與自學者 -- 使用課程於教室教學的老師 -- 內容設計以無障礙與技能循序漸進為主 +- 網頁開發初學者 +- 學生及自學者 +- 在教室使用課程的教師 +- 內容設計注重無障礙及漸進技能建立 -### 教學理念 +### Educational Philosophy -- 專案導向學習法 +- 專案導向學習方法 - 頻繁知識檢核（測驗） -- 實作編碼練習 +- 動手編碼練習 - 真實世界應用範例 -- 強調基礎先於框架 +- 先建立基礎，再學框架 -### 資源庫維護 +### Repository Maintenance -- 具活躍學習者與貢獻社群 -- 定期更新相依套件與內容 -- 維護者監督問題及討論 -- 透過 GitHub Actions 自動化翻譯更新 +- 積極的學習者與貢獻者社群 +- 定期更新相依性與內容 +- 維護者監控 issue 與討論 +- 利用 GitHub Actions 自動化翻譯更新 -### 相關資源 +### Related Resources - [Microsoft Learn 模組](https://docs.microsoft.com/learn/) - [學生中心資源](https://docs.microsoft.com/learn/student-hub/) -- 推薦使用 [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) 予學習者 -- 另有生成式 AI、資料科學、機器學習、物聯網等課程可參考 +- 推薦學習者使用 [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) +- 額外課程：生成式 AI、資料科學、機器學習、物聯網課程可取得 -### 使用特定專案說明 +### Working with Specific Projects -詳細指引請參考 README： -- `quiz-app/README.md` - Vue 3 測驗應用 -- `7-bank-project/README.md` - 含認證的銀行應用 -- `5-browser-extension/README.md` - 瀏覽器擴充開發 -- `6-space-game/README.md` - Canvas 基礎遊戲 -- `9-chat-project/README.md` - AI 聊天助手專案 +個別專案詳細說明，請參閱 README 檔案： +- `quiz-app/README.md` - Vue 3 測驗應用程式 +- `7-bank-project/README.md` - 銀行應用含驗證 +- `5-browser-extension/README.md` - 瀏覽器擴充功能開發 +- `6-space-game/README.md` - Canvas遊戲開發 +- `9-chat-project/README.md` - AI 聊天助理專案 -### Monorepo 結構 +### Monorepo Structure 此非傳統 monorepo，但包含多個獨立專案： -- 每堂課自主完整 -- 各專案無相依共享 -- 可專注於單一專案開發 -- 若要完整體驗請 clone 整個資源庫 +- 每堂課獨立運作 +- 專案不共享依賴 +- 可在不影響他專案下工作 +- 若要完整學習體驗，建議 clone 全部資源庫 --- -**免責聲明**： -本文件係使用人工智能翻譯服務 [Co-op Translator](https://github.com/Azure/co-op-translator) 進行翻譯。雖然我們努力確保準確性，但請注意，自動翻譯可能包含錯誤或不準確之處。原始文件以其原文為最具權威之版本。對於重要資訊，建議聘用專業人工翻譯。我們不對因使用此翻譯而產生的任何誤解或誤譯承擔責任。 +**免責聲明**： +本文件乃使用 AI 翻譯服務 [Co-op Translator](https://github.com/Azure/co-op-translator) 翻譯而成。雖然我們努力確保準確性，但請注意，自動翻譯可能包含錯誤或不準確之處。原始語言版本的文件應被視為權威來源。對於關鍵資訊，建議採用專業人工翻譯。我們概不對因使用本翻譯而引致的任何誤解或誤譯承擔責任。 \ No newline at end of file diff --git a/translations/zh-TW/.co-op-translator.json b/translations/zh-TW/.co-op-translator.json index c1f8f2ffb..51a7d8152 100644 --- a/translations/zh-TW/.co-op-translator.json +++ b/translations/zh-TW/.co-op-translator.json @@ -493,7 +493,7 @@ }, "AGENTS.md": { "original_hash": "a362efd06d64d4134a0cfe8515a86d34", - "translation_date": "2026-02-06T11:09:15+00:00", + "translation_date": "2026-02-06T12:34:49+00:00", "source_file": "AGENTS.md", "language_code": "zh-TW" }, diff --git a/translations/zh-TW/AGENTS.md b/translations/zh-TW/AGENTS.md index 3574bf33b..13a5c470b 100644 --- a/translations/zh-TW/AGENTS.md +++ b/translations/zh-TW/AGENTS.md @@ -1,28 +1,28 @@ # AGENTS.md -## 專案概述 +## 專案概覽 -這是一個教育課程資源庫，旨在教授初學者網頁開發基礎。該課程是由 Microsoft Cloud Advocates 開發的完整 12 週課程，包含 24 個實作課程，涵蓋 JavaScript、CSS 和 HTML。 +這是一個教育課程資源庫，用於教授初學者網頁開發基礎知識。課程是一個由 Microsoft Cloud Advocates 開發的完整 12 週課程，包含 24 節實作課程，涵蓋 JavaScript、CSS 和 HTML。 -### 主要組件 +### 主要組成 -- **教育內容**：24 個結構化課程，組織成專案導向模組 -- **實作專案**：Terrarium、打字遊戲、瀏覽器擴充功能、太空遊戲、銀行應用、程式碼編輯器和 AI 聊天助理 -- **互動測驗**：48 組測驗，每組包含 3 題（課前/課後評估） -- **多語言支援**：透過 GitHub Actions 自動翻譯 50 多種語言 -- **技術使用**：HTML、CSS、JavaScript、Vue.js 3、Vite、Node.js、Express、Python（用於 AI 專案） +- **教育內容**：24 節有結構的課程，組成專案導向模組 +- **實務專案**：植物生態箱、打字遊戲、瀏覽器擴充套件、太空遊戲、銀行應用程式、程式碼編輯器以及 AI 聊天助理 +- **互動測驗**：48 次測驗，每次有 3 題（課前/課後評估） +- **多語言支援**：透過 GitHub Actions 自動翻譯成 50 多種語言 +- **技術堆疊**：HTML、CSS、JavaScript、Vue.js 3、Vite、Node.js、Express、Python（AI 專案） ### 架構 - 以課程為基礎的教育資源庫 -- 每個課程資料夾包含 README、程式碼範例及解答 -- 独立專案在不同目錄（quiz-app、各種課程專案） -- 使用 GitHub Actions（co-op-translator）進行翻譯系統 -- 文件透過 Docsify 提供並可轉為 PDF +- 每個課程資料夾包含 README、程式碼範例和解答 +- 獨立專案位於不同資料夾（quiz-app、各種課程專案） +- 使用 GitHub Actions（co-op-translator）做翻譯系統 +- 文件透過 Docsify 提供並可下載 PDF ## 設定指令 -此資源庫主要用於教育內容的學習。若要操作特定專案： +此資源庫主要是供教育內容使用。如需操作特定專案： ### 主要資源庫設定 @@ -31,13 +31,13 @@ git clone https://github.com/microsoft/Web-Dev-For-Beginners.git cd Web-Dev-For-Beginners ``` -### 測驗應用程式設定 (Vue 3 + Vite) +### 測驗應用設定 (Vue 3 + Vite) ```bash cd quiz-app npm install npm run dev # 啟動開發伺服器 -npm run build # 建置生產環境 +npm run build # 建立生產版本 npm run lint # 執行 ESLint ``` @@ -46,17 +46,17 @@ npm run lint # 執行 ESLint ```bash cd 7-bank-project/api npm install -npm start # 啟動 API 服務器 +npm start # 啟動 API 伺服器 npm run lint # 執行 ESLint npm run format # 使用 Prettier 格式化 ``` -### 瀏覽器擴充功能專案 +### 瀏覽器擴充專案 ```bash cd 5-browser-extension/solution npm install -# 遵循瀏覽器特定的擴充功能載入說明 +# 遵循瀏覽器特定的擴充功能加載說明 ``` ### 太空遊戲專案 @@ -64,7 +64,7 @@ npm install ```bash cd 6-space-game/solution npm install -# 在瀏覽器中打開 index.html 或使用即時伺服器 +# 在瀏覽器中打開 index.html 或使用 Live Server ``` ### 聊天專案 (Python 後端) @@ -78,40 +78,40 @@ python api.py ## 開發工作流程 -### 給內容貢獻者 +### 內容貢獻者 -1. **Fork 資源庫** 到你的 GitHub 帳號 -2. **Clone 你的 fork** 到本地端 -3. **建立新分支** 進行修改 -4. 對課程內容或程式碼範例做出修改 -5. 在相關專案資料夾測試程式碼修改 -6. 遵循貢獻指南提交 pull request +1. **將資源庫 fork** 至您的 GitHub 帳號 +2. **將 fork 的版本 clone** 到本地 +3. **建立新分支** 以進行修改 +4. 修改課程內容或程式碼範例 +5. 在相關專案資料夾測試程式碼更動 +6. 按貢獻指引提交 pull request -### 給學習者 +### 學習者 1. Fork 或 clone 資源庫 -2. 依序瀏覽課程目錄 -3. 閱讀每個課程的 README 檔案 -4. 完成 https://ff-quizzes.netlify.app/web/ 的課前測驗 -5. 進行課程資料夾中的程式碼範例 +2. 按順序瀏覽課程資料夾 +3. 閱讀每課 README 檔案 +4. 完成課前測驗，網址為 https://ff-quizzes.netlify.app/web/ +5. 運行課程資料夾中的程式碼範例 6. 完成作業與挑戰 7. 參加課後測驗 -### 實時開發環境 +### 線上開發 -- **文件**：於根目錄執行 `docsify serve` (port 3000) -- **測驗 App**：於 quiz-app 目錄執行 `npm run dev` -- **專案**：使用 VS Code Live Server 套件服務 HTML 專案 -- **API 專案**：於各 API 目錄執行 `npm start` +- **文件**：於根目錄執行 `docsify serve`（預設埠號 3000） +- **測驗應用**：於 quiz-app 目錄執行 `npm run dev` +- **專案**：使用 VS Code Live Server 擴充套件服務 HTML 專案 +- **API 專案**：於對應的 API 目錄執行 `npm start` -## 測試說明 +## 測試指導 -### 測驗應用程式測試 +### 測驗應用測試 ```bash cd quiz-app npm run lint # 檢查程式碼風格問題 -npm run build # 確認建置成功 +npm run build # 驗證建置是否成功 ``` ### 銀行 API 測試 @@ -119,81 +119,81 @@ npm run build # 確認建置成功 ```bash cd 7-bank-project/api npm run lint # 檢查程式碼風格問題 -node server.js # 驗證伺服器是否無錯誤啟動 +node server.js # 驗證伺服器啟動是否無錯誤 ``` -### 一般測試方式 +### 一般測試方法 -- 此為教育資源庫，無全面自動化測試 -- 手動測試重點： - - 程式碼範例無錯誤執行 - - 文件中連結正確 - - 專案成功編譯 +- 本教育資源庫無完整自動化測試 +- 以人工測試為主，重點在： + - 程式碼範例能正常執行無錯誤 + - 文件中的連結正常運作 + - 專案能成功打造（build） - 範例遵循最佳實務 ### 提交前檢查 -- 於含 package.json 的目錄執行 `npm run lint` -- 驗證 markdown 連結有效 -- 在瀏覽器或 Node.js 中測試程式碼範例 -- 確認翻譯保持正確結構 +- 在有 package.json 的目錄執行 `npm run lint` +- 確認 markdown 連結有效 +- 在瀏覽器或 Node.js 測試程式碼範例 +- 檢查翻譯內容結構是否保持正確 ## 程式碼風格指南 ### JavaScript - 使用現代 ES6+ 語法 -- 遵循專案內 ESLint 既有設定 -- 使用具有意義的變數與函式命名以便教學理解 -- 補充註解說明概念給學習者 -- 配合 Prettier 格式化（配置時） +- 遵循專案中提供的標準 ESLint 設定 +- 使用具教育意義的變數與函式名稱 +- 添加註解以解釋概念，幫助學習者理解 +- 使用配置好的 Prettier 格式化 ### HTML/CSS -- 使用語意化 HTML5 元素 -- 響應式設計原則 -- 明確的類別命名慣例 -- 補充 CSS 技巧註解給學習者 +- 使用語義化的 HTML5 元素 +- 採用響應式設計原則 +- 清晰的類別命名慣例 +- 用註解闡述 CSS 技巧以便教學 ### Python - 遵守 PEP 8 風格指南 -- 清晰且具教學性的程式碼範例 -- 依需求加入型別提示輔助學習 +- 清晰、具教育意義的程式碼範例 +- 必要時使用型別提示，便利學習 ### Markdown 文件 -- 清楚標題層級 -- 指定語言的程式碼區塊 -- 連結至附加資源 -- 在 `images/` 目錄中放置截圖與圖片 -- 為圖片標註替代文字以提升可及性 +- 清晰的標題層級結構 +- 語言標明的程式碼區塊 +- 提供相關資源鏈結 +- `images/` 資料夾內的截圖與圖片 +- 圖片皆有替代文字以便無障礙使用 ### 檔案組織 -- 課程依序編號（1-getting-started-lessons、2-js-basics 等） -- 每個專案包含 `solution/`，且常見 `start/` 或 `your-work/` -- 圖片儲存在各課程特定的 `images/` 資料夾 -- 翻譯置於 `translations/{language-code}/` 結構中 +- 課程依序編號（如 1-getting-started-lessons、2-js-basics 等） +- 每個專案包含 `solution/`，常見還有 `start/` 或 `your-work/` 目錄 +- 圖片存放於每課特定的 `images/` 資料夾 +- 翻譯檔案置於 `translations/{language-code}/` 結構 ## 建置與部署 -### 測驗應用程式部署 (Azure 靜態網站) +### 測驗應用部署 (Azure 靜態網頁應用) -quiz-app 已設置為 Azure 靜態網頁應用部署： +quiz-app 已設定 Azure 靜態網頁應用部署： ```bash cd quiz-app npm run build # 建立 dist/ 資料夾 -# 在推送到 main 時透過 GitHub Actions 工作流程部署 +# 在推送到 main 時，透過 GitHub Actions 工作流程進行部署 ``` -Azure 靜態網站配置： -- **應用程式位置**：`/quiz-app` +Azure 靜態網頁應用配置： +- **應用位置**：`/quiz-app` - **輸出位置**：`dist` - **工作流程**：`.github/workflows/azure-static-web-apps-ashy-river-0debb7803.yml` -### 文件 PDF 產生 +### 文件 PDF 生成 ```bash npm install # 安裝 docsify-to-pdf @@ -209,74 +209,74 @@ docsify serve # 在 localhost:3000 提供服務 ### 專案特定建置 -各專案目錄可能有專屬建置流程： -- Vue 專案：`npm run build` 建立產線包 -- 靜態專案：無建置步驟，直接服務檔案 +每個專案目錄可能有各自的建置流程： +- Vue 專案：`npm run build` 產生生產環境套件 +- 靜態專案：無需建置，直接提供靜態檔案 -## Pull Request 指南 +## Pull Request 指引 ### 標題格式 -使用清楚描述變更範圍的標題： -- `[Quiz-app] 新增第 X 課測驗` -- `[Lesson-3] 修正 terrarium 專案錯字` +使用清晰且描述性的標題來表示更動範圍： +- `[Quiz-app] 新增課程 X 測驗` +- `[Lesson-3] 修正植物生態箱專案的錯字` - `[Translation] 新增第 5 課西班牙語翻譯` -- `[Docs] 更新設定指令` +- `[Docs] 更新安裝說明` ### 必要檢查 -提出 PR 前： +提交 PR 前： 1. **程式碼品質**： - - 在受影響專案目錄執行 `npm run lint` - - 修正所有 lint 錯誤與警告 + - 在受影響的專案目錄執行 `npm run lint` + - 修正所有 lint 錯誤及警告 2. **建置驗證**： - - 如適用，執行 `npm run build` - - 確認無建置失敗 + - 如有需建置，執行 `npm run build` + - 確認無建置錯誤 3. **連結驗證**： - 測試所有 markdown 連結 - - 確認圖片參考正常 + - 確認圖片引用正確 -4. **內容審查**： - - 校對拼字和文法 - - 確保程式碼範例正確且具教學意義 - - 驗證翻譯保持原意 +4. **內容審核**： + - 校對拼字及語法 + - 確認程式碼範例正確且具教育意義 + - 檢查翻譯是否維持原意 ### 貢獻要求 -- 同意 Microsoft CLA（首次 PR 會自動檢查） +- 同意 Microsoft CLA（第一個 PR 會自動檢查） - 遵守 [Microsoft 開源行為守則](https://opensource.microsoft.com/codeofconduct/) -- 詳細指南見 [CONTRIBUTING.md](./CONTRIBUTING.md) -- 如有適用，在 PR 描述中引用議題號碼 +- 詳細指引請參考 [CONTRIBUTING.md](./CONTRIBUTING.md) +- 若有相關議題，請於 PR 描述中引用議題編號 ### 審查流程 -- PR 經維護者及社群審核 -- 優先確保教育的清晰度 -- 程式碼範例應遵循現行最佳實務 -- 翻譯需審核精確與文化適切性 +- PR 將由維護者與社群共同審查 +- 優先考量教育內容清晰度 +- 程式碼範例應符合當前最佳實務 +- 翻譯審查求精確與文化適切 ## 翻譯系統 ### 自動翻譯 -- 利用 GitHub Actions 搭配 co-op-translator 工作流程 +- 使用 GitHub Actions 搭配 co-op-translator 工作流程 - 自動翻譯超過 50 種語言 -- 源檔置於主要目錄 -- 翻譯檔置於 `translations/{language-code}/` 目錄 +- 原始檔置於主要目錄 +- 翻譯檔存於 `translations/{language-code}/` 目錄 -### 手動翻譯改進 +### 手動優化翻譯 -1. 找到 `translations/{language-code}/` 下對應檔案 -2. 保持結構下改進翻譯 -3. 確保程式碼範例仍可正常運行 -4. 測試本地化測驗內容 +1. 找到檔案於 `translations/{language-code}/` +2. 改善翻譯內容，同時保持結構 +3. 確保程式碼範例可正常執行 +4. 測試本地化的測驗內容 -### 翻譯檔元數據 +### 翻譯元資料 -翻譯檔含元資料標頭： +翻譯檔包含元資料標頭： ```markdown -**免責聲明**： -本文件係使用 AI 翻譯服務 [Co-op Translator](https://github.com/Azure/co-op-translator) 進行翻譯。雖然我們努力確保翻譯的準確性，但請注意自動翻譯可能包含錯誤或不準確之處。原始文件的母語版本應視為權威依據。對於重要資訊，建議尋求專業人工翻譯。我們不對因使用本翻譯而產生的任何誤解或誤譯負責。 +**免責聲明**： +本文件係使用 AI 翻譯服務 [Co-op Translator](https://github.com/Azure/co-op-translator) 進行翻譯。儘管我們盡力確保翻譯的準確性，但請注意自動翻譯可能包含錯誤或不準確之處。原始文件的原文版本應視為權威來源。對於重要資訊，建議採用專業人工翻譯。我們不對因使用本翻譯而產生的任何誤解或誤譯負責。 \ No newline at end of file