|
| 1 | +# Contributing |
| 2 | + |
| 3 | +Contributions are welcome! Content is managed as YAML files — never edit generated HTML. |
| 4 | + |
| 5 | +## Adding a new pattern |
| 6 | + |
| 7 | +1. Fork the repo |
| 8 | +2. Create a new YAML file in the appropriate `content/<category>/` folder (e.g. `content/language/my-feature.yaml`) |
| 9 | +3. Copy [`content/template.json`](content/template.json) as a starting point for all required fields (see the [snippet schema](.github/copilot-instructions.md) for details) |
| 10 | +4. Update the `prev`/`next` fields in adjacent pattern files to maintain navigation |
| 11 | +5. Run `jbang html-generators/generate.java` to verify your changes build correctly |
| 12 | +6. Open a pull request |
| 13 | + |
| 14 | +Please ensure JDK version labels only reference the version where a feature became **final** (non-preview). |
| 15 | + |
| 16 | +## Translating the site |
| 17 | + |
| 18 | +The site supports multiple languages. See [`specs/i18n/i18n-spec.md`](specs/i18n/i18n-spec.md) for the full specification. |
| 19 | + |
| 20 | +### Adding a new locale |
| 21 | + |
| 22 | +1. Add the locale to `html-generators/locales.properties` (e.g. `ja=日本語`) |
| 23 | +2. Create `translations/strings/<locale>.yaml` with all UI strings translated (copy `translations/strings/en.yaml` as a starting point) |
| 24 | +3. Create content translation files under `translations/content/<locale>/<category>/<slug>.yaml` |
| 25 | +4. Run `jbang html-generators/generate.java` and verify the build succeeds |
| 26 | +5. Open a pull request |
| 27 | + |
| 28 | +### Translating content files |
| 29 | + |
| 30 | +Translation files contain **only** translatable fields — the generator merges them onto the English base at build time. This prevents translated files from diverging structurally from the English source of truth. |
| 31 | + |
| 32 | +A translation file should contain exactly these fields: |
| 33 | + |
| 34 | +```yaml |
| 35 | +title: "Inferencia de tipos con var" |
| 36 | +oldApproach: "Tipos explícitos" |
| 37 | +modernApproach: "Palabra clave var" |
| 38 | +summary: "Usa var para inferencia de tipos..." |
| 39 | +explanation: "Desde Java 10, el compilador infiere..." |
| 40 | +whyModernWins: |
| 41 | + - icon: "⚡" |
| 42 | + title: "Menos código repetitivo" |
| 43 | + desc: "No es necesario repetir tipos genéricos..." |
| 44 | + - icon: "👁" |
| 45 | + title: "Mejor legibilidad" |
| 46 | + desc: "..." |
| 47 | + - icon: "🔒" |
| 48 | + title: "Igualmente seguro" |
| 49 | + desc: "..." |
| 50 | +support: |
| 51 | + description: "Ampliamente disponible desde JDK 10 (marzo 2018)" |
| 52 | +``` |
| 53 | +
|
| 54 | +Do **not** include `id`, `slug`, `category`, `difficulty`, `jdkVersion`, `oldCode`, `modernCode`, `prev`, `next`, `related`, or `docs` — these are always taken from the English source. |
| 55 | + |
| 56 | +**Important:** If your text contains colons (`:`), ensure the value is properly quoted in YAML to avoid parse errors. Always validate with `jbang html-generators/generate.java` before submitting. |
0 commit comments