Skip to content

feat: bản dịch tiếng Việt + site VuePress thứ 2 với toggle ngôn ngữ - #2916

Closed
vandunxg wants to merge 1 commit into
Snailclimb:mainfrom
vandunxg:feat/vietnamese-translation
Closed

vandunxg wants to merge 1 commit into
Snailclimb:mainfrom
vandunxg:feat/vietnamese-translation

Conversation

@vandunxg

Copy link
Copy Markdown

Dựng bản dịch tiếng Việt của JavaGuide dưới dạng một site VuePress riêng, dùng chung theme/component/style với bản gốc nên UI giống hệt.

Kiến trúc zero-conflict với repo gốc:

  • Không sửa một byte nào trong docs/, package.json hay pnpm-lock.yaml (package.json bị upstream đụng ở 54/200 commit gần nhất -> chắc chắn conflict).
  • Toàn bộ thay đổi nằm ở file/thư mục upstream không có: vi/, i18n/, Makefile, vercel.json, CLAUDE.md.
  • Lệnh chuyển sang Makefile thay cho npm scripts.

Nội dung (12 file, giai đoạn 1 của lộ trình học):

  • 7 snippet dùng chung, README, home, roadmap/README
  • roadmap/java-roadmap.md (1002 dòng) — file trọng tâm của lộ trình

Site tiếng Việt (vi/.vuepress/):

  • base "/vi/", dest "./dist/vi", lang "vi-VN", docsDir "vi"
  • Dịch toàn bộ navbar + 11 file sidebar (289 chuỗi), SEO/JSON-LD, chuỗi UI trong component, comment trong SCSS và feature config
  • trimDescription() đổi dấu câu 。!?,、 sang . ! ? , ; — không đổi thì hàm không bao giờ tìm được điểm ngắt trong văn bản tiếng Việt
  • legacyRedirects làm rỗng (là URL tiếng Trung của site gốc, vô nghĩa dưới /vi/)
  • linksCheck tạm hạ xuống "warn" vì sidebar trỏ tới trang chưa dịch

Toggle ngôn ngữ 中文 | VI (i18n/lang-switch/):

  • Teleport vào .vp-navbar-end của theme, có mặt trên CẢ HAI site
  • Site gốc nhận nút qua wrapper config i18n/cn.config.ts, không phải sửa docs/
  • Trang chưa dịch thì nút VI mờ đi và trỏ về /vi/ thay vì tạo link gãy
  • Dev: site CN proxy /vi/* sang site VI để hai bên cùng một origin

Công cụ đồng bộ (i18n/sync-check.mjs):

  • Sau khi pull upstream, báo file chưa dịch / file gốc đã đổi / file orphan

Đã kiểm chứng:

  • Build CN 641 trang + VI 11 trang, EXIT=0, 61s, peak 2.93GB RAM
  • Toggle đúng cả 3 trường hợp (đã dịch / chưa dịch / chiều ngược lại), xác nhận bằng DOM thật qua headless Chromium
  • git diff rỗng hoàn toàn -> pull upstream không conflict

Nguồn: https://github.com/Snailclimb/JavaGuide (Apache-2.0)

Dựng bản dịch tiếng Việt của JavaGuide dưới dạng một site VuePress riêng,
dùng chung theme/component/style với bản gốc nên UI giống hệt.

Kiến trúc zero-conflict với repo gốc:
- Không sửa một byte nào trong docs/, package.json hay pnpm-lock.yaml
  (package.json bị upstream đụng ở 54/200 commit gần nhất -> chắc chắn conflict).
- Toàn bộ thay đổi nằm ở file/thư mục upstream không có: vi/, i18n/,
  Makefile, vercel.json, CLAUDE.md.
- Lệnh chuyển sang Makefile thay cho npm scripts.

Nội dung (12 file, giai đoạn 1 của lộ trình học):
- 7 snippet dùng chung, README, home, roadmap/README
- roadmap/java-roadmap.md (1002 dòng) — file trọng tâm của lộ trình

Site tiếng Việt (vi/.vuepress/):
- base "/vi/", dest "./dist/vi", lang "vi-VN", docsDir "vi"
- Dịch toàn bộ navbar + 11 file sidebar (289 chuỗi), SEO/JSON-LD,
  chuỗi UI trong component, comment trong SCSS và feature config
- trimDescription() đổi dấu câu 。!?,、 sang . ! ? , ; — không đổi thì
  hàm không bao giờ tìm được điểm ngắt trong văn bản tiếng Việt
- legacyRedirects làm rỗng (là URL tiếng Trung của site gốc, vô nghĩa dưới /vi/)
- linksCheck tạm hạ xuống "warn" vì sidebar trỏ tới trang chưa dịch

Toggle ngôn ngữ 中文 | VI (i18n/lang-switch/):
- Teleport vào .vp-navbar-end của theme, có mặt trên CẢ HAI site
- Site gốc nhận nút qua wrapper config i18n/cn.config.ts, không phải sửa docs/
- Trang chưa dịch thì nút VI mờ đi và trỏ về /vi/ thay vì tạo link gãy
- Dev: site CN proxy /vi/* sang site VI để hai bên cùng một origin

Công cụ đồng bộ (i18n/sync-check.mjs):
- Sau khi pull upstream, báo file chưa dịch / file gốc đã đổi / file orphan

Đã kiểm chứng:
- Build CN 641 trang + VI 11 trang, EXIT=0, 61s, peak 2.93GB RAM
- Toggle đúng cả 3 trường hợp (đã dịch / chưa dịch / chiều ngược lại),
  xác nhận bằng DOM thật qua headless Chromium
- git diff rỗng hoàn toàn -> pull upstream không conflict

Nguồn: https://github.com/Snailclimb/JavaGuide (Apache-2.0)

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@vandunxg vandunxg closed this Sep 18, 2026
@vandunxg
vandunxg deleted the feat/vietnamese-translation branch September 18, 2026 06:34
@vandunxg
vandunxg restored the feat/vietnamese-translation branch September 18, 2026 06:35
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