Skip to content

feat: showcase i18n with structured JSON + build-time MDX generation#88

Open
xuewenjie123 wants to merge 3 commits intoQwenLM:mainfrom
xuewenjie123:feat/showcase-i18n-json
Open

feat: showcase i18n with structured JSON + build-time MDX generation#88
xuewenjie123 wants to merge 3 commits intoQwenLM:mainfrom
xuewenjie123:feat/showcase-i18n-json

Conversation

@xuewenjie123
Copy link
Copy Markdown

feat: Showcase i18n with structured JSON + build-time MDX generation

This PR implements a complete i18n solution for showcase pages, supporting all 7 languages (zh, en, de, fr, ja, pt-BR, ru). It adopts a structured JSON + build-time generation approach for maximum maintainability.


Changes

🏗️ Architecture: Structured JSON Data Source

  • Structured JSON format: Replaced raw body string with structured fields (overview, steps, callouts), making showcase content easy to configure without writing MDX markup
  • Build-time MDX generation: generate-showcase-mdx.js reads structured JSON and generates MDX files for all 7 locales, with auto-generated section headers, meta components, media blocks, and CTA
  • zh.json as source of truth: All showcases must be defined in zh.json; missing translations in other languages automatically fall back to Chinese

📝 Data Generation

  • Added author and date fields to showcase data
  • Updated generate-showcase-data.js with date-based primary sorting (newest first)
  • Showcase index page now displays items in reverse chronological order

🌐 i18n Support for Components

  • ShowcaseDetailCta: Now uses locale-aware links and translated texts for all 7 supported languages
  • ShowcaseDetailMeta: Supports author prop display
  • All showcase components (video-showcase-index, video-showcase-detail, showcase-detail, showcase-cards): Dynamic locale detection via useLocale() hook, replacing hardcoded /zh/ paths

🔧 Scripts

Script Purpose
generate-showcase-mdx.js JSON → MDX generation for all locales (runs at build time)
generate-showcase-data.js Updated with author/date fields and reverse date sorting
extract-showcase-data.js MDX → JSON extraction utility (for migration)
restructure-showcase-json.js body → structured fields migration (one-time use)

📖 Documentation

  • Added SHOWCASE_I18N_GUIDE.md with complete guide for adding/translating showcases

Files Changed

  • ~292 files across all 7 supported locales
  • 7 JSON data files: showcase-i18n/{zh,en,de,fr,ja,pt-BR,ru}.json
  • 234 generated MDX files: content/{lang}/showcase/*.mdx (39 showcases × 6 non-zh locales)
  • 39 updated MDX files: content/zh/showcase/*.mdx
  • 5 component files: showcase-detail-meta, video-showcase-index, video-showcase-detail, showcase-detail, showcase-cards
  • 4 script files: generate-showcase-mdx, generate-showcase-data, extract-showcase-data, restructure-showcase-json
  • 1 doc file: SHOWCASE_I18N_GUIDE.md
  • 1 config file: package.json (build scripts)

How to Add a New Showcase

// showcase-i18n/zh.json
{
  "my-new-showcase": {
    "title": "案例标题",
    "description": "一句话描述",
    "category": "编程开发",
    "features": ["Agent 模式"],
    "thumbnail": "https://...",
    "videoUrl": "https://...",
    "model": "qwen3.5-plus",
    "author": "Qwen Code Team",
    "date": "2025-07-01",
    "overview": "概述文本,支持 Markdown",
    "steps": [
      { "title": "步骤标题", "content": "步骤内容" }
    ],
    "callouts": [
      { "type": "info", "content": "提示信息" }
    ]
  }
}

Then run node scripts/generate-showcase-mdx.js to generate MDX files.

See SHOWCASE_I18N_GUIDE.md for full documentation.


Testing

  • TypeScript compilation passes (0 errors)
  • All 39 showcases × 7 languages generate correctly
  • Structured JSON → MDX rendering matches original content
  • Section headers auto-translated per locale
  • Fallback to zh works for missing translations
image

xwj02155382 added 3 commits April 2, 2026 17:12
- Implement JSON-driven i18n for showcase pages (7 languages)
- Structured JSON format: overview, steps, callouts (replaces raw body)
- Build-time MDX generation from structured JSON data
- Add author and date fields with date-based sorting (newest first)
- i18n support for ShowcaseDetailCta and all showcase components
- Dynamic locale detection via useLocale() hook in all components
- Add SHOWCASE_I18N_GUIDE.md documentation

Scripts:
- generate-showcase-mdx.js: JSON → MDX generation for all locales
- generate-showcase-data.js: updated with author/date and reverse sorting
- extract-showcase-data.js: MDX → JSON extraction utility
- restructure-showcase-json.js: body → structured fields migration

Components updated:
- showcase-detail-meta.tsx: i18n CTA texts, author prop
- video-showcase-index.tsx: dynamic locale links
- video-showcase-detail.tsx: dynamic locale links
- showcase-detail.tsx: dynamic locale links
- showcase-cards.tsx: dynamic locale links

296 files changed across all 7 supported locales.
- Convert step content from raw Markdown string to typed blocks array
  (text, code, image, callout) for better maintainability
- Add watch-showcase.js: watches showcase-i18n/*.json and auto-regenerates
  MDX files on change, works alongside npm run dev
- Backward compatible: supports both blocks (new) and content (legacy)
- Clean up noise data from content-to-blocks migration
- Update SHOWCASE_I18N_GUIDE.md with blocks format docs and watch usage

Scripts added:
- restructure-steps-to-blocks.js: one-time migration from content to blocks
- watch-showcase.js: file watcher for dev workflow

New npm script: watch-showcase
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