github-samples · GeekTrainer · Jul 15, 2026 · Jul 15, 2026 · Jul 15, 2026 · Jul 15, 2026
diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
@@ -10,6 +10,7 @@ This repo hosts the **workshop content** for *Agents in SDLC*, published as an A
   - `src/content/docs/` — **Source Markdown for all lessons. Edit here.**
     - `index.md` — Workshop landing page.
     - `cli/`, `vscode/`, `cloud/`, `app/` — Per-harness lessons (Copilot CLI / VS Code / Cloud agent / GitHub Copilot app). Each harness opens with its own `0-prerequisites.md` setup lesson; the CLI and VS Code harnesses set up a codespace, while the app and cloud harnesses cover the setup their flow needs (for the app, installing Node.js locally and creating the project from the template).
+    - `es-es/`, `ja-jp/`, `ko-kr/`, `pt-br/`, `zh-cn/` — Localized content at the locale-root paths required by Starlight. Translated pages mirror the English path beneath each locale directory; untranslated pages use Starlight's English fallback.
     - `_images/` — Screenshots and diagrams.
   - `astro.config.mjs` — Site config including the manually maintained sidebar. The legacy `/shared/0-prereqs/` → home (`/`) redirect is a full-HTML redirect page at `src/pages/shared/0-prereqs.astro` (not an `astro.config.mjs` `redirects` entry, which would emit a stub with no `<html>` element that Pagefind can't index). Prerequisites are now per-harness (`/<harness>/0-prerequisites/`), so the old shared-prereqs URL forwards to the home page.
   - `src/content.config.ts` — Custom content loader that excludes underscore-prefixed support directories so `_images/` is not routed as content.

diff --git a/.github/instructions/astro.instructions.md b/.github/instructions/astro.instructions.md
@@ -20,4 +20,4 @@ This is a docs wrapper. Don't add interactive framework islands (Svelte, React,
 
 ## Building and verifying
 
-After changing `astro.config.mjs` or anything under `docs/src/`, build and verify the site with the [`build-and-verify-docs`](../skills/build-and-verify-docs/SKILL.md) skill. Its page-count invariant is the tripwire for unexpected routed pages: if the build emits more pages than `36 routable Markdown pages + 1 legacy redirect` without a matching content change, check the underscore-directory exclude in `src/content.config.ts`.
+After changing `astro.config.mjs` or anything under `docs/src/`, build and verify the site with the [`build-and-verify-docs`](../skills/build-and-verify-docs/SKILL.md) skill. Its page-count invariant is the tripwire for unexpected routed pages: Starlight emits each of the 36 workshop routes for the root language and five configured locales, then adds the legacy redirect, for 217 built `index.html` pages excluding the 404 page. If the count changes without a corresponding route or locale change, check the locale layout and the underscore-directory exclude in `src/content.config.ts`.
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
@@ -16,7 +16,7 @@
 
 <!-- Confirm the build + link checks pass before requesting review. -->
 
-- [ ] `cd docs && rm -rf dist && npm run build` succeeds (target: 36 routable pages + 1 redirect = 37 built pages excluding 404; build reports 38 HTML files including 404, or note any intentional change)
+- [ ] `cd docs && rm -rf dist && npm run build` succeeds (target: 36 routes × 6 locales + 1 redirect = 217 built pages excluding 404; build reports 218 HTML files including 404, or note any intentional change)
 - [ ] Lychee link check passes:
       `mkdir -p /tmp/lychee-root && ln -sfn $PWD/docs/dist /tmp/lychee-root/agents-in-sdlc && lychee --offline --no-progress --root-dir /tmp/lychee-root 'docs/dist/**/*.html'`
 - [ ] External GitHub URLs that I changed have been clicked manually (lychee runs offline)

diff --git a/.github/skills/build-and-verify-docs/SKILL.md b/.github/skills/build-and-verify-docs/SKILL.md
@@ -43,16 +43,21 @@ cd docs && rm -rf dist && npm run build
 
 ### 2. Page-count invariant
 
-The built page count should equal the 36 routable `.md` files under `docs/src/content/docs/` plus the one legacy redirect (`/shared/0-prereqs/`, authored as a full-HTML redirect page at `docs/src/pages/shared/0-prereqs.astro`). The expected count is 37 `index.html` files when excluding the 404 page. Astro reports 38 HTML files because it includes the 404 page.
+The workshop has 36 distinct route slugs. Starlight emits each route for the English root locale and the five configured localized routes, using English fallback content when a translation is unavailable. The built site therefore contains $36 \times 6 = 216$ workshop routes plus the one legacy redirect (`/shared/0-prereqs/`, authored as a full-HTML redirect page at `docs/src/pages/shared/0-prereqs.astro`). The expected count is 217 `index.html` files when excluding the 404 page. Astro reports 218 HTML files because it includes the 404 page.
 
 ```bash
-# routable Markdown pages (expected pages, minus the redirect)
-find docs/src/content/docs -name '*.md' | wc -l
+# distinct route slugs in the English root locale
+find docs/src/content/docs -maxdepth 2 -name '*.md' \
+  ! -path 'docs/src/content/docs/es-es/*' \
+  ! -path 'docs/src/content/docs/ja-jp/*' \
+  ! -path 'docs/src/content/docs/ko-kr/*' \
+  ! -path 'docs/src/content/docs/pt-br/*' \
+  ! -path 'docs/src/content/docs/zh-cn/*' | wc -l
 # built pages (excludes the 404)
 find docs/dist -name index.html | grep -v 404 | wc -l
 ```
 
-`built pages` should equal `routable Markdown pages + 1`. If the build emits **more** pages than that without a matching `.md` change, check the underscore-directory exclude in `docs/src/content.config.ts`; it is still needed so support directories such as `_images/` are not routed as pages.
+`built pages` should equal `(distinct route slugs × configured locales) + 1`. If the build emits **more** pages than that without a matching route or locale change, confirm localized content is directly under `docs/src/content/docs/<locale>/` rather than an extra parent directory, then check the underscore-directory exclude in `docs/src/content.config.ts`; it is still needed so support directories such as `_images/` are not routed as pages.
 
 ### 3. Link check (lychee, offline)
 

diff --git a/.github/skills/localizations/SKILL.md b/.github/skills/localizations/SKILL.md
@@ -0,0 +1,101 @@
+---
+name: localizations
+description: A skill that localizes contents into given locales.
+---
+
+# Localize contents into given locales
+
+A skill that localizes contents into given locales.
+
+## How it works
+
+The skill takes input content and a list of target locales. It then translates the content into each specified locale, providing localized versions for each.
+
+### Content structure
+
+```text
+.
+├── README.md
+├── docs/
+│   ├── *.md
+│   └── <any/path>/
+│       └── *.md
+└── docs/
+    └── src/content/docs/
+        └── <locale>/
+            ├── index.md
+            └── <any/path>/
+                └── *.md
+```
+
+### Input contents
+
+Here are the list of contents for localization:
+
+- `README.md`: The main documentation file for the project.
+- All markdown files in the `docs` directory **and its subdirectories** (`docs/**/*.md`): The main content files for the project documentation.
+
+Both `README.md` and the `docs` tree are in scope. The **`docs`** directory is the default location for content files, but `README.md` at the project root is always included as well.
+
+Files already under `docs/src/content/docs/<locale>/` are **outputs**, not inputs—never treat configured locale-root directories as source content to be localized again.
+
+### Target locales
+
+Target locales are defined in the `rules` directory as markdown files in this skill (`rules/ko-kr.md`, for example). **To determine which locales to process, list the files in `rules/`: each `<locale>.md` file corresponds to exactly one supported target locale.** Each locale has its own set of rules and guidelines for translation, ensuring that the localized content is appropriate for the target audience.
+
+Locale identifiers use lowercase with a hyphen (for example, `ko-kr`). This is the canonical casing for both the rules filename and the output directory in this skill; keep them consistent.
+
+### Output contents
+
+All localized workshop content is stored directly under the Starlight content root, with each locale having its own subdirectory. For example, Korean content is stored in `docs/src/content/docs/ko-kr/`.
+
+Locale directories must be direct children of `docs/src/content/docs/` so Starlight recognizes them and renders its language selector. Do not add an intermediate `localizations/` directory.
+
+## Localization process
+
+There are three cases for localization. To detect which case applies, compare the **source tree** against the existing `docs/src/content/docs/<locale>/` tree, and use the **git history of the source files** to detect changes:
+
+- **Original exists, no localized version for the locale:** Create a new localized document.
+- **Both original and localized versions exist:** Compare the source tree against `docs/src/content/docs/<locale>/`, then run `git diff` (or `git log`) on the **source** file to find what changed since the localized version was last produced. Update only the affected sections of the localized document; do not re-translate unchanged sections unnecessarily.
+- **Localized version exists, but the original has been deleted:** Delete the orphaned localized document (and prune now-empty locale subdirectories).
+
+The process runs in two passes. First, the content is analyzed to identify key phrases and context. Then the `translator` agent performs the initial localization, followed by a review-and-refinement pass by the `evaluator` agent to ensure quality and consistency.
+
+> The `translator` and `evaluator` "agents" are **roles/personas**, not external tools. If no dedicated sub-agents are available, perform them as sequential personas: first adopt the translator role to produce the draft, then adopt the evaluator role to critique and refine that draft against the locale rules. Repeat the refinement loop until the evaluator's criteria pass.
+
+### Markdown and formatting preservation
+
+Regardless of locale, the following must be preserved exactly and **not** translated:
+
+- YAML frontmatter **keys** (translate values only where appropriate, e.g. a `title`).
+- Fenced and inline code, including variable, function, and command names.
+- URLs and external link targets.
+- HTML tags, Markdown structure, tables, and admonition markers.
+
+Translate human-language prose, including comments inside code blocks where they are explanatory (per the locale rules). Keep heading order and document structure stable.
+
+**Heading anchors follow the localized text.** When a heading is translated, its auto-generated anchor/slug changes with it—this is expected. The requirement is that **same-document anchor links keep resolving**: whenever you translate a heading, update every in-page link that targets it (`](#...)`) to the localized heading's new slug. Do not leave a link pointing at the original English slug once the heading is translated, and do not preserve an English anchor that no longer matches its heading. Anchors that point into **non-localized** files (or external URLs) keep their original target.
+
+**Image and asset paths point to the original assets unless a localized asset exists.** Because localized files live under `docs/src/content/docs/<locale>/`, rewrite source-relative paths as needed so they still resolve to the shared asset (for example, an app lesson uses `../../_images/x.png`). Only point at a localized asset when a corresponding translated image actually exists under the locale tree. Either way, the link must resolve to a real file.
+
+### Translator agent
+
+Use the `translator` agent to perform the localization. It should follow the rules and guidelines defined for each target locale document in the `rules` directory.
+
+### Evaluator agent
+
+Use the `evaluator` agent to assess the quality of the localized content. The evaluator checks for accuracy, cultural relevance, and overall quality, following the rules and guidelines defined for the target locale in the `rules` directory.
+
+The evaluator scores the localized document against the locale's **Evaluator Scoring Rubric** (defined in the locale's `rules/<locale>.md`). The rubric uses two tiers: **Tier A** hard-fail criteria that must score 5, and **Tier B** graded criteria (1–5) that must score 4 or 5. A document passes only when **every applicable Tier A criterion scores 5 and every applicable Tier B criterion scores ≥ 4**. If anything falls short, return the document to the translator with specific notes and re-run the translate → evaluate loop until it passes, escalating to a human after the rubric's iteration cap.
+
+## DOs and DON'Ts
+
+- **Do** perform localization only for the target locales defined in the `rules` directory (one `<locale>.md` per supported locale). Do not localize into unsupported locales.
+- **Do** preserve Markdown structure, code, external link/URL targets, and frontmatter keys exactly (see *Markdown and formatting preservation*).
+- **Do** let heading anchors follow the localized heading text, and update same-document anchor links to match the new slugs so they keep resolving (see *Markdown and formatting preservation*).
+- **Do** point image and asset paths at the original assets (rewriting the relative path as needed so it resolves from `docs/src/content/docs/<locale>/`), unless a corresponding localized asset exists (see *Markdown and formatting preservation*).
+- **Do** mirror the source directory layout under `docs/src/content/docs/<locale>/`.
+- **Don't** treat configured locale-root directories as source input.
+- **Don't** reorder or restructure content; keep headings and their order stable.
+- **Don't** translate code, commands, or identifiers; translate explanatory prose and code comments only.
+
Original file line number	Diff line number	Diff line change
Expand Up		@@ -20,4 +20,4 @@ This is a docs wrapper. Don't add interactive framework islands (Svelte, React,

		## Building and verifying

		After changing `astro.config.mjs` or anything under `docs/src/`, build and verify the site with the [`build-and-verify-docs`](../skills/build-and-verify-docs/SKILL.md) skill. Its page-count invariant is the tripwire for unexpected routed pages: if the build emits more pages than `36 routable Markdown pages + 1 legacy redirect` without a matching content change, check the underscore-directory exclude in `src/content.config.ts`.
		After changing `astro.config.mjs` or anything under `docs/src/`, build and verify the site with the [`build-and-verify-docs`](../skills/build-and-verify-docs/SKILL.md) skill. Its page-count invariant is the tripwire for unexpected routed pages: Starlight emits each of the 36 workshop routes for the root language and five configured locales, then adds the legacy redirect, for 217 built `index.html` pages excluding the 404 page. If the count changes without a corresponding route or locale change, check the locale layout and the underscore-directory exclude in `src/content.config.ts`.