@mxml3gend/gloss 0.1.0 → 0.1.2

package/README.md

@@ -35,6 +35,11 @@ export default {
   defaultLocale: "en",
   path: "src/i18n",
   format: "json",
+  scan: {
+    include: ["src/**/*.{ts,tsx,js,jsx}"],
+    exclude: ["**/*.test.tsx"],
+    mode: "regex", // or "ast" for strict parsing
+  },
 };
 ```
 
@@ -46,6 +51,9 @@ module.exports = {
   defaultLocale: "en",
   path: "src/i18n",
   format: "json",
+  scan: {
+    mode: "ast",
+  },
 };
 ```
 
@@ -56,4 +64,48 @@ gloss --help
 gloss --version
 gloss --no-open
 gloss --port 5179
+gloss open key auth.login.title
+```
+
+## CI Guardrails
+
+Run project checks for missing/orphan/invalid keys, placeholder mismatches, and potential hardcoded UI text:
+
+```bash
+gloss check
+```
+
+Machine-readable output:
+
+```bash
+gloss check --format json
+gloss check --format both
+```
+
+`gloss check` exits with code `1` when issues are found, so it is CI-friendly.
+
+The local UI also consumes this data through `/api/check` and shows a hardcoded-text status chip.
+
+## Typed Key Generation
+
+Generate `i18n-keys.d.ts` from current translation keys:
+
+```bash
+gloss gen-types
+```
+
+Use the generated `I18nKey` type in your app's `t(...)` signature to get key autocomplete while typing.
+
+Custom output path:
+
+```bash
+gloss gen-types --out src/types/i18n-keys.d.ts
+```
+
+## Deep-Link Open
+
+Open Gloss directly focused on a key:
+
+```bash
+gloss open key auth.login.title
 ```

package/dist/check.js

@@ -0,0 +1,382 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { readAllTranslations } from "./fs.js";
+import { createScanMatcher } from "./scanFilters.js";
+import { flattenObject } from "./translationTree.js";
+import { getInvalidTranslationKeyReason, isLikelyTranslationKey, } from "./translationKeys.js";
+import { inferUsageRoot, scanUsage } from "./usageScanner.js";
+const HARDCODED_IGNORED_DIRECTORIES = new Set([
+    "node_modules",
+    ".git",
+    ".next",
+    ".nuxt",
+    ".turbo",
+    "dist",
+    "build",
+    "coverage",
+    "out",
+    "storybook-static",
+]);
+const HARDCODED_EXTENSIONS = new Set([".tsx", ".jsx"]);
+const JSX_TEXT_REGEX = />\s*([A-Za-z][A-Za-z0-9 .,!?'’"’-]{1,})\s*</g;
+const JSX_ATTRIBUTE_REGEX = /\b(?:title|label|placeholder|alt|aria-label|helperText|tooltip|description)\s*=\s*["'`]([^"'`]+)["'`]/g;
+const SIMPLE_PLACEHOLDER_REGEX = /\{([A-Za-z_][A-Za-z0-9_]*)\}/g;
+const ICU_PLACEHOLDER_REGEX = /\{([A-Za-z_][A-Za-z0-9_]*)\s*,\s*(plural|select|selectordinal)\s*,/g;
+const ICU_PLURAL_START_REGEX = /\{([A-Za-z_][A-Za-z0-9_]*)\s*,\s*plural\s*,/g;
+const ICU_CATEGORY_REGEX = /(?:^|[\s,])(=?\d+|zero|one|two|few|many|other)\s*\{/g;
+const projectRoot = () => process.env.INIT_CWD || process.cwd();
+const normalizePath = (filePath) => filePath.split(path.sep).join("/");
+const withCollapsedWhitespace = (value) => value.replace(/\s+/g, " ").trim();
+const lineNumberAtIndex = (source, index) => {
+    let line = 1;
+    for (let cursor = 0; cursor < index; cursor += 1) {
+        if (source.charCodeAt(cursor) === 10) {
+            line += 1;
+        }
+    }
+    return line;
+};
+const hasIgnoredPathSegment = (relativePath) => normalizePath(relativePath)
+    .split("/")
+    .some((segment) => HARDCODED_IGNORED_DIRECTORIES.has(segment));
+const isLikelyHardcodedText = (value) => {
+    const text = withCollapsedWhitespace(value);
+    if (text.length < 3) {
+        return false;
+    }
+    if (!/[A-Za-z]/.test(text)) {
+        return false;
+    }
+    // Ignore values that clearly look like i18n keys, but keep plain words
+    // like "test" or "Save" so hardcoded UI text is still detected.
+    if (isLikelyTranslationKey(text) && /[.:/]/.test(text)) {
+        return false;
+    }
+    if (/^(true|false|null|undefined)$/i.test(text)) {
+        return false;
+    }
+    if (/^(https?:|\/|#)/i.test(text)) {
+        return false;
+    }
+    if (/[=;(){}|]|=>/.test(text)) {
+        return false;
+    }
+    if (/\b(?:return|const|let|var|function|import|export)\b/.test(text)) {
+        return false;
+    }
+    if (/\b(?:void|promise|string|number|boolean|record|unknown|any|extends|infer)\b/i.test(text)) {
+        return false;
+    }
+    return true;
+};
+const flattenByLocale = (cfg, data) => {
+    const result = {};
+    for (const locale of cfg.locales) {
+        const tree = data[locale] ?? {};
+        result[locale] = flattenObject(tree);
+    }
+    return result;
+};
+const uniqueSorted = (items) => Array.from(new Set(items)).sort((left, right) => left.localeCompare(right));
+const asComparable = (items) => items.join("\u0000");
+const findMatchingBraceEnd = (value, startIndex) => {
+    let depth = 0;
+    for (let index = startIndex; index < value.length; index += 1) {
+        const char = value[index];
+        if (char === "{") {
+            depth += 1;
+        }
+        else if (char === "}") {
+            depth -= 1;
+            if (depth === 0) {
+                return index;
+            }
+        }
+    }
+    return -1;
+};
+const extractPlaceholders = (value) => {
+    const placeholders = new Set();
+    let match = SIMPLE_PLACEHOLDER_REGEX.exec(value);
+    while (match) {
+        placeholders.add(match[1]);
+        match = SIMPLE_PLACEHOLDER_REGEX.exec(value);
+    }
+    SIMPLE_PLACEHOLDER_REGEX.lastIndex = 0;
+    match = ICU_PLACEHOLDER_REGEX.exec(value);
+    while (match) {
+        placeholders.add(match[1]);
+        match = ICU_PLACEHOLDER_REGEX.exec(value);
+    }
+    ICU_PLACEHOLDER_REGEX.lastIndex = 0;
+    return uniqueSorted(placeholders);
+};
+const extractPluralCategories = (value) => {
+    const categoriesByVariable = new Map();
+    let match = ICU_PLURAL_START_REGEX.exec(value);
+    while (match) {
+        const variable = match[1];
+        const startIndex = match.index;
+        const endIndex = findMatchingBraceEnd(value, startIndex);
+        if (endIndex === -1) {
+            match = ICU_PLURAL_START_REGEX.exec(value);
+            continue;
+        }
+        const block = value.slice(startIndex, endIndex + 1);
+        const categories = categoriesByVariable.get(variable) ?? new Set();
+        let categoryMatch = ICU_CATEGORY_REGEX.exec(block);
+        while (categoryMatch) {
+            categories.add(categoryMatch[1]);
+            categoryMatch = ICU_CATEGORY_REGEX.exec(block);
+        }
+        ICU_CATEGORY_REGEX.lastIndex = 0;
+        categoriesByVariable.set(variable, categories);
+        ICU_PLURAL_START_REGEX.lastIndex = endIndex + 1;
+        match = ICU_PLURAL_START_REGEX.exec(value);
+    }
+    ICU_PLURAL_START_REGEX.lastIndex = 0;
+    return new Map(Array.from(categoriesByVariable.entries()).map(([variable, categories]) => [
+        variable,
+        uniqueSorted(categories),
+    ]));
+};
+const scanHardcodedText = async (rootDir, cfg) => {
+    const issues = [];
+    const seen = new Set();
+    const shouldScanFile = createScanMatcher(cfg.scan);
+    const visitDirectory = async (directory) => {
+        const entries = await fs.readdir(directory, { withFileTypes: true });
+        for (const entry of entries) {
+            const fullPath = path.join(directory, entry.name);
+            if (entry.isDirectory()) {
+                if (entry.name.startsWith(".") ||
+                    HARDCODED_IGNORED_DIRECTORIES.has(entry.name)) {
+                    continue;
+                }
+                await visitDirectory(fullPath);
+                continue;
+            }
+            if (!entry.isFile() || !HARDCODED_EXTENSIONS.has(path.extname(entry.name))) {
+                continue;
+            }
+            const relativePath = normalizePath(path.relative(rootDir, fullPath));
+            if (hasIgnoredPathSegment(relativePath) || !shouldScanFile(relativePath)) {
+                continue;
+            }
+            const source = await fs.readFile(fullPath, "utf8");
+            let textMatch = JSX_TEXT_REGEX.exec(source);
+            while (textMatch) {
+                const text = withCollapsedWhitespace(textMatch[1]);
+                if (isLikelyHardcodedText(text)) {
+                    const line = lineNumberAtIndex(source, textMatch.index);
+                    const dedupeKey = `${relativePath}:${line}:jsx_text:${text}`;
+                    if (!seen.has(dedupeKey)) {
+                        seen.add(dedupeKey);
+                        issues.push({ file: relativePath, line, kind: "jsx_text", text });
+                    }
+                }
+                textMatch = JSX_TEXT_REGEX.exec(source);
+            }
+            JSX_TEXT_REGEX.lastIndex = 0;
+            let attrMatch = JSX_ATTRIBUTE_REGEX.exec(source);
+            while (attrMatch) {
+                const text = withCollapsedWhitespace(attrMatch[1]);
+                if (isLikelyHardcodedText(text)) {
+                    const line = lineNumberAtIndex(source, attrMatch.index);
+                    const dedupeKey = `${relativePath}:${line}:jsx_attribute:${text}`;
+                    if (!seen.has(dedupeKey)) {
+                        seen.add(dedupeKey);
+                        issues.push({ file: relativePath, line, kind: "jsx_attribute", text });
+                    }
+                }
+                attrMatch = JSX_ATTRIBUTE_REGEX.exec(source);
+            }
+            JSX_ATTRIBUTE_REGEX.lastIndex = 0;
+        }
+    };
+    await visitDirectory(rootDir);
+    issues.sort((left, right) => {
+        if (left.file !== right.file) {
+            return left.file.localeCompare(right.file);
+        }
+        if (left.line !== right.line) {
+            return left.line - right.line;
+        }
+        return left.text.localeCompare(right.text);
+    });
+    return issues;
+};
+export async function runGlossCheck(cfg) {
+    const rootDir = projectRoot();
+    const data = (await readAllTranslations(cfg));
+    const flatByLocale = flattenByLocale(cfg, data);
+    const usageRoot = inferUsageRoot(cfg);
+    const usage = await scanUsage(usageRoot, cfg.scan);
+    const usageKeys = new Set(Object.keys(usage));
+    const translationKeys = new Set(cfg.locales.flatMap((locale) => Object.keys(flatByLocale[locale] ?? {})));
+    const allKeys = uniqueSorted([...translationKeys, ...usageKeys]);
+    const missingTranslations = [];
+    for (const key of allKeys) {
+        const missingLocales = cfg.locales.filter((locale) => {
+            const value = flatByLocale[locale]?.[key];
+            return value === undefined || value.trim() === "";
+        });
+        if (missingLocales.length > 0) {
+            missingTranslations.push({
+                key,
+                missingLocales,
+                usedInCode: usageKeys.has(key),
+            });
+        }
+    }
+    const orphanKeys = [];
+    for (const key of translationKeys) {
+        if (usageKeys.has(key)) {
+            continue;
+        }
+        const localesWithValue = cfg.locales.filter((locale) => {
+            const value = flatByLocale[locale]?.[key];
+            return value !== undefined && value.trim() !== "";
+        });
+        orphanKeys.push({ key, localesWithValue });
+    }
+    const invalidKeys = [];
+    for (const key of translationKeys) {
+        const reason = getInvalidTranslationKeyReason(key);
+        if (reason) {
+            invalidKeys.push({ key, reason });
+        }
+    }
+    const placeholderMismatches = [];
+    for (const key of translationKeys) {
+        const localesWithValue = cfg.locales.filter((locale) => {
+            const value = flatByLocale[locale]?.[key];
+            return value !== undefined && value.trim() !== "";
+        });
+        if (localesWithValue.length <= 1) {
+            continue;
+        }
+        const referenceLocale = localesWithValue.includes(cfg.defaultLocale)
+            ? cfg.defaultLocale
+            : localesWithValue[0];
+        const referenceValue = flatByLocale[referenceLocale][key];
+        const expectedPlaceholders = extractPlaceholders(referenceValue);
+        const expectedPluralByVariable = extractPluralCategories(referenceValue);
+        const expectedPlaceholdersComparable = asComparable(expectedPlaceholders);
+        const mismatchedLocales = [];
+        const byLocale = {};
+        const pluralMismatches = [];
+        for (const locale of localesWithValue) {
+            const value = flatByLocale[locale][key];
+            const placeholders = extractPlaceholders(value);
+            byLocale[locale] = placeholders;
+            if (asComparable(placeholders) !== expectedPlaceholdersComparable) {
+                mismatchedLocales.push(locale);
+            }
+            const actualPluralByVariable = extractPluralCategories(value);
+            const pluralVariables = uniqueSorted([
+                ...expectedPluralByVariable.keys(),
+                ...actualPluralByVariable.keys(),
+            ]);
+            for (const variable of pluralVariables) {
+                const expectedCategories = expectedPluralByVariable.get(variable) ?? [];
+                const actualCategories = actualPluralByVariable.get(variable) ?? [];
+                if (asComparable(expectedCategories) !== asComparable(actualCategories)) {
+                    pluralMismatches.push({
+                        locale,
+                        variable,
+                        expectedCategories,
+                        actualCategories,
+                    });
+                }
+            }
+        }
+        if (mismatchedLocales.length > 0 || pluralMismatches.length > 0) {
+            placeholderMismatches.push({
+                key,
+                referenceLocale,
+                expectedPlaceholders,
+                byLocale,
+                mismatchedLocales: uniqueSorted(mismatchedLocales),
+                pluralMismatches,
+            });
+        }
+    }
+    const hardcodedTexts = await scanHardcodedText(usageRoot, cfg);
+    const summary = {
+        missingTranslations: missingTranslations.length,
+        orphanKeys: orphanKeys.length,
+        invalidKeys: invalidKeys.length,
+        placeholderMismatches: placeholderMismatches.length,
+        hardcodedTexts: hardcodedTexts.length,
+        totalIssues: missingTranslations.length +
+            orphanKeys.length +
+            invalidKeys.length +
+            placeholderMismatches.length +
+            hardcodedTexts.length,
+    };
+    return {
+        ok: summary.totalIssues === 0,
+        generatedAt: new Date().toISOString(),
+        rootDir: rootDir,
+        locales: cfg.locales,
+        summary,
+        missingTranslations,
+        orphanKeys,
+        invalidKeys,
+        placeholderMismatches,
+        hardcodedTexts,
+    };
+}
+const printTable = (rows) => {
+    const labelWidth = Math.max(...rows.map((row) => row.label.length));
+    console.log("");
+    for (const row of rows) {
+        console.log(`${row.label.padEnd(labelWidth)} : ${row.value}`);
+    }
+};
+const printSample = (title, lines) => {
+    console.log(`\n${title} (${lines.length})`);
+    const limit = 12;
+    for (const line of lines.slice(0, limit)) {
+        console.log(`- ${line}`);
+    }
+    if (lines.length > limit) {
+        console.log(`- ... +${lines.length - limit} more`);
+    }
+};
+export const printGlossCheck = (result, format) => {
+    if (format === "human" || format === "both") {
+        console.log(`Gloss check for ${result.rootDir}`);
+        printTable([
+            { label: "Missing translations", value: result.summary.missingTranslations },
+            { label: "Orphan keys", value: result.summary.orphanKeys },
+            { label: "Invalid keys", value: result.summary.invalidKeys },
+            {
+                label: "Placeholder mismatches",
+                value: result.summary.placeholderMismatches,
+            },
+            { label: "Hardcoded text candidates", value: result.summary.hardcodedTexts },
+            { label: "Total issues", value: result.summary.totalIssues },
+        ]);
+        printSample("Missing translations", result.missingTranslations.map((issue) => `${issue.key} -> missing in [${issue.missingLocales.join(", ")}]${issue.usedInCode ? " (used)" : ""}`));
+        printSample("Orphan keys", result.orphanKeys.map((issue) => `${issue.key} -> present in [${issue.localesWithValue.join(", ")}]`));
+        printSample("Invalid keys", result.invalidKeys.map((issue) => `${issue.key} -> ${issue.reason}`));
+        printSample("Placeholder mismatches", result.placeholderMismatches.map((issue) => {
+            const pluralInfo = issue.pluralMismatches.length > 0
+                ? `; plural mismatches: ${issue.pluralMismatches.length}`
+                : "";
+            return `${issue.key} -> expected [${issue.expectedPlaceholders.join(", ")}] from ${issue.referenceLocale}; locales: [${issue.mismatchedLocales.join(", ")}]${pluralInfo}`;
+        }));
+        printSample("Hardcoded text candidates", result.hardcodedTexts.map((issue) => `${issue.file}:${issue.line} [${issue.kind}] ${issue.text}`));
+        console.log(result.ok
+            ? "\nResult: PASS"
+            : "\nResult: FAIL (non-zero exit code for CI guardrails)");
+    }
+    if (format === "json" || format === "both") {
+        if (format === "both") {
+            console.log("\nJSON output:");
+        }
+        console.log(JSON.stringify(result, null, 2));
+    }
+};

package/dist/config.js

@@ -27,10 +27,11 @@ const normalizeScanConfig = (value) => {
     const scan = value;
     const include = normalizeScanPatterns(scan.include);
     const exclude = normalizeScanPatterns(scan.exclude);
-    if (!include && !exclude) {
+    const mode = scan.mode === "regex" || scan.mode === "ast" ? scan.mode : undefined;
+    if (!include && !exclude && !mode) {
         return undefined;
     }
-    return { include, exclude };
+    return { include, exclude, mode };
 };
 const CONFIG_FILE_NAMES = [
     "gloss.config.ts",
@@ -39,6 +40,37 @@ const CONFIG_FILE_NAMES = [
     "gloss.config.mjs",
     "gloss.config.cjs",
 ];
+const LOCALE_CODE_PATTERN = /^[A-Za-z]{2,3}(?:[-_][A-Za-z0-9]{2,8})*$/;
+const AUTO_DISCOVERY_IGNORED_DIRECTORIES = new Set([
+    "node_modules",
+    ".git",
+    ".next",
+    ".nuxt",
+    ".turbo",
+    "dist",
+    "build",
+    "coverage",
+    "out",
+]);
+const DIRECTORY_NAME_SCORES = new Map([
+    ["i18n", 80],
+    ["locales", 80],
+    ["locale", 60],
+    ["translations", 55],
+    ["translation", 45],
+    ["lang", 35],
+    ["langs", 35],
+    ["messages", 25],
+]);
+const normalizePath = (filePath) => filePath.split(path.sep).join("/").replace(/^\.\//, "");
+const isLikelyLocaleCode = (value) => LOCALE_CODE_PATTERN.test(value);
+const scoreDirectoryName = (directoryPath) => {
+    const segments = normalizePath(directoryPath).split("/");
+    return segments.reduce((score, segment) => {
+        const nextScore = DIRECTORY_NAME_SCORES.get(segment.toLowerCase());
+        return score + (nextScore ?? 0);
+    }, 0);
+};
 const resolveLocalesDirectory = (cwd, localesPath) => {
     if (path.isAbsolute(localesPath)) {
         return localesPath;
@@ -49,9 +81,13 @@ const discoverLocales = async (cwd, localesPath) => {
     const directory = resolveLocalesDirectory(cwd, localesPath);
     try {
         const entries = await fs.readdir(directory, { withFileTypes: true });
-        return entries
+        const localeCandidates = entries
             .filter((entry) => entry.isFile() && entry.name.endsWith(".json"))
             .map((entry) => path.basename(entry.name, ".json").trim())
+            .filter((entry) => entry.length > 0);
+        const likelyLocales = localeCandidates.filter(isLikelyLocaleCode);
+        const localesToUse = likelyLocales.length > 0 ? likelyLocales : localeCandidates;
+        return localesToUse
             .filter((entry) => entry.length > 0)
             .sort((a, b) => a.localeCompare(b));
     }
@@ -59,6 +95,80 @@ const discoverLocales = async (cwd, localesPath) => {
         return [];
     }
 };
+const discoverLocaleDirectoryCandidates = async (cwd) => {
+    const candidates = [];
+    const visit = async (directory) => {
+        const entries = await fs.readdir(directory, { withFileTypes: true });
+        const directoryLocales = entries
+            .filter((entry) => entry.isFile() && entry.name.endsWith(".json"))
+            .map((entry) => path.basename(entry.name, ".json").trim())
+            .filter((entry) => isLikelyLocaleCode(entry));
+        if (directoryLocales.length > 0) {
+            const normalizedDirectory = normalizePath(path.relative(cwd, directory));
+            const uniqueLocales = Array.from(new Set(directoryLocales)).sort((a, b) => a.localeCompare(b));
+            const depth = normalizedDirectory.length === 0
+                ? 0
+                : normalizedDirectory.split("/").length;
+            candidates.push({
+                directoryPath: directory,
+                locales: uniqueLocales,
+                depth,
+            });
+        }
+        for (const entry of entries) {
+            if (!entry.isDirectory()) {
+                continue;
+            }
+            if (entry.name.startsWith(".") ||
+                AUTO_DISCOVERY_IGNORED_DIRECTORIES.has(entry.name)) {
+                continue;
+            }
+            await visit(path.join(directory, entry.name));
+        }
+    };
+    await visit(cwd);
+    return candidates;
+};
+const selectLocaleDirectoryCandidate = (candidates, preferredLocales) => {
+    const scored = candidates.map((candidate) => {
+        const localeMatches = preferredLocales.filter((locale) => candidate.locales.includes(locale));
+        const allPreferredMatch = preferredLocales.length > 0 &&
+            preferredLocales.every((locale) => candidate.locales.includes(locale));
+        const directoryNameScore = scoreDirectoryName(candidate.directoryPath);
+        const srcHintScore = normalizePath(candidate.directoryPath).includes("/src/")
+            ? 15
+            : 0;
+        const depthScore = Math.max(0, 30 - candidate.depth * 3);
+        const localeCountScore = candidate.locales.length * 10;
+        const preferredScore = localeMatches.length * 25 + (allPreferredMatch ? 80 : 0);
+        const score = directoryNameScore +
+            srcHintScore +
+            depthScore +
+            localeCountScore +
+            preferredScore;
+        return { candidate, score };
+    });
+    scored.sort((left, right) => {
+        if (left.score !== right.score) {
+            return right.score - left.score;
+        }
+        if (left.candidate.depth !== right.candidate.depth) {
+            return left.candidate.depth - right.candidate.depth;
+        }
+        return left.candidate.directoryPath.localeCompare(right.candidate.directoryPath);
+    });
+    return scored[0]?.candidate;
+};
+const resolveDiscoveredPath = (cwd, directoryPath) => {
+    const relative = path.relative(cwd, directoryPath);
+    if (!relative || relative === ".") {
+        return ".";
+    }
+    if (!relative.startsWith("..") && !path.isAbsolute(relative)) {
+        return normalizePath(relative);
+    }
+    return directoryPath;
+};
 const resolveConfigPath = async (cwd) => {
     for (const fileName of CONFIG_FILE_NAMES) {
         const candidatePath = path.join(cwd, fileName);
@@ -93,10 +203,10 @@ export async function loadGlossConfig() {
         if (!cfg || typeof cfg !== "object") {
             throw new GlossConfigError("INVALID_CONFIG", "Default export must be a config object.");
         }
-        if (typeof cfg.path !== "string" || !cfg.path.trim()) {
-            throw new GlossConfigError("INVALID_CONFIG", "`path` must be a non-empty string.");
+        if (cfg.path !== undefined &&
+            (typeof cfg.path !== "string" || !cfg.path.trim())) {
+            throw new GlossConfigError("INVALID_CONFIG", "`path` must be a non-empty string when provided.");
         }
-        const translationsPath = cfg.path.trim();
         if (cfg.locales !== undefined && !Array.isArray(cfg.locales)) {
             throw new GlossConfigError("INVALID_CONFIG", "`locales` must be an array of locale codes when provided.");
         }
@@ -105,16 +215,35 @@ export async function loadGlossConfig() {
                 .map((entry) => (typeof entry === "string" ? entry.trim() : ""))
                 .filter((entry) => entry.length > 0)
             : [];
+        const configuredPath = typeof cfg.path === "string" ? cfg.path.trim() : "";
+        const discoveredDirectoryCandidate = configuredPath
+            ? null
+            : selectLocaleDirectoryCandidate(await discoverLocaleDirectoryCandidates(cwd), configuredLocales);
+        const translationsPath = configuredPath
+            ? configuredPath
+            : discoveredDirectoryCandidate
+                ? resolveDiscoveredPath(cwd, discoveredDirectoryCandidate.directoryPath)
+                : "";
+        if (!translationsPath) {
+            throw new GlossConfigError("NO_LOCALES", "No locale directory found. Set `path` in config or add locale JSON files (for example `src/locales/en.json`).");
+        }
         const locales = configuredLocales.length > 0
             ? configuredLocales
-            : await discoverLocales(cwd, translationsPath);
+            : discoveredDirectoryCandidate
+                ? discoveredDirectoryCandidate.locales
+                : await discoverLocales(cwd, translationsPath);
         if (locales.length === 0) {
             throw new GlossConfigError("NO_LOCALES", `No locales found. Add "locales" in config or place *.json files in ${translationsPath}.`);
         }
-        if (typeof cfg.defaultLocale !== "string" || !cfg.defaultLocale.trim()) {
-            throw new GlossConfigError("INVALID_CONFIG", "`defaultLocale` must be a non-empty string.");
+        if (cfg.defaultLocale !== undefined &&
+            (typeof cfg.defaultLocale !== "string" || !cfg.defaultLocale.trim())) {
+            throw new GlossConfigError("INVALID_CONFIG", "`defaultLocale` must be a non-empty string when provided.");
         }
-        const defaultLocale = cfg.defaultLocale.trim();
+        const defaultLocale = typeof cfg.defaultLocale === "string" && cfg.defaultLocale.trim()
+            ? cfg.defaultLocale.trim()
+            : locales.includes("en")
+                ? "en"
+                : locales[0];
         if (!locales.includes(defaultLocale)) {
             throw new GlossConfigError("INVALID_CONFIG", "`defaultLocale` must be included in `locales`.");
         }