Skip to content

docs(l10n): add ko-kr, ja-jp, zh-cn, es-es, pt-br translations of the full course#121

Open
justinyoo wants to merge 8 commits into
github:mainfrom
justinyoo:feat/l10n
Open

docs(l10n): add ko-kr, ja-jp, zh-cn, es-es, pt-br translations of the full course#121
justinyoo wants to merge 8 commits into
github:mainfrom
justinyoo:feat/l10n

Conversation

@justinyoo
Copy link
Copy Markdown

Summary

Adds full localization of the course documentation into 5 languages under localization/<locale>/, mirroring the original directory structure. Each translated chapter, README, and appendix is a standalone document; images continue to point at the originals in the repo-root images/ folder. A new 🌐 Use Your Preferred Language section and matching TOC entry land in the root README.md so readers can switch languages from the landing page.

Locales

  • ko-kr — 한국어
  • ja-jp — 日本語
  • zh-cn — 中文(简体)
  • es-es — Español
  • pt-br — Português (Brasil)

Each locale ships 13 documents (root README + chapters 00–07 + appendices), for 65 translated files in total.

What's localized

  • Root README (course intro, prerequisites, family overview, course structure, quick reference, language switcher)
  • Chapters 00-quick-start through 07-putting-it-together
  • appendices/README.md, appendices/additional-context.md, appendices/ci-cd-integration.md

What's intentionally NOT localized

  • Top-level project files: AGENTS.md, CODE_OF_CONDUCT.md, CONTRIBUTING.md, GLOSSARY.md, SECURITY.md, SUPPORT.md
  • samples/** (code samples and supporting files)
  • .github/** (templates, workflows)

Quality work performed

After the initial machine-assisted translation pass, the following corrections were applied across every locale to ensure rendered output is faithful and links resolve:

  1. Image paths — chapter-local images now resolve correctly via ../../../<chapter>/images/..., repo-root shared images via ../../../images/... from chapters and ../../images/... from each locale's root README.
  2. Repo-root references — links to GLOSSARY.md, LICENSE, etc. updated to ../../../GLOSSARY.md style from chapter files.
  3. Markdown emphasis + link order**[text](url)** rewritten to [**text**](url) so GitHub renders the bold inside the link (≈115 fixes).
  4. Internal anchor localization — every [text](#anchor) and cross-file [text](path#anchor) link in localized files now points at the localized heading slug, computed with a faithful github-slugger implementation (lowercase, drop emoji/punctuation, whitespace → hyphens, preserve the leading hyphen produced by a leading emoji + space).
  5. {#id} cleanup — the ja-jp draft used Pandoc-style explicit heading IDs that GitHub does not honor; these were stripped and the dependent anchors re-canonicalized.
  6. TOC additions — the new 🌐 Use Your Preferred Language section is mirrored in every locale, and the top-of-page TOC strip includes a localized 🌐 [Your Language] entry pointing to that locale's section.

Verification

  • A path verifier (MD_LINK + HTML_SRC + HTML_HREF regex resolution) reports 0 missing files and 0 broken relative paths across all 5 locales.
  • The anchor fixer is idempotent — re-running it after the merge of any locale produces 0 additional changes.
  • Spot-checked rendered TOC output in each locale; e.g. ko-kr root README now reads:

    🎯 학습 목표사전 요건 🤖 Copilot 제품군 📚 강의 구성 📋 명령어 참조 🌐 내 언어

Notes for reviewers

  • Translations preserve heading structure and document order so future edits to the English source can be diffed positionally.
  • Any future English content additions should follow the same pattern: add to the original first, then mirror into each localization/<locale>/... file at the same heading position.
  • Cross-locale anchors (e.g. links from ko-kr/02-context-conversations to ko-kr/appendices/additional-context.md#…) are remapped to the target locale's heading slug, not the English slug.

justinyoo and others added 8 commits May 13, 2026 17:06
Adds full Japanese localization for the GitHub Copilot CLI for Beginners
course under localization/ja-jp/.

Files translated (13 total):
- localization/ja-jp/README.md — course index
- localization/ja-jp/00-quick-start/README.md
- localization/ja-jp/01-setup-and-first-steps/README.md
- localization/ja-jp/02-context-conversations/README.md
- localization/ja-jp/03-development-workflows/README.md
- localization/ja-jp/04-agents-custom-instructions/README.md
- localization/ja-jp/05-skills/README.md
- localization/ja-jp/06-mcp-servers/README.md
- localization/ja-jp/06-mcp-servers/mcp-custom-server.md
- localization/ja-jp/07-putting-it-together/README.md
- localization/ja-jp/appendices/README.md
- localization/ja-jp/appendices/additional-context.md
- localization/ja-jp/appendices/ci-cd-integration.md

Translation conventions:
- Polite form (です・ます調) throughout
- Brand names, code blocks, file paths, and identifiers preserved as-is
- Relative paths adjusted for localization/ja-jp/ depth (../../.. prefix)
- Sibling chapter links kept as localized references

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Re-map [text](#anchor) and cross-file [text](path#anchor) targets so they
point to the localized heading slugs rather than the original English
slugs. Preserves leading-hyphen status from the original anchor and
mirrors github-slugger semantics for translated heading text.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Headings that begin with emoji + space produce a slug with a leading
hyphen on GitHub (e.g. ## 🎯 Learning Objectives -> #-learning-objectives).
The original anchors in the source markdown are inconsistent about this
(some include the leading hyphen, some don't), so the localized files
now use the canonical, github-slugger-faithful slug for the localized
heading text regardless of how the source anchor was written.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…icalize

GFM does not honor Pandoc-style explicit heading IDs; the ja-jp
translator agent had appended them to 9 headings, where they rendered as
literal text and polluted the auto-generated slug. Strip the
annotations and re-canonicalize incoming anchors that referenced the
old polluted slug.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…ocale READMEs

Mirror the new section added to the root README. Each locale's link
list highlights the current language with ./README.md and points to the
others via ../<locale>/README.md (English uses ../../README.md).

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Mirror the new TOC entry added to the root README. Each locale uses a
short translation of 'Your Language' and points to the locale's own
'Use Your Preferred Language' heading slug.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot AI review requested due to automatic review settings May 13, 2026 12:53
Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot wasn't able to review this pull request because it exceeds the maximum number of lines (20,000). Try reducing the number of changed lines and requesting a review from Copilot again.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants