Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

[Release] Exempt translations from Changeset coverage (#7644)

nynexman4464d52db364d8da
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 03993cf35d..70749bdd90 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -704,6 +704,10 @@ example `pnpm changeset:new --packages @astryxdesign/cli --category docs`. Run
the check locally with
`node scripts/release/changeset-coverage.mjs pr --base origin/main --explain`.
+Translation updates and new languages need no Changeset; changes to English
+source messages or keys still do. Removing a released language import path
+follows the [breaking-change policy](docs/specs/AST-017/spec.md).
+
The same check compares the CLI's machine-readable ids with the latest
release: response `type` values, response fields, golden JSON fields, and
`astryx doctor` check ids. Removing or renaming a released one breaks scripts
diff --git a/docs/specs/AST-017/spec.md b/docs/specs/AST-017/spec.md
index 797c43cdfa..05ccb011bb 100644
--- a/docs/specs/AST-017/spec.md
+++ b/docs/specs/AST-017/spec.md
@@ -213,6 +213,10 @@ one removal merged ahead of the decision to allow it.
tier its change requires; it never sets the release version, which is the version
main declares under FR46.
Documentation-only, test-only, and private-package-only changes need no Changeset.
+ Translation-catalog updates and newly added languages need no Changeset, nor
+ English-catalog description or formatting edits that preserve every message key
+ and default message. This exemption never covers removal of a released locale
+ import path, which follows FR3–FR4 and FR31.
Existing Changesets keep their current tag and validated bump semantics and MUST NOT
be mass-migrated. `pnpm changeset:new` remains the authoring path, and
`pnpm check:changesets` validates tag, bump, contributors, and the declared tier;
diff --git a/scripts/release/changeset-coverage.mjs b/scripts/release/changeset-coverage.mjs
index 3910c62368..0712e5eb86 100644
--- a/scripts/release/changeset-coverage.mjs
+++ b/scripts/release/changeset-coverage.mjs
@@ -11,7 +11,9 @@
* `files`, root README, or consumer-facing package.json fields) needs a
* Changeset, added or edited by the same change, naming that package. Tests,
* stories, spec records, generated CHANGELOGs, unpacked files, private and
- * canary-only packages, and everything outside a package need none.
+ * canary-only packages, and everything outside a package need none. Translation
+ * updates/additions and translator-description-only edits are exempt; removed
+ * locale paths and English message/key changes still need coverage.
* 2. Released CLI JSON ids: a response `type`, response field, golden field, or
* doctor check id from the latest stable release that is missing at head
* breaks scripts (spec:AST-017 FR3, FR13). The change that removes it, or
@@ -28,7 +30,7 @@
import {execFileSync} from 'node:child_process';
import path from 'node:path';
import {createRequire} from 'node:module';
-import {parseArgs} from 'node:util';
+import {isDeepStrictEqual, parseArgs} from 'node:util';
import {fileURLToPath} from 'node:url';
import {parseFrontmatter} from '../check-changesets.mjs';
import {parseWorkspaceGlobs} from '../lib/workspace-globs.mjs';
@@ -350,6 +352,51 @@ function changedChangesets(changes, head) {
}));
}
+/**
+ * Translation updates and additions need no release note; removed paths do.
+ * English message/key changes still need coverage; descriptions do not.
+ * The catalog gate, not this dependency-free release check, validates ICU.
+ */
+function localeCoverageExemption(file, base, head) {
+ const locale = /^packages\/core\/locales\/([^/]+)\.json$/.exec(file)?.[1];
+ if (!locale || locale === 'pseudo') return null;
+ if (locale !== 'en')
+ return head.read(file) === null ? null : 'translated locale catalog';
+
+ const messages = catalog => {
+ if (!catalog || typeof catalog !== 'object' || Array.isArray(catalog))
+ return null;
+ const entries = Object.entries(catalog);
+ if (
+ entries.length === 0 ||
+ entries.some(
+ ([, entry]) =>
+ !entry ||
+ typeof entry !== 'object' ||
+ Array.isArray(entry) ||
+ typeof entry.defaultMessage !== 'string' ||
+ (Object.hasOwn(entry, 'description') &&
+ typeof entry.description !== 'string') ||
+ Object.keys(entry).some(
+ key => key !== 'defaultMessage' && key !== 'description',
+ ),
+ )
+ )
+ return null;
+ return Object.fromEntries(
+ entries.map(([key, entry]) => [key, entry.defaultMessage]),
+ );
+ };
+
+ const before = messages(readJson(base, file));
+ const after = messages(readJson(head, file));
+ // Both sides must exist and have the known rich-catalog shape.
+ if (before === null || after === null) return null;
+ return isDeepStrictEqual(before, after)
+ ? 'translator descriptions or formatting only'
+ : null;
+}
+
/**
* Rule 1 for one change (a pull request, or one commit of a release range).
*
@@ -416,6 +463,11 @@ export function checkCoverage({
exempt.push({file, reason: result.reason});
continue;
}
+ const localeExemption = localeCoverageExemption(file, base, head);
+ if (localeExemption) {
+ exempt.push({file, reason: localeExemption});
+ continue;
+ }
if (result.surface === 'manifest') {
const fields = consumerManifestDelta(
readJson(base, file),
diff --git a/scripts/release/changeset-coverage.test.mjs b/scripts/release/changeset-coverage.test.mjs
index b56d538933..0d45fe6bf3 100644
--- a/scripts/release/changeset-coverage.test.mjs
+++ b/scripts/release/changeset-coverage.test.mjs
@@ -6,7 +6,7 @@
* @input in-memory repository trees shaped like the real workspace
* @output proofs that a shipped change needs a Changeset naming its package,
* that exempt surfaces need none, and that a released CLI JSON id cannot
- * disappear unclassified — including red arms replaying #7125 and #7154
+ * disappear unclassified — including regressions for #7125, #7154, and #7626
* @position focused suite for scripts/release/changeset-coverage.mjs
*/
@@ -312,6 +312,236 @@ describe('isPackedFile, isWorkspaceDir, consumerManifestDelta', () => {
});
});
+describe('rule 1 — locale updates', () => {
+ const english = 'packages/core/locales/en.json';
+ const french = 'packages/core/locales/fr-FR.json';
+ const key = '@astryx.commandPalette.noResultsFor';
+ const loading = '@astryx.commandPalette.loading';
+ const catalog = {
+ [key]: {
+ defaultMessage: 'Aucun résultat pour {query}',
+ description: 'Old context.',
+ },
+ [loading]: {defaultMessage: 'Chargement', description: 'Loading context.'},
+ };
+ const base = repo({
+ 'packages/core/package.json': manifest('@astryxdesign/core', {
+ files: ['src', 'locales'],
+ }),
+ [english]: JSON.stringify({
+ [key]: {
+ defaultMessage: 'No results for {query}',
+ description: 'Old context.',
+ },
+ [loading]: {defaultMessage: 'Loading', description: 'Loading context.'},
+ }),
+ [french]: JSON.stringify(catalog),
+ });
+
+ it('replays #7626: description-only edits in 29 existing locales need no Changeset', () => {
+ const locales = [
+ 'af-ZA',
+ 'ar-SA',
+ 'ca-ES',
+ 'cs-CZ',
+ 'da-DK',
+ 'de-DE',
+ 'el-GR',
+ 'es-ES',
+ 'fi-FI',
+ 'fr-FR',
+ 'he-IL',
+ 'hu-HU',
+ 'it-IT',
+ 'ja-JP',
+ 'ko-KR',
+ 'nl-NL',
+ 'no-NO',
+ 'pl-PL',
+ 'pt-BR',
+ 'pt-PT',
+ 'ro-RO',
+ 'ru-RU',
+ 'sr-SP',
+ 'sv-SE',
+ 'tr-TR',
+ 'uk-UA',
+ 'vi-VN',
+ 'zh-CN',
+ 'zh-TW',
+ ];
+ const before = {...base};
+ const after = {...base};
+ for (const locale of locales) {
+ const file = `packages/core/locales/${locale}.json`;
+ before[file] = JSON.stringify(catalog);
+ after[file] = JSON.stringify({
+ ...catalog,
+ [key]: {
+ ...catalog[key],
+ description:
+ 'Not read by any component: CommandPalette announces emptySearchText instead.',
+ },
+ });
+ }
+ const result = change(before, after);
+ expect(result.problems).toEqual([]);
+ expect(result.coverage.exempt).toHaveLength(29);
+ });
+
+ it('exempts translator descriptions in English, including JSON property reordering', () => {
+ const source = JSON.parse(base[english]);
+ source[key] = {
+ description: 'Updated context.',
+ defaultMessage: source[key].defaultMessage,
+ };
+ expect(
+ change(base, {...base, [english]: JSON.stringify(source)}).problems,
+ ).toEqual([]);
+ });
+
+ it.each([
+ [
+ 'corrected text',
+ {
+ ...catalog,
+ [key]: {
+ ...catalog[key],
+ defaultMessage: 'Aucun résultat trouvé pour {query}',
+ },
+ },
+ ],
+ ['filled translation', {[key]: catalog[key], [loading]: catalog[loading]}],
+ ['omitted translation', {[key]: catalog[key]}],
+ ])('exempts an existing language’s %s', (name, translated) => {
+ const before =
+ name === 'filled translation'
+ ? {...base, [french]: JSON.stringify({[key]: catalog[key]})}
+ : base;
+ expect(
+ change(before, {...base, [french]: JSON.stringify(translated)}).problems,
+ ).toEqual([]);
+ });
+
+ it.each([
+ [
+ 'new language',
+ 'packages/core/locales/es-ES.json',
+ JSON.stringify(catalog),
+ ],
+ ['empty catalog', french, '{}'],
+ ['malformed JSON', french, '{'],
+ ['non-catalog JSON', french, '[]'],
+ ['invalid message', french, JSON.stringify({[key]: {defaultMessage: 42}})],
+ [
+ 'unknown field',
+ french,
+ JSON.stringify({...catalog, [key]: {...catalog[key], runtime: true}}),
+ ],
+ ])(
+ 'needs no Changeset for a translated catalog’s %s',
+ (name, file, contents) => {
+ const head = {...base, [file]: contents};
+ if (contents === null) delete head[file];
+ expect(change(base, head).problems).toEqual([]);
+ },
+ );
+
+ it('requires a Changeset when a translated locale is renamed without keeping its old path', () => {
+ const head = {...base, 'packages/core/locales/fr.json': base[french]};
+ delete head[french];
+ const result = change(base, head);
+ expect(result.problems).toHaveLength(1);
+ expect(result.problems[0]).toContain('fr-FR.json');
+ expect(result.coverage.exempt).toHaveLength(1);
+ });
+
+ it.each([
+ ['removed language', french, null],
+ [
+ 'committed pseudo-locale',
+ 'packages/core/locales/pseudo.json',
+ JSON.stringify(catalog),
+ ],
+ [
+ 'English key addition',
+ english,
+ JSON.stringify({
+ ...JSON.parse(base[english]),
+ '@astryx.newMessage': {
+ defaultMessage: 'New message',
+ description: 'New context.',
+ },
+ }),
+ ],
+ ['new English catalog', english, JSON.stringify(catalog)],
+ ['removed English catalog', english, null],
+ ['malformed English JSON', english, '{'],
+ ['empty English catalog', english, '{}'],
+ ['non-catalog English JSON', english, '[]'],
+ [
+ 'invalid English message',
+ english,
+ JSON.stringify({[key]: {defaultMessage: 42}}),
+ ],
+ [
+ 'unknown English field',
+ english,
+ JSON.stringify({[key]: {...catalog[key], runtime: true}}),
+ ],
+ [
+ 'nested locale path',
+ 'packages/core/locales/sub/fr-FR.json',
+ JSON.stringify(catalog),
+ ],
+ [
+ 'English copy',
+ english,
+ JSON.stringify({
+ ...JSON.parse(base[english]),
+ [key]: {
+ defaultMessage: 'Nothing matches {query}',
+ description: 'Old context.',
+ },
+ }),
+ ],
+ [
+ 'English key removal',
+ english,
+ JSON.stringify({[key]: JSON.parse(base[english])[key]}),
+ ],
+ ])('still requires a Changeset for %s', (name, file, contents) => {
+ const before = {...base};
+ if (name === 'new English catalog') delete before[english];
+ const head = {...before, [file]: contents};
+ if (contents === null) delete head[file];
+ expect(change(before, head).problems).toHaveLength(1);
+ });
+
+ it('requires a Changeset when English is renamed to a translated locale', () => {
+ const head = {...base, 'packages/core/locales/fr.json': base[english]};
+ delete head[english];
+ const result = change(base, head);
+ expect(result.problems).toHaveLength(1);
+ expect(result.problems[0]).toContain('en.json');
+ });
+
+ it('does not exempt source changes mixed with a routine translation update', () => {
+ const head = {
+ ...base,
+ [french]: JSON.stringify({
+ ...catalog,
+ [key]: {...catalog[key], description: 'Updated context.'},
+ }),
+ 'packages/core/src/Button/Button.tsx': 'export const Button = 2;\n',
+ };
+ const result = change(base, head);
+ expect(result.problems).toHaveLength(1);
+ expect(result.problems[0]).toContain('Button.tsx');
+ expect(result.coverage.exempt).toHaveLength(1);
+ });
+});
+
describe('rule 1 — a shipped change names its package', () => {
it('passes when a Changeset in the change names the package', () => {
const base = repo();