Locale Bundle Contract Gate

Locale Bundle Contract Gate is a deterministic Apify Actor that compares one reference JSON/YAML locale bundle with up to 20 candidates. It reports missing and extra keys, value-type changes, message-contract drift, locale-aware plural mistakes, and HTML element-structure drift. It never translates text and calls no AI or paid API.

The useful output is not merely a pass/fail bit. Every finding includes a readable key path, RFC 6901 JSON Pointer, expected/actual evidence when applicable, and a concrete repair action. The Actor writes the same authoritative record to the default dataset and the OUTPUT key, preserves every source as a key-value record with its SHA-256 hash, and emits REPORT.SARIF, REPORT.JUNIT.XML, and REPORT.MD.

Message syntax is explicit

• plain: structure, types, keys, and optional HTML only. Braces have no message meaning.
• i18next: {{name}} interpolation plus _one, _few, _many, _other, and related suffix groups. Expected suffixes come from Intl.PluralRules(candidateLocale), so Korean is not forced to copy English categories.
• icu: ICU MessageFormat parsing, argument-name/type checks, select branches, and candidate-locale plural/ordinal categories. {{name}} is never accidentally parsed as ICU when i18next is selected.

Input

Paste content or provide a public HTTPS URL for the base and each candidate. Exactly one source is required per bundle. URL fields are intentionally plain text in the Apify schema; runtime validation separately enforces HTTPS, no credentials, port 443, public-only DNS answers, pinned request lookup, connected-socket verification, revalidation after every redirect, three redirects, 10 seconds, and 1 MiB per source.

See examples/input.json and examples/output.json. The deterministic demo in canary_input.json uses only inline content and requires no network.

Local verification

npm ci --ignore-scripts
npm run preflight
docker build --pull=false -t locale-bundle-contract-gate:local .
docker run --rm --network none -e AUTOMATON_CONTAINER_SMOKE=1 locale-bundle-contract-gate:local

The smoke branch is selected only when AUTOMATON_CONTAINER_SMOKE=1; otherwise the Actor uses its bounded native storage adapter and requires Actor input. Tests include a real downstream CI experiment that runs deliberately broken and corrected fixture files through production analysis code.

CI decision

With failOn: "error" (default), the Actor saves all reports first and then exits non-zero when error findings exist. failOn: "never" is useful when a downstream step reads OUTPUT.status. Warnings, currently extra keys, do not fail the gate.

Honest comparison and limits

Resource limits are enforced before comparison output is stored: 20 candidates, 1 MiB per source, 8 MiB across sources, 25,000 JSON/YAML values, depth 40, 1,024 UTF-8 bytes per key, 4,096 bytes per rendered readable path or RFC 6901 path, and 2 MiB of cumulative expanded paths per parsed bundle. Source URLs are limited to 2,048 bytes and locale identifiers to 128 bytes.

Finding messages and expected/actual evidence are bounded; evidence over 4 KiB is represented by an explicit truncated: true preview with its original byte length and SHA-256, never as a complete value. The retained finding set obeys both maxFindings and a 256 KiB cumulative serialized-finding budget while complete per-locale and global error/warning counts are tracked independently. Thus status remains FAIL when an error is not retained. OUTPUT, SARIF, JUnit, and Markdown are each checked against a 1 MiB ceiling before any production storage write. A truncated report states how many findings it retained; aggregate counts remain authoritative.

The free @lingual/i18n-check already checks ICU/i18next JSON/YAML bundles, missing keys, and invalid keys, and is the better choice when installing a local CLI is acceptable. This Actor is not sold as a novel implementation of those checks. Its product-specific value is a hosted, bounded contract with retained source hashes, exact dual paths, three CI report formats, one stable dataset record, and Apify API/workflow consumption. It does not scan application source for unused keys, translate strings, judge language quality, support PO/XLIFF/ARB, or prove that rendered UI is correct.

Automated plural checks are contract policy, not linguistic proof. ICU mode expects the candidate locale's plural categories plus explicit numeric selectors found in the base. Teams that intentionally collapse categories should use plain mode or adapt their bundle before gating.

Output contract

tests/canary-output.schema.json is the authoritative JSON Schema for the OUTPUT record. Apify's input, output-link, and dataset schemas remain distinct platform contracts in .actor. actor.json references the exact uploaded files.

Privacy and cost

Inline runs make no network calls. URL mode fetches only URLs explicitly supplied by the user. No credentials, proxy, browser, paid API, webhook, schedule, or external AI is used. See SECURITY_REVIEW.md, PRICING_PROPOSAL.md, and SUPPORT.md.

Release readiness is owned by the Automaton workflow and Portfolio, not a claim embedded in uploaded source. The local QA report records implementation checks; signed exact-bundle Docker validation and actual Private Build/Canary receipts must also pass before READY_TO_PUBLISH. Public visibility, Store publication, monetization and icon registration remain separately approved manual actions.