Skip to content

Generate the six READMEs from a single README.src.md (NRG)#14

Open
andriishin wants to merge 1 commit into
developersu:masterfrom
andriishin:add-nrg-template
Open

Generate the six READMEs from a single README.src.md (NRG)#14
andriishin wants to merge 1 commit into
developersu:masterfrom
andriishin:add-nrg-template

Conversation

@andriishin
Copy link
Copy Markdown

Привет! 👋 / こんにちは / Hi! This PR migrates the six README files (README.md, README_ES.md, README_ID.md, README_JP.md, README_RU.md, README_RYU.md) to a single README.src.md template; all six are then regenerated by Nanolaba Readme Generator (NRG) during mvn compile.

Why

Six parallel READMEs drift fast. Even now there are small inconsistencies:

  • README_RU.md is missing the Indonesian flag link that other locales have.
  • README_ID.md mistakenly links to itself in the language list.
  • Badge layout in README_ID.md is split across 3 lines while every other locale uses one line.
  • README_JP.md / README_RYU.md use GLPv3以降 (no space) while README.md uses GLPv3 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

  1. New 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).
  2. Renamed README_*.mdREADME.*.md (lowercase, dot-separated suffix) — required by NRG's convention <base>.<lang>.md. Git tracks them as renames (≥51% similarity each). The default README.md stays at the same path.
    • README_ES.mdREADME.es.md
    • README_ID.mdREADME.id.md
    • README_JP.mdREADME.ja.md (note: ja is the standard ISO 639-1 code for Japanese)
    • README_RU.mdREADME.ru.md
    • README_RYU.mdREADME.ryu.md
  3. Modified pom.xml — adds com.nanolaba:nrg-maven-plugin:1.0 (≈22-line <plugin> block at the end of <build><plugins>). Default phase is compile, no extra config.
  4. Modified files carry a 2-line NRG-added header (<!-- This file was automatically generated by NRG 1.0 -->) so future contributors know to edit README.src.md instead.

How to verify

  1. Run mvn compile (or ./mvnw compile if you use the wrapper) — NRG will regenerate all six READMEs from README.src.md.
  2. git diff should be empty (or only show the NRG header rewrite if the SNAPSHOT version bumped).
  3. Each file's flag-link section shows links to the other five languages with locale-correct alt-text (e.g. [![Английский язык]…] only in README.ru.md, [![英語]…] only in README.ja.md and README.ryu.md, etc.).
  4. Inconsistencies listed in Why are normalized away.

Side effects

  • External links to README_RU.md etc. (e.g. from blog posts or git mirror) will 404 until updated to the new README.ru.md paths. 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.
  • Inside the project, the README.md flag 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. Я с радостью помогу с правками, если решите попробовать. 🙇

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

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant