Generate the six READMEs from a single README.src.md (NRG)#14
Open
andriishin wants to merge 1 commit into
Open
Generate the six READMEs from a single README.src.md (NRG)#14andriishin wants to merge 1 commit into
andriishin wants to merge 1 commit into
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
Six parallel READMEs drift fast. Even now there are small inconsistencies:
README_RU.mdis missing the Indonesian flag link that other locales have.README_ID.mdmistakenly links to itself in the language list.README_ID.mdis split across 3 lines while every other locale uses one line.README_JP.md/README_RYU.mduseGLPv3以降(no space) whileREADME.mdusesGLPv3 or higher.NRG keeps everything in sync from one source. The plugin is small (one Maven dependency, no runtime), Apache 2.0, Java 8 — fits the project's existing constraints.
What changed
README.src.md(~75 lines) — single template covering all six languages. Identical content (badges, screenshots, link URLs) appears once; per-language strings use either the inline${en:'…', es:'…', id:'…', ja:'…', ru:'…', ryu:'…'}form (one-line items) or per-line<!--lang-->markers (multi-language flag block, where each locale shows links to the other five).README_*.md→README.*.md(lowercase, dot-separated suffix) — required by NRG's convention<base>.<lang>.md. Git tracks them as renames (≥51% similarity each). The defaultREADME.mdstays at the same path.README_ES.md→README.es.mdREADME_ID.md→README.id.mdREADME_JP.md→README.ja.md(note:jais the standard ISO 639-1 code for Japanese)README_RU.md→README.ru.mdREADME_RYU.md→README.ryu.mdpom.xml— addscom.nanolaba:nrg-maven-plugin:1.0(≈22-line<plugin>block at the end of<build><plugins>). Default phase iscompile, no extra config.<!-- This file was automatically generated by NRG 1.0 -->) so future contributors know to editREADME.src.mdinstead.How to verify
mvn compile(or./mvnw compileif you use the wrapper) — NRG will regenerate all six READMEs fromREADME.src.md.git diffshould be empty (or only show the NRG header rewrite if the SNAPSHOT version bumped).[![Английский язык]…]only inREADME.ru.md,[![英語]…]only inREADME.ja.mdandREADME.ryu.md, etc.).Side effects
README_RU.mdetc. (e.g. from blog posts or git mirror) will 404 until updated to the newREADME.ru.mdpaths. This is the main downside of the rename. If the cost is too high, easy alternative: keep the old files as 1-line shims that say "Moved to README.ru.md" — happy to add that.README.mdflag block links to the new paths.What NRG is
NRG is an Apache 2.0, Java 8 Markdown template engine purpose-built for multi-language READMEs. Distributed as a CLI, Maven plugin, and Java library. v1.0 on Maven Central. Used to generate its own README from
README.src.md.If the migration angle doesn't fit Tihwin's direction, no problem — feel free to close. Я с радостью помогу с правками, если решите попробовать. 🙇