Skip to content

docs: add Arabic (العربية) README translation#458

Merged
lefarcen merged 4 commits intomainfrom
docs/arabic-readme
May 5, 2026
Merged

docs: add Arabic (العربية) README translation#458
lefarcen merged 4 commits intomainfrom
docs/arabic-readme

Conversation

@qiongyu1999
Copy link
Copy Markdown
Contributor

Summary

  • Adds README.ar.md — full Arabic translation of README.md (740 lines, wrapped in a top-level <div dir=\"rtl\"> so GitHub renders it RTL correctly).
  • Wires up the language switcher in all nine sibling READMEs (en / de / fr / zh-CN / zh-TW / ko / ja-JP / ru / uk) — the previously-placeholder العربية entry now links to README.ar.md.

Translation approach

  • All URLs, file paths, code blocks, shields.io badges, table structures, and HTML embeds preserved verbatim.
  • Prose and table cell text translated to Modern Standard Arabic (فصحى).
  • Technical terms widely used in English by Arabic-speaking devs (daemon, sidecar, artifact, skill, prompt, BYOK, SSE, SSRF, model/CLI names, etc.) are kept in English with Arabic context — same convention used by most Arabic technical documentation.
  • Anchor IDs in the badge links updated to Arabic-friendly section ids (#الوكلاء-المدعومون, #أنظمة-التصميم, #الـ-skills).

Status

This is an initial pass. I'm not a native Arabic speaker — phrasing and terminology review from native readers is very welcome before merge or as a follow-up. The structural plumbing (RTL wrapper, language switcher links, asset preservation) should be solid regardless.

Test plan

  • Open README.ar.md on GitHub and confirm RTL rendering across paragraphs, tables, headings, and image grids.
  • Click العربية from each of the other nine README files — should land on README.ar.md.
  • Confirm all images, badges, MP4 video links, and internal anchors still resolve.
  • Native-Arabic-speaker review of phrasing/terminology (post-merge OK).

Adds README.ar.md — full Arabic translation of README.md, wrapped in a
top-level <div dir="rtl"> for correct RTL rendering on GitHub. All
URLs, file paths, code blocks, badges, and tables are preserved verbatim;
prose and table cell text are translated to Modern Standard Arabic.

Also wires up the language switcher in all nine sibling README files
(en/de/fr/zh-CN/zh-TW/ko/ja-JP/ru/uk) so the previously-placeholder
العربية entry now links to README.ar.md.

The translation is an initial pass — native-Arabic-speaker review for
phrasing/terminology is welcome.
@lefarcen lefarcen self-requested a review May 4, 2026 14:36
@lefarcen lefarcen added the documentation Improvements or additions to documentation label May 4, 2026
Copy link
Copy Markdown
Contributor

@lefarcen lefarcen left a comment

Choose a reason for hiding this comment

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

Hi @qiongyu1999! Thanks for taking on the Arabic translation — the structural plumbing (RTL wrapper, language switcher, section parity) is solid. I found two issues that need fixing before merge:

  1. Fenced code blocks contain translated prose — the stated translation approach was to preserve code blocks verbatim, but several blocks (prompt-stack diagram, bash examples, .od/ tree, repository tree) have Arabic prose inside the fences. These should remain exactly as in README.md.

  2. License section drops upstream attributionREADME.md explicitly mentions bundled licenses (skills/guizang-ppt/LICENSE, skills/html-ppt/LICENSE) with author links; README.ar.md replaces that with a generic pointer to LICENSE. The translation should preserve those attribution links.

Please address these two findings. Once fixed, this PR will be ready for merge.

— open-design team

Comment thread README.ar.md
Comment thread README.ar.md Outdated
Address PR #458 review feedback (P2):

1. Revert translated prose inside fenced code blocks back to verbatim
   English, matching the source README.md:
   - Prompt-stack composition block
   - Architecture ASCII diagram (browser layer, daemon comments,
     bottom CLI row)
   - Quickstart bash comments
   - .od/ tree comments
   - Repository structure tree comments

2. Restore the License section's bundled-attribution sentence with
   links to skills/guizang-ppt/LICENSE (MIT, @op7418) and
   skills/html-ppt/LICENSE (MIT, @lewislulu); the previous version
   collapsed it to a generic 'see LICENSE' pointer.
@qiongyu1999
Copy link
Copy Markdown
Contributor Author

Thanks @lefarcen for the review! Both findings addressed in fa2b973:

1. Fenced code blocks → verbatim English. Reverted translated prose inside all fences:

  • Prompt-stack composition block
  • Architecture ASCII diagram (browser layer, daemon-side comments, bottom CLI row)
  • Quickstart bash comments (should print 10.33.2, open the web URL printed by tools-dev)
  • .od/ tree comments
  • Repository structure tree comments

2. License attribution restored. Brought back the full sentence with the two bundled-license links and author handles — skills/guizang-ppt/LICENSE (MIT, @op7418) and skills/html-ppt/LICENSE (MIT, @lewislulu) — translated wrapper prose only.

Ready for another look.

Copy link
Copy Markdown
Contributor

@lefarcen lefarcen left a comment

Choose a reason for hiding this comment

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

Both P2 findings addressed successfully! 🎉

Code blocks: All fenced blocks now match README.md exactly (the repository tree includes README.ar.md with العربية (this file), which correctly mirrors the pattern in README.md where it says ← this file).

License attribution: The full bundled-license sentence is restored with both links (skills/guizang-ppt/LICENSE @op7418, skills/html-ppt/LICENSE @lewislulu).

LGTM — this PR is ready for merge from my side. Nice work on the comprehensive Arabic translation!

Copy link
Copy Markdown
Contributor

@mrcfps mrcfps left a comment

Choose a reason for hiding this comment

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

@qiongyu1999 I reviewed the Arabic README addition plus the language-switcher updates across the sibling READMEs. The previous code-fence preservation and bundled-license attribution concerns are addressed at the current head, and the remaining changes are documentation-only translation/link plumbing. Thanks for the careful follow-up — this is ready from my review. 🙂

Generated by Looper 0.5.4 · runner=reviewer · agent=opencode

@lefarcen lefarcen dismissed their stale review May 4, 2026 14:54

Both findings addressed in fa2b973

# Conflicts:
#	README.de.md
#	README.fr.md
#	README.ja-JP.md
#	README.ko.md
#	README.md
#	README.ru.md
#	README.uk.md
#	README.zh-CN.md
#	README.zh-TW.md
Copy link
Copy Markdown
Contributor

@mrcfps mrcfps left a comment

Choose a reason for hiding this comment

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

@qiongyu1999 thanks for the careful follow-up on the earlier review items. I found one remaining completeness gap in the Arabic README translation that should be fixed before merge so the new localized README stays in sync with the current English source. 🙂

Generated by Looper 0.5.4 · runner=reviewer · agent=opencode

Comment thread README.ar.md
@qiongyu1999 qiongyu1999 requested review from lefarcen and mrcfps May 5, 2026 06:01
Address PR #458 follow-up review (mrcfps): the Arabic README jumped from
the .od/ first-run section straight to repository structure, missing the
two sections added to README.md after this branch was forked:

- ## Running the Project — web/localhost mode, fixed-port restarts,
  desktop/Electron commands, and the useful-commands table
- ## Use Open Design from your coding agent — stdio MCP server setup,
  per-client install flow, daemon-must-be-running note, and the
  read-only security model

Command blocks, table structure, and links are preserved verbatim from
README.md per the same convention used elsewhere in the file.
@qiongyu1999
Copy link
Copy Markdown
Contributor Author

Thanks @mrcfps — you're right, those two sections landed in main after this branch was forked and got skipped during the merge resolution. Now translated and inserted between the .od/ first-run table and ## بنية المستودع:

  • ## تشغيل المشروع — web/localhost (default + fixed ports + restart), desktop/Electron (status + screenshot), and the useful-commands table.
  • ## استخدام Open Design من وكيل البرمجة لديك — stdio MCP server setup, per-client install flow, daemon-must-be-running note, and the read-only security model.

Command blocks and links preserved verbatim per the same pattern used elsewhere. Ready for another look.

Copy link
Copy Markdown
Contributor

@mrcfps mrcfps left a comment

Choose a reason for hiding this comment

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

@qiongyu1999 I reviewed the current Arabic README translation update, including the newly inserted Running the Project and MCP sections, the verbatim command/code blocks, license attribution, and the Arabic links added to the sibling README language switchers. The current head looks consistent with the English README for these documentation changes, and the previous completeness gap is addressed — thanks for the thoughtful follow-up. 🙂

Generated by Looper 0.5.4 · runner=reviewer · agent=opencode

@lefarcen lefarcen merged commit c2e3691 into main May 5, 2026
1 check passed
Copy link
Copy Markdown
Contributor

@lefarcen lefarcen left a comment

Choose a reason for hiding this comment

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

mrcfps's review verified the completeness gap is addressed. The current head looks good from the documentation translation perspective. ✅

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

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants