Merge branch 'main' into copilot/add-content-translation-arabic

Author: brunoborges

.github/agents/agentic-workflows.agent.md

@@ -15,7 +15,10 @@ This is a **dispatcher agent** that routes your request to the appropriate speci
 - **Updating existing workflows**: Routes to `update` prompt
 - **Debugging workflows**: Routes to `debug` prompt  
 - **Upgrading workflows**: Routes to `upgrade-agentic-workflows` prompt
+- **Creating report-generating workflows**: Routes to `report` prompt — consult this whenever the workflow posts status updates, audits, analyses, or any structured output as issues, discussions, or comments
 - **Creating shared components**: Routes to `create-shared-agentic-workflow` prompt
+- **Fixing Dependabot PRs**: Routes to `dependabot` prompt — use this when Dependabot opens PRs that modify generated manifest files (`.github/workflows/package.json`, `.github/workflows/requirements.txt`, `.github/workflows/go.mod`). Never merge those PRs directly; instead update the source `.md` files and rerun `gh aw compile --dependabot` to bundle all fixes
+- **Analyzing test coverage**: Routes to `test-coverage` prompt — consult this whenever the workflow reads, analyzes, or reports on test coverage data from PRs or CI runs
 
 Workflows may optionally include:
 
@@ -27,7 +30,7 @@ Workflows may optionally include:
 - Workflow files: `.github/workflows/*.md` and `.github/workflows/**/*.md`
 - Workflow lock files: `.github/workflows/*.lock.yml`
 - Shared components: `.github/workflows/shared/*.md`
-- Configuration: https://github.com/github/gh-aw/blob/v0.46.1/.github/aw/github-agentic-workflows.md
+- Configuration: https://github.com/github/gh-aw/blob/v0.50.4/.github/aw/github-agentic-workflows.md
 
 ## Problems This Solves
 
@@ -49,7 +52,7 @@ When you interact with this agent, it will:
 ### Create New Workflow
 **Load when**: User wants to create a new workflow from scratch, add automation, or design a workflow that doesn't exist yet
 
-**Prompt file**: https://github.com/github/gh-aw/blob/v0.46.1/.github/aw/create-agentic-workflow.md
+**Prompt file**: https://github.com/github/gh-aw/blob/v0.50.4/.github/aw/create-agentic-workflow.md
 
 **Use cases**:
 - "Create a workflow that triages issues"
@@ -59,7 +62,7 @@ When you interact with this agent, it will:
 ### Update Existing Workflow  
 **Load when**: User wants to modify, improve, or refactor an existing workflow
 
-**Prompt file**: https://github.com/github/gh-aw/blob/v0.46.1/.github/aw/update-agentic-workflow.md
+**Prompt file**: https://github.com/github/gh-aw/blob/v0.50.4/.github/aw/update-agentic-workflow.md
 
 **Use cases**:
 - "Add web-fetch tool to the issue-classifier workflow"
@@ -69,7 +72,7 @@ When you interact with this agent, it will:
 ### Debug Workflow  
 **Load when**: User needs to investigate, audit, debug, or understand a workflow, troubleshoot issues, analyze logs, or fix errors
 
-**Prompt file**: https://github.com/github/gh-aw/blob/v0.46.1/.github/aw/debug-agentic-workflow.md
+**Prompt file**: https://github.com/github/gh-aw/blob/v0.50.4/.github/aw/debug-agentic-workflow.md
 
 **Use cases**:
 - "Why is this workflow failing?"
@@ -79,23 +82,53 @@ When you interact with this agent, it will:
 ### Upgrade Agentic Workflows
 **Load when**: User wants to upgrade workflows to a new gh-aw version or fix deprecations
 
-**Prompt file**: https://github.com/github/gh-aw/blob/v0.46.1/.github/aw/upgrade-agentic-workflows.md
+**Prompt file**: https://github.com/github/gh-aw/blob/v0.50.4/.github/aw/upgrade-agentic-workflows.md
 
 **Use cases**:
 - "Upgrade all workflows to the latest version"
 - "Fix deprecated fields in workflows"
 - "Apply breaking changes from the new release"
 
+### Create a Report-Generating Workflow
+**Load when**: The workflow being created or updated produces reports — recurring status updates, audit summaries, analyses, or any structured output posted as a GitHub issue, discussion, or comment
+
+**Prompt file**: https://github.com/github/gh-aw/blob/v0.50.4/.github/aw/report.md
+
+**Use cases**:
+- "Create a weekly CI health report"
+- "Post a daily security audit to Discussions"
+- "Add a status update comment to open PRs"
+
 ### Create Shared Agentic Workflow
 **Load when**: User wants to create a reusable workflow component or wrap an MCP server
 
