SoyaOS

Generate three release-note locales from structured facts

Produce zh, zh-hant, and en release notes from one closed fact source, with invariant checks and SHA-256 integrity.

Release notes often need localization, but translation must not change versions, quotas, endpoints, or product boundaries. This Recipe generates Simplified Chinese, Traditional Chinese, and English Markdown from one structured fact file and validates every output deterministically.

Fact source

The default examples/soyaos-cloud-v0.2.0.json input comes from the official v0.2.0 Release. It records product and release identity, official links, and each fact’s unique ID, kind, source text, and invariant strings.

SoyaOS Cloud may translate titles, summaries, and fact prose. It cannot add URLs, numbers, or new facts. The renderer takes versions, dates, and links directly from the source file.

Prepare and run

Install Node.js 22 or later and create an API Key through the Cloud quickstart. Treat the Key as an opaque string and keep it in the current shell’s environment.

git clone https://github.com/soyaos/cloud-recipes.git
cd cloud-recipes
export SOYA_API_KEY='your-soyaos-api-key'
npm run run:multilingual-release-notes

The default package is:

output/soyaos-cloud-v0.2.0-release-notes/
├── zh.md
├── zh-hant.md
├── en.md
└── manifest.json

Why use a closed fact set

A generic “write release notes” prompt makes one model discover facts, judge them, and translate them at once. Errors become difficult to isolate. This Recipe first fixes verified facts in JSON, then gives Cloud the language work it handles best.

The validator requires exactly zh, zh-hant, and en; identical fact IDs in identical order; every invariant preserved verbatim; no unapproved numbers or URLs; English prose without CJK text; and recognizable Traditional Chinese text in zh-hant.

If the first response is invalid, one repair is allowed. A second failure stops closed.

Manifest and gates

manifest.json records release identity, the fact list, Cloud requestIds, and the SHA-256 of each Markdown file. Changing any output after generation breaks its integrity check.

Five gates cover content, Markdown structure, language, manifest integrity, and security. Only after they all pass does the Recipe atomically rename its temporary directory into the final package, so it cannot deliver a partial result.

Generate another release

Copy the example JSON, populate the same schema with verified facts for another release, and run:

node recipes/multilingual-release-notes/run.mjs \
  --input examples/your-release.json \
  --output output/your-release-notes

Do not treat unverified marketing copy as facts, and never place an API Key in the input file.

Common errors

  • invalid_facts: invalid structure, credential-bearing URL, or duplicate fact ID.
  • locale_mismatch: the model did not return all three exact locales.
  • invariant_changed: a technical identifier, quota, or other invariant changed.
  • invented_number / invented_url: the model added data outside the fact set.
  • quality_gate_failed: language, structure, hash, or security validation failed.

Source and tests: soyaos/cloud-recipes

Edit this page on GitHub