Skip to content

docs(i18n): defer README template-driven generation, capture #195 discussion#403

Open
laihenyi wants to merge 1 commit intonexu-io:mainfrom
laihenyi:feat/translations-defer-readme-tooling
Open

docs(i18n): defer README template-driven generation, capture #195 discussion#403
laihenyi wants to merge 1 commit intonexu-io:mainfrom
laihenyi:feat/translations-defer-readme-tooling

Conversation

@laihenyi
Copy link
Copy Markdown
Contributor

@laihenyi laihenyi commented May 4, 2026

Follow-up to #196 / discussion in #195. After PR #196 landed, @andriishin pointed out NRG (single .src.md template → multi-locale README.<lang>.md) as a fix for the atomic-update brittleness called out in TRANSLATIONS.md step 7. @lefarcen analyzed the fit and we agreed the right move is document-and-defer rather than fold tooling into the docs RFC.

This PR captures that decision in TRANSLATIONS.md so future contributors don't relitigate it from scratch.

What changes

A single bullet under Deferred decisions — parallel in shape to the existing Translation memory tooling entry:

  • Lists multiple options (NRG, custom .src.md scripts, All Contributors-style) so we don't lock into one tool prematurely.
  • Trigger conditions: ≥15 locales OR README structural edits more frequent than monthly.
  • Records the core trade-off from the RFC: TRANSLATIONS.md — i18n contribution guide and starter glossary #195 thread: template-driven generation solves the "update line 27 in 10 README variants" brittleness but forces a shared structure that today's locale variants intentionally diverge from (e.g. README.zh-TW.md's "上手體驗" section, the pt-BR / pt-PT content-level precedent).

Why "Deferred" not "Open question"

The existing Open questions section is for genuinely undecided items. NRG-class tooling has been actively discussed in #195 and the team agreed to defer with explicit triggers — that's the same shape as the TM-tooling entry already living under Deferred decisions.

Out of scope

A separate tracking issue ("Evaluate template-driven README generation") will collect NRG + alternatives and link back here. That's a separate, smaller change that doesn't need to ride with this docs update.

Test plan

 discussion

Add NRG / template-driven README generation to TRANSLATIONS.md
"Deferred decisions" with explicit re-evaluation triggers (≥15 locales
or monthly+ README structural edits) and a record of the shared-structure
trade-off that surfaced in nexu-io#195. Captures the rationale (zh-TW's
"上手體驗" section, pt-BR vs pt-PT content-level divergence precedent)
so future contributors don't relitigate it from scratch.
@lefarcen
Copy link
Copy Markdown
Contributor

lefarcen commented May 4, 2026

Hi @laihenyi! 🎉
Thanks for the contribution — excellent follow-up capturing the NRG discussion from #195.
I will run a deep review and get back to you within 24h.

Thanks for making open-design better!
— open-design team

@lefarcen lefarcen added the documentation Improvements or additions to documentation label May 4, 2026
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.

@laihenyi I reviewed the TRANSLATIONS.md deferred-decision update and verified the new README template-generation guidance is scoped to the changed documentation, keeps the existing deferred-decisions structure, and records clear revisit triggers plus the locale-variation trade-off. This is a tidy follow-up that should make future i18n tooling discussions easier to pick up without forcing premature process changes. Thanks for capturing the rationale so clearly. 🙌

Generated by Looper 0.0.0-dev · runner=reviewer · agent=opencode

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