@dittowords/spec-cli 0.0.1-alpha.7 → 0.0.1-alpha.8

package/README.md

@@ -54,6 +54,12 @@ rules:
     description: Always use as two words (verb form)
     styleguide: Acme Inc.
     section: Terminology
+locales:
+  de-DE:
+    - name: Use informal address
+      description: Use "Du" instead of "Sie" for all user-facing copy
+      styleguide: German
+      section: Formality
 ---
 ```
 
@@ -66,7 +72,17 @@ A repo may have a single `workspace.ditto.md` somewhere under the CLI's configur
 workspace: true
 # Managed by Ditto — do not edit below
 tags: [body, button, call-to-action, dialog-title, heading, nav]
-rules: []
+rules:
+  - name: Write in active voice
+    description: Lead with verbs, avoid passive constructions
+    styleguide: Acme Inc.
+    section: Voice & Tone
+locales:
+  de-DE:
+    - name: Use informal address
+      description: Use "Du" instead of "Sie" for all user-facing copy
+      styleguide: German
+      section: Formality
 ---
 ```
 
@@ -74,7 +90,7 @@ rules: []
 
 **Developer-owned keys**: `component`, `tags`, `surfaces`. Edit these freely.
 
-**CLI-managed keys**: `rules` and workspace `tags`. Overwritten by `ditto-spec pull`. Do not edit by hand. Rules come in two shapes: style rules (`name`/`description`/`examples`) and terminology entries (`term`/`disallowed`/`description`).
+**CLI-managed keys**: `rules`, `locales`, and workspace `tags`. Overwritten by `ditto-spec pull`. Do not edit by hand. Rules come in two shapes: style rules (`name`/`description`/`examples`) and terminology entries (`term`/`disallowed`/`description`).
 
 **Surface keys** identify each distinct piece of user-facing text the component renders. For text passed as props, use the prop path as the key — dot-notation works for nested props (e.g., `primaryAction.label`). Use `$children` for text via the `children` prop. For hardcoded or internal strings, use a descriptive role name (e.g., `headline`, `bodyText`, `submitLabel`).
 
@@ -82,13 +98,16 @@ rules: []
 
 **`maxLength` / `minLength`** are hard layout constraints, not stylistic preferences. Stylistic guidance belongs on the platform as rules.
 
-### Three-level rule hierarchy
+### Rule hierarchy
 
 | Scope | Where | Applies to |
 |---|---|---|
 | **Workspace** | `workspace.ditto.md` `rules[]` | Every surface in every component |
 | **Component-level** | Component's `rules[]`, no `surface` field | Every surface in this component |
 | **Per-surface** | Component's `rules[]`, with `surface: "<key>"` | That one surface |
+| **Locale-scoped** | `locales.<code>[]` (workspace or component) | Same hierarchy as above, but only when writing copy for that locale |
+
+Base rules in `rules` always apply. Locale-scoped rules in `locales` apply only when writing copy for the matching locale — they never conflict with each other because each locale is a separate scope.
 
 ## CLI commands
 
@@ -115,8 +134,9 @@ Syncs rules from the platform into spec files.
 1. Discovers all `.ditto.md` files under configured roots
 2. Fetches style guides from `GET /v2/styleguides`
 3. Flattens rules and wordlist entries across all guides (or only those named in `styleguides` config)
-4. Matches rules to specs by tag intersection (client-side)
-5. Rewrites the `rules` key in each file's YAML frontmatter
+4. Separates base rules from locale-scoped rules (included when `locales` is configured)
+5. Matches rules to specs by tag intersection (client-side)
+6. Rewrites the `rules` and `locales` keys in each file's YAML frontmatter
 
 Use `--dry-run` to see what would change without writing.
 
@@ -146,6 +166,7 @@ Create `dittospec.config.json` at your repo root (or any ancestor directory):
 | `workspaceId` | Your workspace ID |
 | `roots` | Repo-relative directories to search for `.ditto.md` files. Defaults to `["."]`. |
 | `styleguides` | Optional list of style guide names to pull. Defaults to all. |
+| `locales` | Optional list of locale codes (e.g. `["de-DE", "fr-FR"]`). Includes locale-scoped style guides matching these codes. Base (no-variant) guides are always included. |
 
 Set `DITTO_API_KEY` in your environment or in a `.env` file at the repo root.
 
