morluto/rea

Fork 0

mirror of https://github.com/morluto/rea.git synced 2026-11-05 06:45:22 +00:00

[GH-ISSUE #1022] docs: add and maintain multilingual website versions #376

New issue

Closed

opened 2026-10-15 18:24:26 +00:00 by bsakaguchi · 4 comments

bsakaguchi commented

2026-10-15 18:24:26 +00:00

Owner

Originally created by @N0zoM1z0 on GitHub (Oct 7, 2026).
Original GitHub issue: https://github.com/morluto/rea/issues/1022

The REA website currently has an English homepage, onboarding pages, guides and DX-Ball, Notion and TH04 showcases. Add multilingual versions so readers can understand the examples and get started in their preferred language, and establish a way to keep those versions current as the website changes.

Content and experience

Cover the homepage, getting started, guide and showcase indexes, worked guides, and all three case studies.
Add a simple language selector. Switching languages should open the equivalent page when available; make any English fallback clear.
Translate navigation, headings, instructions, figure labels, alternative text, captions, copy-button feedback and page metadata. Keep executable commands, API names and source excerpts accurate.
Reuse the current layout and shared components. Check longer translated text on mobile, including diagrams and code comparisons.
Preserve source attribution and the scope of each case study's findings.

Follow the website's existing editorial principle:

A good website is like a good paper: easy to follow, clear and concise, with a clean, refined presentation.

— N0zoM1z0

Translations should read naturally in each language, with direct headings and concrete examples. The website style guide remains the starting point.

Maintenance and acceptance

Choose the initial languages and a consistent URL structure.
Implement equivalent-page language switching, appropriate HTML language attributes and localized page metadata.
Translate and review the reading pages and their explanatory figures.
Document how English content changes are tracked in translations, how outdated pages are identified, and how contributors submit language updates.
Update website/README.md, website/AGENTS.md and the style guide with the multilingual workflow.
Extend website checks to cover locale links, anchors, assets and missing page mappings; verify copying, downloads, figures and mobile layouts locally.
Keep the existing single, manually triggered GitHub Pages publisher.

This issue records the work; implementation and the initial language list are still to be decided. README translation review is tracked separately in #958.

Originally created by @N0zoM1z0 on GitHub (Oct 7, 2026). Original GitHub issue: https://github.com/morluto/rea/issues/1022 The REA website currently has an English homepage, onboarding pages, guides and DX-Ball, Notion and TH04 showcases. Add multilingual versions so readers can understand the examples and get started in their preferred language, and establish a way to keep those versions current as the website changes. ## Content and experience - Cover the homepage, getting started, guide and showcase indexes, worked guides, and all three case studies. - Add a simple language selector. Switching languages should open the equivalent page when available; make any English fallback clear. - Translate navigation, headings, instructions, figure labels, alternative text, captions, copy-button feedback and page metadata. Keep executable commands, API names and source excerpts accurate. - Reuse the current layout and shared components. Check longer translated text on mobile, including diagrams and code comparisons. - Preserve source attribution and the scope of each case study's findings. Follow the website's existing editorial principle: > A good website is like a good paper: easy to follow, clear and concise, with a clean, refined presentation. > > — N0zoM1z0 Translations should read naturally in each language, with direct headings and concrete examples. The [website style guide](https://github.com/morluto/rea/blob/main/website/style-guide.md) remains the starting point. ## Maintenance and acceptance - [ ] Choose the initial languages and a consistent URL structure. - [ ] Implement equivalent-page language switching, appropriate HTML language attributes and localized page metadata. - [ ] Translate and review the reading pages and their explanatory figures. - [ ] Document how English content changes are tracked in translations, how outdated pages are identified, and how contributors submit language updates. - [ ] Update `website/README.md`, `website/AGENTS.md` and the style guide with the multilingual workflow. - [ ] Extend website checks to cover locale links, anchors, assets and missing page mappings; verify copying, downloads, figures and mobile layouts locally. - [ ] Keep the existing single, manually triggered GitHub Pages publisher. This issue records the work; implementation and the initial language list are still to be decided. README translation review is tracked separately in #958.

bsakaguchi

2026-10-15 18:24:26 +00:00

closed this issue
added the
help wanted

documentation

enhancement
labels

bsakaguchi commented

2026-10-15 18:24:27 +00:00

Author

Owner

@akram1089 commented on GitHub (Oct 7, 2026):

I'd like to work on this. Before writing any pages, here's a proposal to agree on scope and structure, since the issue leaves the languages and URL layout open.

Initial languages: Simplified Chinese (zh), Japanese (ja), Korean (ko) and Arabic (ar), matching the README translations reviewed under #958. Arabic also exercises right-to-left layout (dir="rtl") early, before the page set grows.

URL structure: keep English at the current paths and add path-prefixed mirrors, e.g. website/public/zh/get-started/index.html → /zh/get-started/. This fits the current static layout and scripts/verify-website.py's relative-reference rule. Shared assets stay in website/public/assets/; localized pages reference them relatively (../../assets/…). No build step and no change to the single manually triggered Pages publisher.

Switching and metadata:

A small language selector in the existing header nav. It links to the equivalent page through a static mapping, so it works without JavaScript.
Every page gets <html lang> (plus dir="rtl" for Arabic), <link rel="alternate" hreflang> for each available version, and a localized <title>/description.
A page without a translation falls back to English, with a visible one-line notice in the selected language.

Figures: the three SVGs in assets/figures/ contain text labels. I'd localize them as per-locale copies (assets/figures/zh/…) and keep the English originals unchanged.

Checks: extend verify-website.py to fail when:

a localized page has no English counterpart;
a hreflang alternate points at a missing page;
a locale's links, anchors or assets don't resolve (the existing per-page checks already cover these once the pages exist).

Keeping translations current: each localized page records the English source commit it was translated from (an HTML comment such as ). The checker can then list pages whose English source changed after that commit, so outdated translations are reported rather than silently diverging. I'd document this, plus how to submit a language update, in website/README.md, website/AGENTS.md and the style guide.

Delivery in reviewable slices:

Infrastructure (selector, lang/hreflang, fallback notice, checker, workflow docs) with homepage + Get started in the four languages.
Guides index and the three worked guides.
Showcase index and the DX-Ball, Notion and TH04 case studies, including localized figures.

Commands, API names, tool names and source excerpts stay in English in every slice. I'll check longer translated text on mobile, including the diagrams and code comparisons.

Does this direction work, particularly the language list and the /zh/… path layout? If you'd prefer different languages or a different structure, I'll adjust before starting slice 1.

@akram1089 commented on GitHub (Oct 7, 2026): I'd like to work on this. Before writing any pages, here's a proposal to agree on scope and structure, since the issue leaves the languages and URL layout open. **Initial languages:** Simplified Chinese (`zh`), Japanese (`ja`), Korean (`ko`) and Arabic (`ar`), matching the README translations reviewed under #958. Arabic also exercises right-to-left layout (`dir="rtl"`) early, before the page set grows. **URL structure:** keep English at the current paths and add path-prefixed mirrors, e.g. `website/public/zh/get-started/index.html` → `/zh/get-started/`. This fits the current static layout and `scripts/verify-website.py`'s relative-reference rule. Shared assets stay in `website/public/assets/`; localized pages reference them relatively (`../../assets/…`). No build step and no change to the single manually triggered Pages publisher. **Switching and metadata:** - A small language selector in the existing header nav. It links to the equivalent page through a static mapping, so it works without JavaScript. - Every page gets `<html lang>` (plus `dir="rtl"` for Arabic), `<link rel="alternate" hreflang>` for each available version, and a localized `<title>`/description. - A page without a translation falls back to English, with a visible one-line notice in the selected language. **Figures:** the three SVGs in `assets/figures/` contain text labels. I'd localize them as per-locale copies (`assets/figures/zh/…`) and keep the English originals unchanged. **Checks:** extend `verify-website.py` to fail when: - a localized page has no English counterpart; - a `hreflang` alternate points at a missing page; - a locale's links, anchors or assets don't resolve (the existing per-page checks already cover these once the pages exist). **Keeping translations current:** each localized page records the English source commit it was translated from (an HTML comment such as ``). The checker can then list pages whose English source changed after that commit, so outdated translations are reported rather than silently diverging. I'd document this, plus how to submit a language update, in `website/README.md`, `website/AGENTS.md` and the style guide. **Delivery in reviewable slices:** 1. Infrastructure (selector, `lang`/`hreflang`, fallback notice, checker, workflow docs) with **homepage + Get started** in the four languages. 2. Guides index and the three worked guides. 3. Showcase index and the DX-Ball, Notion and TH04 case studies, including localized figures. Commands, API names, tool names and source excerpts stay in English in every slice. I'll check longer translated text on mobile, including the diagrams and code comparisons. Does this direction work, particularly the language list and the `/zh/…` path layout? If you'd prefer different languages or a different structure, I'll adjust before starting slice 1.

bsakaguchi commented

2026-10-15 18:24:27 +00:00

Author

Owner

@N0zoM1z0 commented on GitHub (Oct 7, 2026):

Thanks @akram1089, we'd be happy to have you work on this! The four languages and the path-prefixed layout both work for us. Please go ahead with slice 1.

Our website philosophy is:

A good website is like a good paper: easy to follow, clear and concise, with a clean, refined presentation.

That applies to every language. Use natural wording, direct headings and figures that help readers understand the example at a glance. Show the question, what REA provides, and how that leads to the result. The website style guide covers the current approach.

Three things to keep in mind:

Start with the first PR. Let's review the infrastructure, homepage and Get started pages for layout and translation quality before expanding to the guides and showcases. Local previews will help us review the result.
Check the Arabic layout in practice. Keep commands, code and assembly left-to-right within the RTL pages. Review each figure's reading order and meaning rather than mirroring the whole diagram.
Track changes to the corresponding English page. An unrelated repository commit should not mark a translation outdated. Make the check work with CI's shallow checkout, or explicitly provide the history it needs. When a page falls back to English, make that clear to the reader in their selected language.

Looking forward to the first PR, and thanks for taking this on!

@N0zoM1z0 commented on GitHub (Oct 7, 2026): Thanks @akram1089, we'd be happy to have you work on this! The four languages and the path-prefixed layout both work for us. Please go ahead with slice 1. Our website philosophy is: > A good website is like a good paper: easy to follow, clear and concise, with a clean, refined presentation. That applies to every language. Use natural wording, direct headings and figures that help readers understand the example at a glance. Show the question, what REA provides, and how that leads to the result. The [website style guide](https://github.com/morluto/rea/blob/main/website/style-guide.md) covers the current approach. Three things to keep in mind: 1. **Start with the first PR.** Let's review the infrastructure, homepage and Get started pages for layout and translation quality before expanding to the guides and showcases. Local previews will help us review the result. 2. **Check the Arabic layout in practice.** Keep commands, code and assembly left-to-right within the RTL pages. Review each figure's reading order and meaning rather than mirroring the whole diagram. 3. **Track changes to the corresponding English page.** An unrelated repository commit should not mark a translation outdated. Make the check work with CI's shallow checkout, or explicitly provide the history it needs. When a page falls back to English, make that clear to the reader in their selected language. Looking forward to the first PR, and thanks for taking this on!

bsakaguchi commented

2026-10-15 18:24:27 +00:00

Author

Owner

@faeid2026 commented on GitHub (Oct 10, 2026):

Hi! I can help you set up and maintain the multilingual versions for your website right now. I specialize in high-speed React front-end development and dynamic layouts.

I can build a clean, multi-language structure that matches your acceptance criteria perfectly. You can check the level of modern UI and performance I deliver here: https://futureglow-display.lovable.app

I am active on my laptop right now. To start working on your multilingual setup immediately, you can send a quick upfront deposit of $20 directly to my PayPal link here: https://paypal.me/faiedpaypal

As soon as the deposit is sent, I will code the template structure and post a live preview here for you to check. Let's get this done today!

@faeid2026 commented on GitHub (Oct 10, 2026): Hi! I can help you set up and maintain the multilingual versions for your website right now. I specialize in high-speed React front-end development and dynamic layouts. I can build a clean, multi-language structure that matches your acceptance criteria perfectly. You can check the level of modern UI and performance I deliver here: https://futureglow-display.lovable.app I am active on my laptop right now. To start working on your multilingual setup immediately, you can send a quick upfront deposit of $20 directly to my PayPal link here: https://paypal.me/faiedpaypal As soon as the deposit is sent, I will code the template structure and post a live preview here for you to check. Let's get this done today!

bsakaguchi commented

2026-10-15 18:24:27 +00:00

Author

Owner

@N0zoM1z0 commented on GitHub (Oct 11, 2026):

Implemented in #1779 and published to rea.tools and GitHub Pages.

All 19 README editions now have matching website versions, including guides, showcases, the blog, figures and interactive messages. Language switching opens the equivalent page and preserves its anchor. Arabic and Persian use RTL layouts.

Translations live in standard PO catalogs; English source changes mark affected text as pending, with a visible English fallback until it is updated. The translation contribution guide covers editing, review and checks. Further language corrections are welcome.

CI and review passed. Both hosts serve the same verified revision; online language routes, metadata, downloads and mobile interactions were checked. Contributor refinements from #1737 were incorporated with co-author credit.

@N0zoM1z0 commented on GitHub (Oct 11, 2026): Implemented in #1779 and published to [rea.tools](https://rea.tools/) and [GitHub Pages](https://morluto.github.io/rea/). All 19 README editions now have matching website versions, including guides, showcases, the blog, figures and interactive messages. Language switching opens the equivalent page and preserves its anchor. Arabic and Persian use RTL layouts. Translations live in standard PO catalogs; English source changes mark affected text as pending, with a visible English fallback until it is updated. The [translation contribution guide](https://github.com/morluto/rea/blob/main/website/locales/README.md) covers editing, review and checks. Further language corrections are welcome. CI and review passed. Both hosts serve the same verified revision; online language routes, metadata, downloads and mobile interactions were checked. Contributor refinements from #1737 were incorporated with co-author credit.

bsakaguchi referenced this issue

2026-10-15 18:28:29 +00:00

[GH-ISSUE #2383] [Tracker] Audit analysis and debugging coverage for the TIOBE top 100 languages (October 2026) #794

bsakaguchi referenced this issue

2026-10-16 21:13:22 +00:00

[PR #464] [MERGED] feat(electron): add autonomous Electron runtime analysis #2012

bsakaguchi added

enhancement

and removed

enhancement

labels

2026-10-31 00:29:06 +00:00