-**Prompt file**: https://github.com/github/gh-aw/blob/v0.46.1/.github/aw/create-shared-agentic-workflow.md
+**Prompt file**: https://github.com/github/gh-aw/blob/v0.50.4/.github/aw/create-shared-agentic-workflow.md
 
 **Use cases**:
 - "Create a shared component for Notion integration"
 - "Wrap the Slack MCP server as a reusable component"
 - "Design a shared workflow for database queries"
 
+### Fix Dependabot PRs
+**Load when**: User needs to close or fix open Dependabot PRs that update dependencies in generated manifest files (`.github/workflows/package.json`, `.github/workflows/requirements.txt`, `.github/workflows/go.mod`)
+
+**Prompt file**: https://github.com/github/gh-aw/blob/v0.50.4/.github/aw/dependabot.md
+
+**Use cases**:
+- "Fix the open Dependabot PRs for npm dependencies"
+- "Bundle and close the Dependabot PRs for workflow dependencies"
+- "Update @playwright/test to fix the Dependabot PR"
+
+### Analyze Test Coverage
+**Load when**: The workflow reads, analyzes, or reports test coverage — whether triggered by a PR, a schedule, or a slash command. Always consult this prompt before designing the coverage data strategy.
+
+**Prompt file**: https://github.com/github/gh-aw/blob/v0.50.4/.github/aw/test-coverage.md
+
+**Use cases**:
+- "Create a workflow that comments coverage on PRs"
+- "Analyze coverage trends over time"
+- "Add a coverage gate that blocks PRs below a threshold"
+
 ## Instructions
 
 When a user interacts with you:
@@ -136,8 +169,9 @@ gh aw compile --validate
 
 ## Important Notes
 
-- Always reference the instructions file at https://github.com/github/gh-aw/blob/v0.46.1/.github/aw/github-agentic-workflows.md for complete documentation
+- Always reference the instructions file at https://github.com/github/gh-aw/blob/v0.50.4/.github/aw/github-agentic-workflows.md for complete documentation
 - Use the MCP tool `agentic-workflows` when running in GitHub Copilot Cloud
 - Workflows must be compiled to `.lock.yml` files before running in GitHub Actions
 - **Bash tools are enabled by default** - Don't restrict bash commands unnecessarily since workflows are sandboxed by the AWF
 - Follow security best practices: minimal permissions, explicit network access, no template injection
+- **Single-file output**: When creating a workflow, produce exactly **one** workflow `.md` file. Do not create separate documentation files (architecture docs, runbooks, usage guides, etc.). If documentation is needed, add a brief `## Usage` section inside the workflow file itself.

.github/aw/actions-lock.json

@@ -4,6 +4,11 @@
       "repo": "actions/github-script",
       "version": "v8",
       "sha": "ed597411d8f924073f98dfc5c65a23a2325f34cd"
+    },
+    "github/gh-aw/actions/setup@v0.50.4": {
+      "repo": "github/gh-aw/actions/setup",
+      "version": "v0.50.4",
+      "sha": "90ebf8057e8e005103b8d123732d2c64c30e9b27"
     }
   }
 }

.github/copilot-instructions.md

