Skip to content

Commit fa21868

Browse files
quantizorquantizor
authored
feat: add chinese & hindi translations (#771)
* feat: add i18n infrastructure with Chinese language support - Add languages.ts registry for supported languages (en, zh) - Add ui-strings.ts with multilingual UI labels and messages - Create English baseline documentation in src/i18n/en/ - Add i18n validation script to ensure translation completeness - Add Chinese i18n rules for translation guidelines * docs: add Simplified Chinese documentation translations Complete Mandarin translations for all documentation: - README.md with full API documentation and examples - GFM spec (GitHub Flavored Markdown specification) - CommonMark spec (Markdown specification) - Interactive demo template All natural language content translated to Simplified Chinese (普通话) with technical terms including English equivalents on first use. * docs: add Simplified Chinese JSDoc documentation to public APIs Add @lang zh JSDoc tags with Simplified Chinese translations to all exported: - Functions (parser, compilers, utilities) - Types and interfaces (Options, RenderOptions, AST nodes) - React, HTML, Markdown, Native, Solid, and Vue components Improves developer experience for Chinese-speaking developers with bilingual inline documentation visible in IDEs and editors. * feat: add Hindi language support for internationalization Add Modern Standard Hindi (हिन्दी) as third supported language: - Complete translations of all documentation (README, specs, template) - Hindi UI strings for interactive components - Hindi i18n translation guidelines - Update language registry and UI strings to include Hindi Follows global speaker rankings (Ethnologue 2025) for language prioritization. Improves accessibility for Hindi-speaking developers worldwide. * docs: add Hindi JSDoc documentation to public APIs Add @lang hi JSDoc tags with Modern Standard Hindi translations to all exported: - Core parser and compiler functions - Type definitions and interfaces - All renderer adapters (React, HTML, Markdown, Native, Solid, Vue) Completes trilingual documentation (English, Chinese, Hindi) for all public APIs, making the library more accessible to developers globally. * feat: add language selector to interactive demo Add multilingual support to the demo site: - Language dropdown in navigation for English, Chinese, Hindi - Dynamic content loading based on selected language - Internationalized UI strings for all controls and labels - Responsive design with language-specific typography Users can now view documentation and try the parser in their preferred language, improving accessibility and user experience. * chore: rebuild site with i18n support * docs: update repository documentation for i18n support - Update AGENTS.md with i18n workflow and translation guidelines - Add i18n contribution guidelines to CONTRIBUTING.md - Update README.md with language support information - Add i18n command documentation for cursor workflow - Add parse.spec.ts test for i18n validation * test: fix inline snapshot formatting for HTML block test
1 parent 4068d42 commit fa21868

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

61 files changed

+57932
-2778
lines changed

‎.changeset/goofy-walls-repair.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
'markdown-to-jsx': patch
3+
---
4+
5+
Add Chinese (Mandarin) JSDoc documentation to all public APIs. All exported functions, types, interfaces, and components now include bilingual documentation using the `@lang zh` tag for Simplified Chinese translations, improving developer experience for Chinese-speaking users.

‎.changeset/hindi-i18n-support.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
'markdown-to-jsx': patch
3+
---
4+
5+
Add Hindi (हिन्दी) language support for internationalization. Includes full translations of documentation (README, markdown spec, GFM spec, interactive demo template), UI strings, and JSDoc translations for all public APIs using the `@lang hi` tag. Hindi is now the third supported language after English and Mandarin Chinese, following global speaker rankings (Ethnologue 2025).

‎.cursor/commands/i18n.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
User to provider:
2+
3+
1. Target Language (e.g. Mandarin)(user provides)
4+
2. Target Language Abbreviation (e.g. cn)(system provides)
5+
6+
I want to make a {1} version of the docs. Make -{2} versions of each thing, appropriate meta tags, and add with the other languages in all the places. In AGENTS.md we need to add instructions that for now on any new changesets, public documentation, and public JSDOC comments should include a minimal {1} translation below the English. Any time those files are updated in English, we need to do the corresponding update in the {1} version.
7+
8+
Perform research to identify the most well-known dialect of {1}, preferred formality and tone, and utilize it for the translation. Lastly, I'd like you to look at some popular {1}-language open source developer sites and see if they do anything unique that is not common in the American tech scene. For instance, a particular style of writing or didactic style.
9+
10+
Work on each file individually as its own TODO.

‎.cursor/rules/i18n-hi.mdc‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
---
2+
globs: src/i18n/hi/**
3+
alwaysApply: false
4+
---
5+
6+
Modern Standard Hindi (मानक हिन्दी) for technical documentation
7+
Formal register using आप pronoun throughout
8+
JSDoc multilingual format: English baseline, then @lang hi lines
9+
Technical terms: include English in parentheses on first use: पार्सर (Parser), कंपाइलर (Compiler), एब्स्ट्रैक्ट सिंटैक्स ट्री (AST)
10+
No parentheses for established terms in subsequent uses
11+
12+
Term translations:
13+
Parser=पार्सर, Compiler=कंपाइलर, AST=एब्स्ट्रैक्ट सिंटैक्स ट्री, Options=विकल्प, Returns=रिटर्न करता है/रिटर्न, Param=पैरामीटर, Override=ओवरराइड, Sanitize=सैनिटाइज़/साफ करें, Sanitizer=सैनिटाइज़र फ़ंक्शन, Slugify=स्लगिफ़ाई/URL-सुरक्षित बनाएं, Entry Point=एंट्री पॉइंट, Wrapper=रैपर, Props=props, Component=कंपोनेंट, Node=नोड, Block=ब्लॉक, Inline=इनलाइन, Link=लिंक, Image=छवि/इमेज, Header/Heading=शीर्षक/हेडिंग, List=सूची/लिस्ट, Table=टेबल/तालिका, Code Block=कोड ब्लॉक, Quote=उद्धरण/कोट, Paragraph=पैराग्राफ़, Text=टेक्स्ट, Attribute=एट्रिब्यूट, Tag=टैग, Element=एलिमेंट, String=स्ट्रिंग, Function=फ़ंक्शन, Boolean=बूलियन, Array=ऐरे, Object=ऑब्जेक्ट, Deprecated=अप्रचलित, Breaking Changes=ब्रेकिंग परिवर्तन, Migration=माइग्रेशन, Install=इंस्टॉल, Installation=इंस्टॉलेशन, Usage=उपयोग, Example=उदाहरण, Note=नोट, Warning=चेतावनी, Tip=सुझाव/टिप, Important=महत्वपूर्ण, Caution=सावधानी/सतर्कता, Alert=अलर्ट/सूचना, Reference=संदर्भ/रेफ़रेंस, Definition=परिभाषा, Frontmatter=फ्रंटमैटर/प्रारंभिक मेटाडेटा, Footnote=फ़ुटनोट/पाद टिप्पणी, Rendering=रेंडरिंग, Parsing=पार्सिंग, Output=आउटपुट, Input=इनपुट, Rule=नियम/रूल, Type=प्रकार/टाइप, Spec/Specification=विनिर्देश/स्पेक, Syntax=सिंटैक्स, Content=कंटेंट/सामग्री, Value=मान/वैल्यू, Expression=एक्सप्रेशन, Security=सुरक्षा, XSS=XSS, Safe=सुरक्षित, Unsafe=असुरक्षित, Filter=फ़िल्टर, Escape=एस्केप, Entity=एंटिटी, Character=वर्ण/कैरेक्टर, Unicode=यूनिकोड, Regex=रेगेक्स/रेगुलर एक्सप्रेशन, Match=मैच, Pattern=पैटर्न, Build=बिल्ड, Test=टेस्ट, Server=सर्वर, Client=क्लाइंट, Native=नेटिव, Upgrade/Upgrading=अपग्रेड/अपग्रेडिंग, Feature=सुविधा, Table of Contents=विषय-सूची, Donate=दान करें, Changelog=परिवर्तन लॉग, Library=लाइब्रेरी
14+
15+
Alert types: NOTE=नोट, TIP=सुझाव/टिप, IMPORTANT=महत्वपूर्ण, WARNING=चेतावनी, CAUTION=सावधानी
16+
17+
Section headers: dual-language format with Hindi first: "इंस्टॉलेशन (Installation)", "उपयोग (Usage)" - but prefer Hindi-only for common terms
18+
UI strings localized per src/i18n/ui-strings.ts conventions
19+
Formal written style, active voice preferred
20+
@param and @returns in JSDoc use Hindi descriptions, English for types
21+
Maintain parallel structure with English version
22+
Keep technical accuracy, avoid over-localization of domain-specific terms
23+
Table of contents links: preserve URL encoding with Hindi text
24+
Devanagari numerals not used, use Western Arabic numerals (0-9)
25+
Use nuqta (़) for phonetic accuracy in loanwords: फ़ंक्शन, रेफ़रेंस, ग्राफ़
26+
Compound terms: prefer spacing for clarity (कोड ब्लॉक not कोडब्लॉक)
27+
Breaking changes translation: "ब्रेकिंग परिवर्तन" with context
28+
Version numbers, file paths, URLs remain in English/original form

‎.cursor/rules/i18n-zh.mdc‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
---
2+
globs: src/i18n/zh/**
3+
alwaysApply: false
4+
---
5+
6+
Simplified Chinese (普通话) for technical documentation
7+
JSDoc multilingual format: English baseline, then @lang zh lines
8+
Technical terms: include English in parentheses on first use: 解析器 (Parser), 编译器 (Compiler), 抽象语法树 (AST)
9+
No parentheses for established terms in subsequent uses
10+
11+
Term translations:
12+
Parser=解析器, Compiler=编译器, AST=抽象语法树, Options=选项, Returns=返回, Param=参数, Override=覆盖, Sanitize=清理, Sanitizer=清理函数, Slugify=转换为别名, Entry Point=入口点, Wrapper=包装器, Props=属性, Component=组件, Node=节点, Block=块, Inline=内联, Link=链接, Image=图像, Header/Heading=标题, List=列表, Table=表格, Code Block=代码块, Quote=引用, Paragraph=段落, Text=文本, Attribute=属性, Tag=标签, Element=元素, String=字符串, Function=函数, Boolean=布尔值, Array=数组, Object=对象, Deprecated=已弃用, Breaking Changes=破坏性变更, Migration=迁移, Install=安装, Usage=用法, Example=示例, Note=注意, Warning=警告, Tip=提示, Important=重要, Caution=小心, Alert=警报/提示, Reference=引用, Definition=定义, Frontmatter=前置元数据, Footnote=脚注, Rendering=渲染, Parsing=解析, Output=输出, Input=输入, Rule=规则, Type=类型, Spec=规范, Syntax=语法, Content=内容, Value=值, Expression=表达式, Security=安全, XSS=XSS, Safe=安全, Unsafe=不安全, Filter=过滤, Escape=转义, Entity=实体, Character=字符, Unicode=Unicode, Regex=正则表达式, Match=匹配, Pattern=模式
13+
14+
Alert types: NOTE=注意, TIP=提示, IMPORTANT=重要, WARNING=警告, CAUTION=小心
15+
16+
Section headers: dual-language format with English in parentheses: "安装 (Installation)", "用法 (Usage)"
17+
UI strings localized per src/i18n/ui-strings.ts conventions
18+
Formal written style, active voice
19+
@param and @returns in JSDoc use Chinese for descriptions, English for types
20+
Maintain parallel structure with English version
21+
Keep technical accuracy, avoid over-localization of domain-specific terms
22+
Table of contents links: preserve URL encoding with Chinese text

‎AGENTS.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -47,3 +47,23 @@ The priorities of this library are bundle size, performance, and functionality i
4747

4848
- `src/index.tsx` - Main entry point re-exporting parser, types, and utilities
4949
- `src/index.cjs.tsx` - CommonJS entry point with deprecated exports
50+
51+
## Internationalization (i18n)
52+
53+
- All localized content in `src/i18n/`.
54+
- Required files per language: `README.md`, `default-template.md`, `gfm-spec.md`, `markdown-spec.md`.
55+
- UI strings in `src/i18n/ui-strings.ts`.
56+
- Supported languages in `src/i18n/languages.ts`.
57+
- Language ordering by global speakers ([Ethnologue 2025](https://www.ethnologue.com/insights/most-spoken-language/)): English, Mandarin Chinese, Hindi, Spanish, Arabic.
58+
- Technical documentation standards: Simplified Chinese (Mandarin, 普通话), Modern Standard Hindi (मानक हिन्दी with formal आप pronoun).
59+
- Code examples: Keep API names, package names, technical constants in English. Translate text content within code blocks (string literals, user-facing text, natural language comments, example markdown text) while preserving syntax and markup.
60+
- Use `@lang <code>` JSDoc tags for multilingual documentation (Public APIs and types only): English baseline, then `@lang zh` for Chinese, `@lang hi` for Hindi, etc.
61+
- Updates to `README.md` or public API documentation must be mirrored in all `src/i18n/{lang}/` files.
62+
- All new changesets, public documentation, and public JSDoc comments should include translations for all supported languages (currently: English, Chinese, Hindi).
63+
- Run `bun run validate-i18n` before committing any i18n or documentation changes.
64+
- New languages should have a PATCH changeset.
65+
- Create language-specific rule files in `.cursor/rules/i18n-{lang}.mdc` for each new language containing: term translations, style guidelines, technical term handling, format conventions. Optimize for machine interpretation (no markdown formatting, minimal punctuation, concise directives).
66+
- Prefer native/idiomatic words over transliterations for user-facing text (UI strings, alerts, documentation headings).
67+
- For technical terms, provide both options: native word first, transliteration second (e.g., Hindi: सुझाव/टिप for "tip").
68+
- Transliterations acceptable for programming-specific terms with no native equivalent (e.g., कंपोनेंट for "component").
69+
- Verify translations match actual usage in target language technical communities (React docs, MDN, official framework translations).

‎CONTRIBUTING.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -62,6 +62,18 @@ Add the new target to both `scripts/metrics.ts` and `scripts/profile.ts` so it c
6262
- Bring in testing helpers like `@testing-library/*` if needed
6363
- Test all happy and unhappy paths
6464

65+
## Adding a New Language
66+
67+
Using Cursor or equivalent, run `/i18n <language>` in plan mode (e.g., `/i18n Spanish`). This automates the entire translation workflow including research, file creation, and validation. Review and approve the plan before execution.
68+
69+
**Language Ordering:** Languages must be ordered by total number of speakers globally (English first, then by descending speaker count). According to Ethnologue 2025 data ([source](https://www.ethnologue.com/insights/most-spoken-language/)):
70+
71+
1. English (1.5B speakers)
72+
2. Mandarin Chinese (1.2B speakers)
73+
3. Hindi (609M speakers)
74+
4. Spanish (558M speakers)
75+
5. Standard Arabic (335M speakers)
76+
6577
## Cutting a release
6678

6779
This is handled automatically via changesets.

‎README.md‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,7 @@ Some special features of the library:
2525
- [Entry Points](#entry-points)
2626
- [Main](#main)
2727
- [React](#react)
28-
- [React Server Components (RSC)](#react-server-components-rsc)
28+
- [React Server Components RSC](#react-server-components-rsc)
2929
- [React Native](#react-native)
3030
- [SolidJS](#solidjs)
3131
- [Vue.js](#vuejs)
@@ -188,7 +188,7 @@ render(<Markdown># Hello world!</Markdown>, document.body)
188188

189189
#### Main
190190

191-
The legacy\*default entry point exports everything, including the React compiler and component:
191+
The legacy default entry point exports everything, including the React compiler and component:
192192

193193
```tsx
194194
import Markdown, { compiler, parser } from 'markdown-to-jsx'
@@ -243,6 +243,7 @@ export function ClientMarkdown({ content }: { content: string }) {
243243
```
244244

245245
**Notes:**
246+
246247
- `MarkdownProvider` and `MarkdownContext` are client-only and become no-ops in RSC environments
247248
- RSC rendering provides better performance by avoiding client-side hydration
248249
- The component maintains identical output in both environments
@@ -380,7 +381,7 @@ const vnode2 = astToJSX(ast)
380381
- **Vue 3 support**: Uses Vue 3's `h()` render function API
381382
- **JSX support**: Works with Vue 3 JSX via `@vue/babel-plugin-jsx` or `@vitejs/plugin-vue-jsx`
382383
- **HTML attributes**: Uses standard HTML attributes (`class` instead of `className`)
383-
- **Component overrides**: Support for both Options API and Composition API componen
384+
- **Component overrides**: Support for both Options API and Composition API components
384385

385386
#### HTML
386387

0 commit comments

Comments
 (0)