Skip to content

feat: Add Traditional Chinese (zh-TW) i18n support#1

Open
sd0xdev wants to merge 1 commit intodelbaoliveira:mainfrom
sd0xdev:feat/i18n-zh-tw
Open

feat: Add Traditional Chinese (zh-TW) i18n support#1
sd0xdev wants to merge 1 commit intodelbaoliveira:mainfrom
sd0xdev:feat/i18n-zh-tw

Conversation

@sd0xdev
Copy link

@sd0xdev sd0xdev commented Feb 4, 2026

Summary

Adds full internationalization (i18n) infrastructure and Traditional Chinese (zh-TW) translation for the entire project — game UI, course lessons, and documentation.

  • i18n engine: New strings.js with detectLocale(), t() dual-signature helper, T.* template functions, and localizeHTML() — locale detected via ?lang=zh-TW URL parameter
  • Game fully localized: All room descriptions, item names, enemy names, NPC dialogues, UI buttons, status text, and combat messages translated to zh-TW with inline _zh suffix fields in data JSON files
  • 11 course lessons translated: Complete zh-TW lesson files in learn-claude/zh-TW/, with lesson metadata (title_zh, file_zh) in lessons.json
  • Course locale support: /course lang zh-TW command to switch course language, stored in course-progress.json
  • Translation quality: Reviewed with adversarial brainstorming (Claude + Codex) for Taiwan-native conventions — oral tone for game UI, English retained for gaming terms (HP, Session), consistent naming style for items, monster language kept in original English
  • CJK typography: Dedicated font stack (Noto Sans TC, PingFang TC, Microsoft JhengHei) with adjusted font sizes (14px base vs 10px pixel font) and antialiasing for Chrome/Safari
  • Server bug fix: req.url with query string (e.g. /?lang=zh-TW) caused 404 — fixed by stripping query params before file path resolution (affects dungeon/, reference/complete/, reference/starter/)
  • Test suite: 86 tests (82 i18n + 4 server) covering t() behavior, T.* templates, data file integrity (_zh fields), S string completeness, dirNames, and server query string routing
  • Unified scripts: pnpm start runs complete game (both languages), pnpm run dev runs student workspace
CleanShot 2026-02-04 at 21 59 20@2x CleanShot 2026-02-04 at 21 59 48@2x

Files Changed

New Files

File Description
reference/complete/strings.js i18n engine — locale detection, translation helpers, string maps, template functions
learn-claude/zh-TW/*.md (11 files) Traditional Chinese translations of all course lessons
README.zh-TW.md Traditional Chinese README
tests/i18n.test.js i18n unit tests (82 tests)
tests/server.test.js Server routing tests (4 tests)
vitest.config.js Test configuration
package.json Project scripts and dependencies

Modified Files

File Changes
reference/complete/game.js Use t() / T.* for all user-facing strings; take()/talk() match zh-TW names
reference/complete/ui/ui.js Localized UI updates, encounter stats, item icons
reference/complete/style.css CJK font stack, adjusted sizes for zh-TW readability
reference/complete/index.html Include strings.js
reference/complete/data/*.json Added _zh fields and icon fields to all data files
reference/complete/server.js Strip query string from URL path; zh-TW log message
reference/starter/server.js Strip query string from URL path
dungeon/server.js Strip query string from URL path; zh-TW log message
.claude/skills/course/SKILL.md Added `lang en
.claude/skills/course/lessons.json Added title_zh, file_zh, name_zh fields
CLAUDE.md Added i18n section documenting architecture and conventions
README.md Added pnpm start/pnpm run dev scripts, language commands

i18n Architecture

URL ?lang=zh-TW
       │
       ▼
  detectLocale()  →  locale = "zh-TW"
       │
       ├──▶ t(S.welcome)         →  "歡迎來到 Dungeons & Agents!"
       ├──▶ t(room, "name")      →  room.name_zh
       ├──▶ T.youGo("up")        →  "你往上走。"
       └──▶ T.localizeExits(...) →  "上、下"

Test Plan

  • pnpm test — 86 tests pass
  • Open http://localhost:3000 — English UI renders correctly
  • Open http://localhost:3000?lang=zh-TW — Chinese UI renders with correct fonts/sizes
  • Run /course lang zh-TW then /course — dashboard shows Chinese lesson titles
  • In zh-TW: take, talk, attack commands work with Chinese item/NPC names
  • Server starts with both EN and zh-TW URLs in console log

- Establishes internationalization (i18n) support for English and Traditional Chinese (zh-TW)
- Adds i18n foundation: strings.js with locale detection, translation helper, and template functions
- Refactors UI/data flow to consume translated strings and localized content
- Extends data models with zh-TW fields and updates core data (rooms/items/enemies/characters) with zh translations
- Enables locale selection via URL query (?lang=zh-TW) and persists locale in progress data
- Updates server/index flow to surface zh-TW option and logs
- Introduces new zh-TW course content and accompanying lessons
- Adds tests for i18n (detectLocale, t(), templates) and data integrity; includes server routing tests
- Adds necessary dependencies and config (Anthropic SDK, dotenv, Vitest) and associated config/scripts
- Improves READMEs and UI styling to support Chinese locale
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.

1 participant