@@ -18,33 +18,48 @@ content/streams/stream-tolist.json
 ...
 ```
 
-**Categories:** `language`, `collections`, `strings`, `streams`, `concurrency`, `io`, `errors`, `datetime`, `security`, `tooling`
+**Categories:** `language`, `collections`, `strings`, `streams`, `concurrency`, `io`, `errors`, `datetime`, `security`, `tooling`, `enterprise`
 
 ### Generated Files (DO NOT EDIT)
 
 The following are **generated by `html-generators/generate.java`** and must not be edited directly:
 
-- `site/index.html` — homepage with preview cards (generated from `templates/index.html`)
-- `site/language/*.html`, `site/collections/*.html`, etc. — detail pages
-- `site/data/snippets.json` — aggregated search index
+- `site/index.html` — English homepage with preview cards (generated from `templates/index.html`)
+- `site/language/*.html`, `site/collections/*.html`, etc. — English detail pages
+- `site/data/snippets.json` — English aggregated search index
+- `site/{locale}/index.html` — localized homepage (e.g., `site/es/index.html`)
+- `site/{locale}/language/*.html`, etc. — localized detail pages
+- `site/{locale}/data/snippets.json` — localized search index
 
-Run `jbang html-generators/generate.java` to rebuild all generated files from the JSON sources.
+Run `jbang html-generators/generate.java` to rebuild all generated files from the JSON sources and translations.
 
 ### Manually Maintained Files
 
-- `site/app.js` — client-side search, filtering, code highlighting
+- `site/app.js` — client-side search, filtering, code highlighting, locale detection
 - `site/styles.css` — all styling
-- `templates/slug-template.html` — HTML template with `{{placeholder}}` tokens used by the generator
-- `templates/index.html` — homepage template with `{{tipCards}}` and `{{snippetCount}}` placeholders
+- `templates/slug-template.html` — HTML template with `{{placeholder}}` tokens (content + UI strings) used by the generator
+- `templates/index.html` — homepage template with `{{tipCards}}`, `{{snippetCount}}`, and UI string placeholders
 - `templates/index-card.html` — preview card template for the homepage grid
+- `html-generators/categories.properties` — category ID → display name mapping
+- `html-generators/locales.properties` — supported locales registry (locale=Display name)
+- `translations/strings/{locale}.yaml` — UI strings per locale (labels, nav, footer, etc.)
+- `translations/content/{locale}/` — translated pattern JSON files (partial, translatable fields only)
 
 ### Project Structure
 
 ```
-content/            # Source JSON files (one per pattern, organized by category)
+content/            # English content JSON files (source of truth, one per pattern)
+translations/       # All i18n artifacts
+  strings/          # UI strings per locale (en.yaml, es.yaml, pt-BR.yaml)
+  content/          # Translated pattern files per locale (partial, translatable fields only)
+    es/             # Spanish translations (mirrors content/ folder structure)
+    pt-BR/          # Brazilian Portuguese translations
 site/               # Deployable site (static assets + generated HTML)
-templates/          # HTML templates for detail pages
-html-generators/    # Build scripts and pre-built JAR
+  es/               # Generated Spanish pages
+  pt-BR/            # Generated Portuguese pages
+templates/          # HTML templates with {{…}} tokens for content + UI strings
+html-generators/    # Build scripts, categories.properties, locales.properties
+specs/              # Feature specifications (e.g., i18n-spec.md)
 ```
 
 ## JSON Snippet Schema
@@ -101,6 +116,8 @@ Each `content/category/slug.json` file has this structure:
 
 ## Category Display Names
 
+Categories and their display names are defined in `html-generators/categories.properties`:
+
 | ID | Display |
 |----|---------|
 | `language` | Language |
@@ -113,12 +130,59 @@ Each `content/category/slug.json` file has this structure:
 | `datetime` | Date/Time |
 | `security` | Security |
 | `tooling` | Tooling |
+| `enterprise` | Enterprise |
 
 ## Adding a New Pattern
 
 1. Create `content/category/new-slug.json` with all required fields
 2. Update `prev`/`next` in the adjacent patterns' JSON files
 3. Run `jbang html-generators/generate.java`
+4. (Optional) Create translated content files under `translations/content/{locale}/category/new-slug.json` with only translatable fields — or let the AI translation workflow handle it
+
+## Internationalization (i18n)
+
+The site supports multiple languages. See `specs/i18n/i18n-spec.md` for the full specification.
+
+### Key Concepts
+
+- **UI strings:** Hard-coded template text (labels, nav, footer) is extracted into `translations/strings/{locale}.yaml`. Templates use `{{dotted.key}}` tokens (e.g., `{{nav.allPatterns}}`, `{{sections.codeComparison}}`). Missing keys fall back to the English value with a build-time warning.
+- **Content translations:** Translated pattern files under `translations/content/{locale}/` contain **only** translatable fields (`title`, `summary`, `explanation`, `oldApproach`, `modernApproach`, `whyModernWins`, `support.description`). All other fields (`oldCode`, `modernCode`, `slug`, `id`, `prev`, `next`, `related`, `docs`, etc.) are always taken from the English source.
+- **Locale registry:** `html-generators/locales.properties` lists supported locales (format: `locale=Display name`). The first entry is the default.
+- **English is a first-class locale:** All locales — including English — go through the same build pipeline.
+- **Fallback:** If a pattern has no translation file for a locale, the English content is used and an "untranslated" banner is shown.
+
+### Supported Locales
+
+Defined in `html-generators/locales.properties`:
+
+| Locale | Display Name |
+|--------|-------------|
+| `en` | English |
+| `es` | Español |
+| `pt-BR` | Português (Brasil) |
+
+### Content Translation File Example
+
+Translation files contain **only** translatable fields — no structural data:
+
+```json
+// translations/content/pt-BR/language/type-inference-with-var.json
+{
+  "title": "Inferência de tipo com var",
+  "oldApproach": "Tipos explícitos",
+  "modernApproach": "Palavra-chave var",
+  "summary": "Use var para deixar o compilador inferir o tipo local.",
+  "explanation": "...",
+  "whyModernWins": [
+    { "icon": "⚡", "title": "Menos ruído", "desc": "..." },
+    { "icon": "👁",  "title": "Mais legível", "desc": "..." },
+    { "icon": "🔒", "title": "Seguro", "desc": "..." }
+  ],
+  "support": {
+    "description": "Amplamente disponível desde o JDK 10 (março de 2018)"
+  }
+}
+```
 
 ## Local Development