localewarden 0.1.1 → 0.2.0

package/dist/files.js

@@ -87,7 +87,7 @@ export function findSourceFiles(root, pattern, sourceLanguage) {
     };
     const files = [];
     for (const rel of all.sort()) {
-        if (!rel.endsWith('.json'))
+        if (!/\.(json|arb|txt)$/.test(rel))
             continue;
         const match = matcher.exec(rel);
         if (!match || match.groups?.lang !== sourceLanguage)
@@ -99,6 +99,38 @@ export function findSourceFiles(root, pattern, sourceLanguage) {
     }
     return files;
 }
+/**
+ * Key pattern -> RegExp. "*" matches within one segment, "**" any number of segments. A
+ * pattern without a dot matches the last segment anywhere ("id" matches "steps.2.id").
+ */
+export function keyPattern(pattern) {
+    const body = pattern
+        .split(/(\*\*|\*)/)
+        .map(part => (part === '**' ? '.*' : part === '*' ? '[^.]*' : escapeRegExp(part)))
+        .join('');
+    return new RegExp(pattern.includes('.') ? `^${body}$` : `(?:^|\\.)${body}$`);
+}
+/** Path pattern -> RegExp ("*" within a folder, "**" across folders, {lang} as written). */
+export function pathPattern(pattern) {
+    const body = pattern
+        .replace(/\\/g, '/')
+        .replace(/^\.\//, '')
+        .split(/(\*\*\/?|\*)/)
+        .map(part => (part.startsWith('**') ? '(?:.*/)?' : part === '*' ? '[^/]*' : escapeRegExp(part)))
+        .join('');
+    return new RegExp(`^${body}$`);
+}
+/**
+ * Values that are not text and stay as they are in every language: URLs, email addresses,
+ * file paths and plain numbers or codes without spaces.
+ */
+export function isLiteralValue(value) {
+    const v = value.trim();
+    return (/^(?:https?:\/\/|mailto:|tel:)\S+$/i.test(v) ||
+        /^[\w.+-]+@[\w-]+(?:\.[\w-]+)+$/.test(v) ||
+        /^(?:\.{0,2}\/)?[\w@.-]+(?:\/[\w@.-]+)*\.(?:png|jpe?g|gif|svg|webp|avif|ico|mp3|mp4|webm|wav|pdf|json|css|js|html?)$/i.test(v) ||
+        /^[\d\s.,:%+\-–/×x#]+$/.test(v));
+}
 export const keyOf = (segments) => segments.join('.');
 /** All string values of a parsed JSON document, in document order. */
 export function stringLeaves(value, prefix = [], out = []) {
@@ -209,6 +241,25 @@ export function detectFormat(text) {
 export function serialize(value, format) {
     return JSON.stringify(value, null, format.indent) + (format.finalNewline ? '\n' : '');
 }
+const txtKey = (rel) => path.posix.basename(rel.replace(/\\/g, '/'), '.txt');
+/**
+ * Parses a locale file. A .txt file (fastlane metadata: description.txt, keywords.txt) is one
+ * string, keyed by its file name, so maxLength patterns like "keywords" apply to it.
+ */
+export function parseDoc(rel, text) {
+    if (rel.endsWith('.txt'))
+        return { [txtKey(rel)]: text.replace(/\r?\n$/, '') };
+    return JSON.parse(text);
+}
+/** Flutter ARB metadata ("@@locale", "@title": { description, placeholders }): not text. */
+export const isArbMetadata = (rel, key) => rel.endsWith('.arb') && key.startsWith('@');
+/** Text of a locale file, or null when a .txt file has no value to write. */
+export function serializeDoc(rel, doc, format) {
+    if (!rel.endsWith('.txt'))
+        return serialize(doc, format);
+    const value = doc[txtKey(rel)];
+    return typeof value === 'string' ? value + (format.finalNewline ? '\n' : '') : null;
+}
 export function readText(file) {
     try {
         return fs.readFileSync(file, 'utf8');

package/dist/placeholders.js

@@ -6,7 +6,8 @@
 export const DEFAULT_PLACEHOLDER_PATTERNS = [
     '\\{\\{\\s*[\\w.-]+\\s*\\}\\}', // {{name}}       i18next, Handlebars, vue-i18n
     '\\{\\s*[\\w.-]+\\s*\\}', //        {name}         ICU, react-intl, i18next (custom)
-    '%(?:\\d+\\$)?[-+0#]*\\d*(?:\\.\\d+)?[sdifuxXeEgGc@]', // %s %d %1$s %.2f  printf, Android, iOS
+    // Not followed by a letter: Hungarian writes suffixes after percent signs ("100%-ig").
+    '%(?:\\d+\\$)?[-+0#]*\\d*(?:\\.\\d+)?[sdifuxXeEgGc@](?![A-Za-z\\u00C0-\\u024F])', // %s %d %1$s %.2f  printf, Android, iOS
     '%\\([\\w.-]+\\)[sdif]', //        %(name)s       Python
     '%\\{[\\w.-]+\\}', //               %{name}        Ruby, rails-i18n
     '\\$\\{[\\w.-]+\\}', //             ${name}        template literals

package/dist/project.d.ts

@@ -9,10 +9,25 @@ export interface Finding {
     text: string;
     note?: string;
 }
+/**
+ * Short sibling strings (same parent key) that differ in the source but got the same
+ * translation: answer options, tabs or menu items the user can no longer tell apart.
+ */
+export declare function collapsedSiblings(source: Map<string, string>, target: Map<string, string>): {
+    key: string;
+    note: string;
+}[];
 /**
  * Runs the quality checks over every translated string. Approved hand edits are skipped
  * except for placeholder and script errors, which break the app either way.
  */
 export declare function checkProject(config: Config, languages?: string[]): Finding[];
+/**
+ * Repairs placeholder findings that have exactly one possible fix: the source has one
+ * placeholder and the translation one brace token with another name ("{heures}" for
+ * "{hours}"). The file text is edited in place, so its formatting stays as it is.
+ * Returns the repaired findings.
+ */
+export declare function fixPlaceholders(config: Config, findings: Finding[]): Finding[];
 /** Table of finding counts per language and check. */
 export declare function summaryTable(findings: Finding[], languages: string[]): string;

package/dist/project.js

@@ -1,11 +1,46 @@
 import path from 'node:path';
 import { CHECKS, Checker, ERROR_CHECKS } from './checks.js';
-import { findSourceFiles, flatten, readText } from './files.js';
+import { findSourceFiles, flatten, isArbMetadata, parseDoc, readText, writeText } from './files.js';
 import { reviewId, State } from './state.js';
 import { hash } from './util.js';
+/**
+ * Short sibling strings (same parent key) that differ in the source but got the same
+ * translation: answer options, tabs or menu items the user can no longer tell apart.
+ */
+export function collapsedSiblings(source, target) {
+    const groups = new Map();
+    for (const key of target.keys()) {
+        // Only nested keys: in a flat file every string would be a "sibling" of every other.
+        if (!key.includes('.'))
+            continue;
+        const parent = key.slice(0, key.lastIndexOf('.'));
+        // Plural forms of one string are meant to look alike.
+        if (/_(zero|one|two|few|many|other)$/.test(key))
+            continue;
+        groups.set(parent, [...(groups.get(parent) ?? []), key]);
+    }
+    const out = [];
+    for (const keys of groups.values()) {
+        const seen = new Map();
+        for (const key of keys) {
+            const src = source.get(key)?.trim();
+            const text = target.get(key)?.trim().toLocaleLowerCase();
+            if (!src || !text || src.length > 40)
+                continue;
+            const earlier = seen.get(text);
+            if (earlier !== undefined && source.get(earlier)?.trim().toLocaleLowerCase() !== src.toLocaleLowerCase()) {
+                out.push({ key, note: `same translation as "${earlier}", although the source differs ("${source.get(earlier)}" / "${src}")` });
+            }
+            else if (earlier === undefined) {
+                seen.set(text, key);
+            }
+        }
+    }
+    return out;
+}
 function readJson(file) {
     const text = readText(file);
-    return text === null ? null : JSON.parse(text);
+    return text === null ? null : parseDoc(file, text);
 }
 /**
  * Runs the quality checks over every translated string. Approved hand edits are skipped
@@ -16,6 +51,8 @@ export function checkProject(config, languages = config.targetLanguages) {
     const state = new State(path.join(config.root, config.stateDir));
     const findings = [];
     for (const file of findSourceFiles(config.root, config.files, config.sourceLanguage)) {
+        if (checker.scope.isExcluded(file))
+            continue;
         const sourceDoc = readJson(path.join(config.root, file.pathFor(config.sourceLanguage)));
         if (sourceDoc === null)
             continue;
@@ -32,10 +69,17 @@ export function checkProject(config, languages = config.targetLanguages) {
             }
             if (doc === null)
                 continue;
-            for (const [key, text] of flatten(doc)) {
+            const translated = flatten(doc);
+            for (const { key, note } of collapsedSiblings(source, translated)) {
+                const review = state.review[reviewId(lang, file.id, key)];
+                if (review?.status === 'approved')
+                    continue;
+                findings.push({ lang, check: 'partial', severity: 'warning', file: rel, key, text: translated.get(key) ?? '', note });
+            }
+            for (const [key, text] of translated) {
                 // Plural forms only the target language has are checked against the source "_other".
                 const sourceText = source.get(key) ?? (/_(zero|one|two|few|many)$/.test(key) ? source.get(key.replace(/_(zero|one|two|few|many)$/, '_other')) : undefined);
-                if (sourceText === undefined || sourceText.trim() === '')
+                if (sourceText === undefined || sourceText.trim() === '' || isArbMetadata(rel, key) || checker.scope.isLiteral(key, sourceText))
                     continue;
                 const review = state.review[reviewId(lang, file.id, key)];
                 const approved = review?.status === 'approved' && review.valueHash === hash(text);
@@ -57,6 +101,42 @@ export function checkProject(config, languages = config.targetLanguages) {
     }
     return findings;
 }
+/**
+ * Repairs placeholder findings that have exactly one possible fix: the source has one
+ * placeholder and the translation one brace token with another name ("{heures}" for
+ * "{hours}"). The file text is edited in place, so its formatting stays as it is.
+ * Returns the repaired findings.
+ */
+export function fixPlaceholders(config, findings) {
+    const fixed = [];
+    const sources = new Map();
+    for (const file of findSourceFiles(config.root, config.files, config.sourceLanguage)) {
+        const doc = readJson(path.join(config.root, file.pathFor(config.sourceLanguage)));
+        if (doc)
+            for (const lang of config.targetLanguages)
+                sources.set(file.pathFor(lang), flatten(doc));
+    }
+    const checker = new Checker(config);
+    for (const finding of findings.filter(f => f.check === 'placeholder')) {
+        const source = sources.get(finding.file)?.get(finding.key);
+        if (source === undefined)
+            continue;
+        const expected = source.match(checker.placeholderRe) ?? [];
+        const tokens = finding.text.match(/\{\{?[^{}]+\}?\}/g) ?? [];
+        const [want, got] = [expected[0], tokens[0]];
+        if (new Set(expected).size !== 1 || tokens.length !== 1 || !want || !got || got === want)
+            continue;
+        const repaired = finding.text.replace(got, want);
+        const file = path.join(config.root, finding.file);
+        const text = readText(file);
+        const before = JSON.stringify(finding.text).slice(1, -1);
+        if (text === null || text.split(before).length !== 2)
+            continue; // not found exactly once
+        writeText(file, text.replace(before, JSON.stringify(repaired).slice(1, -1)));
+        fixed.push({ ...finding, text: repaired });
+    }
+    return fixed;
+}
 /** Table of finding counts per language and check. */
 export function summaryTable(findings, languages) {
     const header = ['lang', ...CHECKS];

package/dist/prompt.d.ts

@@ -4,6 +4,10 @@ export interface PromptItem {
     source: string;
     /** Existing translation of an older version of the source (revision mode). */
     previous?: string;
+    /** Maximum characters of the translation (store listings, SEO titles, buttons). */
+    maxLength?: number;
+    /** Set when --fix-flagged revises a translation that lost content. */
+    completing?: boolean;
 }
 /** System prompt for translating a JSON array of strings. */
 export declare function batchPrompt(config: Config, lang: string, items: PromptItem[]): string;

package/dist/prompt.js

@@ -46,17 +46,24 @@ export function batchPrompt(config, lang, items) {
     const revision = revised.length > 0
         ? ` REVISION: the source of some elements was edited after they had been translated. Their existing translation (of the older source) by 1-based position: ${JSON.stringify(Object.fromEntries(revised))}. For these elements, ${REVISION_RULE}`
         : '';
+    const limited = items.map((item, i) => (item.maxLength ? `element ${i + 1} at most ${item.maxLength}` : null)).filter(Boolean);
+    const lengths = limited.length > 0
+        ? ` LENGTH LIMIT: these elements are cut off past a character limit (counting spaces): ${limited.join(', ')} characters. Stay under it even if that means a shorter, freer phrasing; never pad.`
+        : '';
     const plural = items.some(item => /_(zero|one|two|few|many|other)$/.test(item.key))
         ? ` PLURALS: keys ending in _zero, _one, _two, _few, _many or _other are plural forms (Unicode CLDR categories) of ${languageName(lang)}. Write the form of that category, even when the source text given is the English plural (_zero is used when the count is 0, _two when it is 2; keep the {{count}} placeholder).`
         : '';
-    return `${intro(config, lang)} Translate each string in the JSON array. Return ONLY a valid JSON array of strings with the same number of elements in the same order. No explanations, no code fences.${rules(config, lang, items.map(i => i.source))}${keys}${plural}${revision}`;
+    return `${intro(config, lang)} Translate each string in the JSON array. Return ONLY a valid JSON array of strings with the same number of elements in the same order. No explanations, no code fences.${rules(config, lang, items.map(i => i.source))}${keys}${lengths}${plural}${revision}`;
 }
 /** System prompt for translating one string as plain text. */
 export function singlePrompt(config, lang, item, extra = '') {
     const revision = item.previous
         ? ` REVISION: the source was edited after it had been translated. Existing translation (of the older source): ${JSON.stringify(item.previous)}. ${REVISION_RULE[0].toUpperCase()}${REVISION_RULE.slice(1)}`
         : '';
-    return `${intro(config, lang)} The user message is one UI string (key: ${item.key}). Output only the translation, with no explanations, quotes or commentary.${rules(config, lang, [item.source])}${revision}${extra}`;
+    const length = item.maxLength
+        ? ` LENGTH LIMIT: at most ${item.maxLength} characters including spaces; the text is cut off past that. Prefer a shorter, freer phrasing over a literal one.`
+        : '';
+    return `${intro(config, lang)}${length} The user message is one UI string (key: ${item.key}). Output only the translation, with no explanations, quotes or commentary.${rules(config, lang, [item.source])}${revision}${extra}`;
 }
 /** Turns a translation request into a minimal correction of an existing translation. */
 export function repairInstruction(existing, problems) {

package/dist/review.js

@@ -1,13 +1,14 @@
 import path from 'node:path';
-import { flatten, readText } from './files.js';
-import { parseReviewId, State } from './state.js';
-import { hash } from './util.js';
+import { findSourceFiles, flatten, parseDoc, readText } from './files.js';
+import { parseReviewId, reviewId, State } from './state.js';
+import { hash, today } from './util.js';
 function currentValue(config, lang, fileId, key) {
-    const text = readText(path.join(config.root, fileId.split('{lang}').join(lang)));
+    const rel = fileId.split('{lang}').join(lang);
+    const text = readText(path.join(config.root, rel));
     if (text === null)
         return undefined;
     try {
-        return flatten(JSON.parse(text)).get(key);
+        return flatten(parseDoc(rel, text)).get(key);
     }
     catch {
         return undefined;
@@ -58,6 +59,25 @@ export function updateReview(config, action, selectors) {
         }
         changed++;
     }
+    // Approving a string that is not on the list marks it as checked by a person: it is then
+    // protected like a hand edit and the quality check no longer reports warnings for it.
+    if (action === 'approve') {
+        const exact = selectors.filter(sel => sel !== 'all' && !sel.endsWith(':*') && sel.includes(':'));
+        for (const selector of exact) {
+            const colon = selector.indexOf(':');
+            const [lang, key] = [selector.slice(0, colon), selector.slice(colon + 1)];
+            for (const file of findSourceFiles(config.root, config.files, config.sourceLanguage)) {
+                const id = reviewId(lang, file.id, key);
+                if (state.review[id])
+                    continue;
+                const value = currentValue(config, lang, file.id, key);
+                if (value === undefined)
+                    continue;
+                state.review[id] = { status: 'approved', reason: 'approved-by-hand', file: file.pathFor(lang), since: today(), valueHash: hash(value) };
+                changed++;
+            }
+        }
+    }
     if (changed > 0)
         state.save();
     return changed;

package/dist/scope.d.ts

@@ -0,0 +1,15 @@
+import type { Config } from './config.js';
+import { type LocaleFile } from './files.js';
+/** Which files and strings localewarden translates, and their length limits. */
+export declare class Scope {
+    private readonly config;
+    private readonly excluded;
+    private readonly ignored;
+    private readonly limits;
+    constructor(config: Config);
+    /** Excluded by id ("locales/{lang}/nav.json") or by the source path ("locales/en/nav.json"). */
+    isExcluded(file: LocaleFile): boolean;
+    /** Not text: an ignored key or a URL, email, file path or number. Copied, never translated. */
+    isLiteral(key: string, value: string): boolean;
+    maxLength(key: string): number | undefined;
+}

package/dist/scope.js

@@ -0,0 +1,26 @@
+import { isLiteralValue, keyPattern, pathPattern } from './files.js';
+/** Which files and strings localewarden translates, and their length limits. */
+export class Scope {
+    config;
+    excluded;
+    ignored;
+    limits;
+    constructor(config) {
+        this.config = config;
+        this.excluded = config.exclude.map(pathPattern);
+        this.ignored = config.ignoreKeys.map(keyPattern);
+        this.limits = Object.entries(config.maxLength).map(([pattern, max]) => [keyPattern(pattern), max]);
+    }
+    /** Excluded by id ("locales/{lang}/nav.json") or by the source path ("locales/en/nav.json"). */
+    isExcluded(file) {
+        const paths = [file.id, file.pathFor(this.config.sourceLanguage)];
+        return this.excluded.some(re => paths.some(p => re.test(p)));
+    }
+    /** Not text: an ignored key or a URL, email, file path or number. Copied, never translated. */
+    isLiteral(key, value) {
+        return this.ignored.some(re => re.test(key)) || isLiteralValue(value);
+    }
+    maxLength(key) {
+        return this.limits.find(([re]) => re.test(key))?.[1];
+    }
+}

package/dist/state.d.ts

@@ -9,7 +9,7 @@
  * repair-failures.json  targeted repairs (--fix-flagged) that were rejected, so the same
  *              value is not sent to the model again.
  */
-export type ReviewReason = 'manual-edit' | 'source-changed' | 'edited-after-approval';
+export type ReviewReason = 'manual-edit' | 'source-changed' | 'edited-after-approval' | 'approved-by-hand';
 export interface ReviewEntry {
     status: 'pending' | 'approved';
     reason: ReviewReason;