@@ -161,6 +182,7 @@ When writing or editing user-facing text for a component:
    - **Style rules** have `name`, `description`, and optional `examples` (before/after pairs). Use `examples` as concrete tone/shape guidance.
    - **Terminology entries** have `term` and `disallowed`. Always use the `term` form; never use any of the `disallowed` alternatives.
 6. Each rule carries `styleguide` and `section` metadata indicating its source on the platform.
+7. If a `locales` key is present, it contains locale-scoped rules keyed by locale code (e.g. `de-DE`). When writing copy for a specific locale, follow the matching `locales.<code>` rules **in addition to** the base `rules`. When writing for the default/base locale, only follow `rules`. Locale-scoped rules never conflict — each locale is a separate boundary.
 
 ### Creating specs
 

package/dist/api.d.ts

@@ -34,6 +34,7 @@ export type FlatRule = {
     kind: "style";
     styleguide: string;
     section: string;
+    localeCode: string | null;
     name: string;
     description: string;
     examples: {
@@ -45,6 +46,7 @@ export type FlatRule = {
     kind: "wordlist";
     styleguide: string;
     section: string;
+    localeCode: string | null;
     term: string;
     disallowed: string[];
     description: string;

package/dist/api.js

@@ -3,7 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.DittoApi = void 0;
 exports.flattenStyleguides = flattenStyleguides;
 function flattenStyleguides(guides, filter) {
-    const selected = filter ? guides.filter((g) => filter.includes(g.name)) : guides;
+    const selected = filter?.length ? guides.filter((g) => filter.includes(g.name)) : guides;
     const result = [];
     for (const guide of selected) {
         for (const section of guide.sections) {
@@ -13,6 +13,7 @@ function flattenStyleguides(guides, filter) {
                         kind: "style",
                         styleguide: guide.name,
                         section: section.name,
+                        localeCode: guide.variant?.localeCode ?? null,
                         name: rule.name,
                         description: rule.description,
                         examples: rule.examples,
@@ -26,6 +27,7 @@ function flattenStyleguides(guides, filter) {
                         kind: "wordlist",
                         styleguide: guide.name,
                         section: section.name,
+                        localeCode: guide.variant?.localeCode ?? null,
                         term: entry.term,
                         disallowed: entry.disallowed,
                         description: entry.description,

package/dist/commands/init.js

@@ -44,6 +44,7 @@ When writing or editing text props for a component:
 4. Follow all rules in the ${c("rules")} key. Rules without a ${c("surface")} field apply to every surface; rules with ${c("surface")} apply only to that surface.
 5. Rules come in two shapes: style rules (${c("name")}, ${c("description")}, ${c("examples")}) and terminology entries (${c("term")}, ${c("disallowed")}). For terminology entries, always use the ${c("term")} form and never use the ${c("disallowed")} alternatives.
 6. Each rule carries ${c("styleguide")} and ${c("section")} metadata indicating its source.
+7. If a ${c("locales")} key is present, it contains locale-scoped rules keyed by locale code. When writing copy for a specific locale, follow the matching locale's rules in addition to the base ${c("rules")}. When writing for the default locale, only follow ${c("rules")}.
 
 ${h3} Creating specs
 

package/dist/commands/pull.js

@@ -46,52 +46,63 @@ async function pull(opts = {}) {
     }
     const guides = await api.getStyleguides();
     const allRules = (0, api_1.flattenStyleguides)(guides, config.styleguides);
-    console.log(`Fetched ${allRules.length} rule${allRules.length === 1 ? "" : "s"} from ${guides.length} style guide(s).`);
-    const platformTags = [...new Set(allRules.flatMap((r) => r.tags))].filter(Boolean).sort();
+    const baseRules = allRules.filter((r) => r.localeCode === null);
+    const configuredLocales = config.locales ?? [];
+    const localeRules = configuredLocales.length > 0
+        ? allRules.filter((r) => r.localeCode !== null && configuredLocales.includes(r.localeCode))
+        : [];
+    const localeGroups = groupByLocale(localeRules);
+    const activeRules = [...baseRules, ...localeRules];
+    console.log(`Fetched ${activeRules.length} rule${activeRules.length === 1 ? "" : "s"} from ${guides.length} style guide(s).`);
+    const platformTags = [...new Set(activeRules.flatMap((r) => r.tags))].filter(Boolean).sort();
     let written = 0;
     let unchanged = 0;
     if (workspaceFiles.length === 1) {
         const { file, parsed } = workspaceFiles[0];
-        const universalRules = allRules.filter((r) => r.tags.length === 0).map(toRuleObj);
-        if (rulesMatch(parsed.spec.rules, universalRules) && tagsMatch(parsed.spec.tags, platformTags)) {
+        const universalBaseRules = baseRules.filter((r) => r.tags.length === 0).map(toRuleObj);
+        const universalLocales = {};
+        for (const [code, rules] of localeGroups) {
+            const universal = rules.filter((r) => r.tags.length === 0).map(toRuleObj);
+            if (universal.length > 0)
+                universalLocales[code] = universal;
+        }
+        if (jsonMatch(parsed.spec.rules, universalBaseRules) &&
+            jsonMatch(parsed.spec.tags, platformTags) &&
+            jsonMatch(parsed.spec.locales, Object.keys(universalLocales).length > 0 ? universalLocales : undefined)) {
             unchanged++;
         }
         else if (opts.dryRun) {
-            console.log(`~ ${path_1.default.relative(root, file.abs)} (would write ${universalRules.length} workspace rule(s), ${platformTags.length} tag(s))`);
+            console.log(`~ ${path_1.default.relative(root, file.abs)} (would write ${universalBaseRules.length} workspace rule(s), ${platformTags.length} tag(s), ${Object.keys(universalLocales).length} locale(s))`);
         }
         else {
-            (0, serialize_1.rewriteManagedKeys)(file.abs, { tags: platformTags, rules: universalRules });
+            (0, serialize_1.rewriteManagedKeys)(file.abs, { tags: platformTags, rules: universalBaseRules, locales: universalLocales });
             written++;
-            console.log(`✓ ${path_1.default.relative(root, file.abs)} — ${universalRules.length} workspace rule(s), ${platformTags.length} tag(s)`);
+            console.log(`✓ ${path_1.default.relative(root, file.abs)} — ${universalBaseRules.length} workspace rule(s), ${platformTags.length} tag(s), ${Object.keys(universalLocales).length} locale(s)`);
         }
     }
     for (const { file, parsed } of componentFiles) {
         const specLike = parsed.spec;
         const componentTags = specLike.tags ?? [];
         const surfaces = specLike.surfaces ?? {};
-        const componentMatches = rulesForTags(allRules, componentTags);
-        const consumed = new Set(componentMatches);
-        const matchedRules = [];
-        for (const rule of componentMatches) {
-            matchedRules.push(toRuleObj(rule));
-        }
-        for (const [surfaceKey, surface] of Object.entries(surfaces)) {
-            const matches = rulesForTags(allRules, surface.tags ?? []).filter((r) => !consumed.has(r));
-            for (const rule of matches) {
-                matchedRules.push(toSurfaceRuleObj(surfaceKey, rule));
-            }
+        const matchedBaseRules = matchRulesForSpec(baseRules, componentTags, surfaces);
+        const matchedLocales = {};
+        for (const [code, rules] of localeGroups) {
+            const matched = matchRulesForSpec(rules, componentTags, surfaces);
+            if (matched.length > 0)
+                matchedLocales[code] = matched;
         }
-        if (rulesMatch(parsed.spec.rules, matchedRules)) {
+        if (jsonMatch(parsed.spec.rules, matchedBaseRules) &&
+            jsonMatch(parsed.spec.locales, Object.keys(matchedLocales).length > 0 ? matchedLocales : undefined)) {
             unchanged++;
             continue;
         }
         if (opts.dryRun) {
-            console.log(`~ ${path_1.default.relative(root, file.abs)} (would write ${matchedRules.length} rule(s))`);
+            console.log(`~ ${path_1.default.relative(root, file.abs)} (would write ${matchedBaseRules.length} rule(s), ${Object.keys(matchedLocales).length} locale(s))`);
             continue;
         }
-        (0, serialize_1.rewriteManagedKeys)(file.abs, { rules: matchedRules });
+        (0, serialize_1.rewriteManagedKeys)(file.abs, { rules: matchedBaseRules, locales: matchedLocales });
         written++;
-        console.log(`✓ ${path_1.default.relative(root, file.abs)} — ${matchedRules.length} rule(s)`);
+        console.log(`✓ ${path_1.default.relative(root, file.abs)} — ${matchedBaseRules.length} rule(s), ${Object.keys(matchedLocales).length} locale(s)`);
     }
     console.log(`\nDone. ${written} updated, ${unchanged} unchanged.`);
     if (failed > 0) {
@@ -99,6 +110,31 @@ async function pull(opts = {}) {
         process.exit(1);
     }
 }
+function matchRulesForSpec(rules, componentTags, surfaces) {
+    const componentMatches = rulesForTags(rules, componentTags);
+    const consumed = new Set(componentMatches);
+    const matched = [];
+    for (const rule of componentMatches) {
+        matched.push(toRuleObj(rule));
+    }
+    for (const [surfaceKey, surface] of Object.entries(surfaces)) {
+        const surfaceMatches = rulesForTags(rules, surface.tags ?? []).filter((r) => !consumed.has(r));
+        for (const rule of surfaceMatches) {
+            matched.push(toSurfaceRuleObj(surfaceKey, rule));
+        }
+    }
+    return matched;
+}
+function groupByLocale(rules) {
+    const groups = new Map();
+    for (const rule of rules) {
+        const code = rule.localeCode;
+        if (!groups.has(code))
+            groups.set(code, []);
+        groups.get(code).push(rule);
+    }
+    return groups;
+}
 function rulesForTags(rules, tags) {
     if (tags.length === 0)
         return [];
@@ -115,7 +151,8 @@ function toRuleObj(rule) {
     }
     else {
         out.name = rule.name;
-        out.description = rule.description;
+        if (rule.description)
+            out.description = rule.description;
         if (rule.examples.length > 0) {
             out.examples = rule.examples.map((ex) => ({ from: ex.from, to: ex.to }));
         }
@@ -127,9 +164,6 @@ function toRuleObj(rule) {
 function toSurfaceRuleObj(surface, rule) {
     return { surface, ...toRuleObj(rule) };
 }
-function rulesMatch(existing, incoming) {
-    return JSON.stringify(existing ?? []) === JSON.stringify(incoming);
-}
-function tagsMatch(existing, incoming) {
-    return JSON.stringify(existing ?? []) === JSON.stringify(incoming);
+function jsonMatch(existing, incoming) {
+    return JSON.stringify(existing ?? undefined) === JSON.stringify(incoming ?? undefined);
 }

package/dist/config.d.ts

@@ -3,6 +3,7 @@ export interface Config {
     workspaceId: string;
     roots?: string[];
     styleguides?: string[];
+    locales?: string[];
 }
 export declare class ConfigNotFoundError extends Error {
     constructor(cwd: string);

package/dist/config.js

@@ -61,6 +61,13 @@ function validate(c, source) {
             throw new Error(`${source}: every entry in "styleguides" must be a string.`);
         }
     }
+    if (obj.locales !== undefined) {
+        if (!Array.isArray(obj.locales))
+            throw new Error(`${source}: "locales" must be an array of strings if present.`);
+        if (obj.locales.some((l) => typeof l !== "string")) {
+            throw new Error(`${source}: every entry in "locales" must be a string.`);
+        }
+    }
 }
 function getApiKey() {
     try {

package/dist/serialize.d.ts

@@ -1,4 +1,5 @@
 export declare function rewriteManagedKeys(filePath: string, updates: {
     tags?: string[];
     rules?: unknown[];
+    locales?: Record<string, unknown[]>;
 }): void;

package/dist/serialize.js

@@ -14,12 +14,29 @@ function rewriteManagedKeys(filePath, updates) {
     const spec = js_yaml_1.default.load(frontmatterYaml);
     if (updates.tags !== undefined) {
         const savedRules = spec.rules;
+        const savedLocales = spec.locales;
         delete spec.rules;
+        delete spec.locales;
         spec.tags = updates.tags;
         spec.rules = savedRules;
+        if (savedLocales !== undefined)
+            spec.locales = savedLocales;
     }
-    if (updates.rules !== undefined)
+    if (updates.rules !== undefined) {
+        const savedLocales = spec.locales;
+        delete spec.locales;
         spec.rules = updates.rules;
+        if (savedLocales !== undefined)
+            spec.locales = savedLocales;
+    }
+    if (updates.locales !== undefined) {
+        if (Object.keys(updates.locales).length > 0) {
+            spec.locales = updates.locales;
+        }
+        else {
+            delete spec.locales;
+        }
+    }
     let dumped = js_yaml_1.default
         .dump(spec, {
         lineWidth: -1,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dittowords/spec-cli",
-  "version": "0.0.1-alpha.7",
+  "version": "0.0.1-alpha.8",
   "description": "CLI for syncing .ditto.md content specs with the Ditto platform.",
   "main": "dist/cli.js",
   "bin": {