@katerynakhar/i18n-keeper 0.16.0

package/src/glossary.ts

@@ -0,0 +1,191 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+export const GLOSSARY_FILE = '.i18n/glossary.json';
+
+export type MatchMode = 'prefix' | 'exact' | 'substring';
+
+export interface GlossaryTerm {
+  /** The word as it appears in the source locale. */
+  source: string;
+  /** Accepted renderings per locale. Locales left out are not checked. */
+  targets: Record<string, string[]>;
+  /** Default `prefix`, which tolerates suffix inflection: panier → paniers. */
+  match: MatchMode;
+  caseSensitive: boolean;
+}
+
+export interface Glossary {
+  version: 1;
+  /** Tokens that must survive verbatim: brand and product names, protocols. */
+  doNotTranslate: string[];
+  terms: GlossaryTerm[];
+}
+
+export class GlossaryError extends Error {}
+
+export function glossaryPath(root: string, explicit?: string): string {
+  return resolve(root, explicit ?? GLOSSARY_FILE);
+}
+
+function fail(file: string, message: string): never {
+  throw new GlossaryError(`Invalid glossary ${file}\n  ${message}`);
+}
+
+function asStringArray(file: string, value: unknown, where: string): string[] {
+  if (!Array.isArray(value) || value.some((v) => typeof v !== 'string')) {
+    fail(file, `${where} must be an array of strings`);
+  }
+  return value as string[];
+}
+
+export function loadGlossary(file: string): Glossary | null {
+  if (!existsSync(file)) return null;
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(readFileSync(file, 'utf8'));
+  } catch (err) {
+    fail(file, err instanceof Error ? err.message : String(err));
+  }
+
+  if (typeof parsed !== 'object' || parsed === null) fail(file, 'expected an object');
+  const raw = parsed as Record<string, unknown>;
+  if (raw['version'] !== 1) fail(file, 'expected "version": 1');
+
+  const doNotTranslate =
+    raw['doNotTranslate'] === undefined
+      ? []
+      : asStringArray(file, raw['doNotTranslate'], 'doNotTranslate');
+
+  const termsRaw = raw['terms'] === undefined ? [] : raw['terms'];
+  if (!Array.isArray(termsRaw)) fail(file, 'terms must be an array');
+
+  const terms: GlossaryTerm[] = termsRaw.map((entry, index) => {
+    const where = `terms[${index}]`;
+    if (typeof entry !== 'object' || entry === null) fail(file, `${where} must be an object`);
+    const term = entry as Record<string, unknown>;
+
+    const source = term['source'];
+    if (typeof source !== 'string' || source === '') {
+      fail(file, `${where}.source must be a non-empty string`);
+    }
+
+    const targetsRaw = term['targets'];
+    if (typeof targetsRaw !== 'object' || targetsRaw === null || Array.isArray(targetsRaw)) {
+      fail(file, `${where}.targets must be an object keyed by locale`);
+    }
+    const targets: Record<string, string[]> = {};
+    for (const [locale, value] of Object.entries(targetsRaw as Record<string, unknown>)) {
+      const forms = asStringArray(file, value, `${where}.targets.${locale}`);
+      if (forms.length === 0) fail(file, `${where}.targets.${locale} must list at least one form`);
+      targets[locale] = forms;
+    }
+
+    const match = term['match'] ?? 'prefix';
+    if (match !== 'prefix' && match !== 'exact' && match !== 'substring') {
+      fail(file, `${where}.match must be "prefix", "exact" or "substring"`);
+    }
+
+    const caseSensitive = term['caseSensitive'] ?? false;
+    if (typeof caseSensitive !== 'boolean') fail(file, `${where}.caseSensitive must be a boolean`);
+
+    return { source, targets, match, caseSensitive };
+  });
+
+  return { version: 1, doNotTranslate, terms };
+}
+
+// ---------------------------------------------------------------------------
+// Matching
+// ---------------------------------------------------------------------------
+
+const WORDLIKE = /[\p{L}\p{N}]/u;
+
+/**
+ * Scripts written without spaces, where a term is normally surrounded by other
+ * letters and boundary checks would never match.
+ */
+const NO_WORD_BREAKS =
+  /[\p{Script=Han}\p{Script=Hiragana}\p{Script=Katakana}\p{Script=Thai}\p{Script=Lao}\p{Script=Khmer}\p{Script=Myanmar}]/u;
+
+export function usesWordBoundaries(term: string): boolean {
+  return !NO_WORD_BREAKS.test(term);
+}
+
+/**
+ * Whether `term` occurs in `text`.
+ *
+ * `prefix` is the default because suffix inflection is the common case: a
+ * glossary saying "panier" should accept "paniers", and one saying "корзин"
+ * should accept every case ending.
+ */
+export function containsTerm(
+  text: string,
+  term: string,
+  match: MatchMode = 'prefix',
+  caseSensitive = false,
+): boolean {
+  if (term === '') return false;
+
+  const haystack = caseSensitive ? text : text.toLowerCase();
+  const needle = caseSensitive ? term : term.toLowerCase();
+
+  if (match === 'substring' || !usesWordBoundaries(term)) {
+    return haystack.includes(needle);
+  }
+
+  let from = 0;
+  for (;;) {
+    const at = haystack.indexOf(needle, from);
+    if (at === -1) return false;
+
+    const before = at === 0 ? '' : haystack[at - 1]!;
+    const startsWord = before === '' || !WORDLIKE.test(before);
+
+    if (startsWord) {
+      if (match === 'prefix') return true;
+      const afterIndex = at + needle.length;
+      const after = afterIndex >= haystack.length ? '' : haystack[afterIndex]!;
+      if (after === '' || !WORDLIKE.test(after)) return true;
+    }
+
+    from = at + 1;
+  }
+}
+
+export interface TermExpectation {
+  term: GlossaryTerm;
+  accepted: string[];
+}
+
+/** Terms that apply to this source string for this locale, with their forms. */
+export function expectationsFor(
+  glossary: Glossary,
+  locale: string,
+  sourceValue: string,
+): TermExpectation[] {
+  const out: TermExpectation[] = [];
+  for (const term of glossary.terms) {
+    const accepted = term.targets[locale];
+    if (!accepted) continue;
+    if (!containsTerm(sourceValue, term.source, term.match, term.caseSensitive)) continue;
+    out.push({ term, accepted });
+  }
+  return out;
+}
+
+/** Do-not-translate tokens present in the source but missing from the target. */
+export function missingVerbatim(
+  glossary: Glossary,
+  sourceValue: string,
+  targetValue: string,
+): string[] {
+  const missing: string[] = [];
+  for (const token of glossary.doNotTranslate) {
+    // Brand names carry their capitalisation, so this comparison is exact.
+    if (!containsTerm(sourceValue, token, 'exact', true)) continue;
+    if (!containsTerm(targetValue, token, 'exact', true)) missing.push(token);
+  }
+  return missing;
+}

package/src/lengths.ts

@@ -0,0 +1,214 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { looksLikeIcuPlural } from './plurals.js';
+
+export const LIMITS_FILE = '.i18n/limits.json';
+
+export interface LimitPattern {
+  match: string;
+  max: number;
+}
+
+export interface Limits {
+  version: 1;
+  /** Applied to every measurable key when set. */
+  default: number | null;
+  keys: Record<string, number>;
+  patterns: LimitPattern[];
+}
+
+export class LimitsError extends Error {}
+
+export function limitsPath(root: string, explicit?: string): string {
+  return resolve(root, explicit ?? LIMITS_FILE);
+}
+
+function fail(file: string, message: string): never {
+  throw new LimitsError(`Invalid limits ${file}\n  ${message}`);
+}
+
+function asMax(file: string, value: unknown, where: string): number {
+  if (typeof value !== 'number' || !Number.isInteger(value) || value <= 0) {
+    fail(file, `${where} must be a positive integer`);
+  }
+  return value;
+}
+
+export function loadLimits(file: string): Limits | null {
+  if (!existsSync(file)) return null;
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(readFileSync(file, 'utf8'));
+  } catch (err) {
+    fail(file, err instanceof Error ? err.message : String(err));
+  }
+
+  if (typeof parsed !== 'object' || parsed === null) fail(file, 'expected an object');
+  const raw = parsed as Record<string, unknown>;
+  if (raw['version'] !== 1) fail(file, 'expected "version": 1');
+
+  const fallback =
+    raw['default'] === undefined || raw['default'] === null
+      ? null
+      : asMax(file, raw['default'], 'default');
+
+  const keys: Record<string, number> = {};
+  if (raw['keys'] !== undefined) {
+    if (typeof raw['keys'] !== 'object' || raw['keys'] === null || Array.isArray(raw['keys'])) {
+      fail(file, 'keys must be an object mapping key to maximum width');
+    }
+    for (const [key, value] of Object.entries(raw['keys'] as Record<string, unknown>)) {
+      keys[key] = asMax(file, value, `keys.${key}`);
+    }
+  }
+
+  const patterns: LimitPattern[] = [];
+  if (raw['patterns'] !== undefined) {
+    if (!Array.isArray(raw['patterns'])) fail(file, 'patterns must be an array');
+    raw['patterns'].forEach((entry, index) => {
+      const where = `patterns[${index}]`;
+      if (typeof entry !== 'object' || entry === null) fail(file, `${where} must be an object`);
+      const pattern = entry as Record<string, unknown>;
+      if (typeof pattern['match'] !== 'string' || pattern['match'] === '') {
+        fail(file, `${where}.match must be a non-empty string`);
+      }
+      patterns.push({
+        match: pattern['match'],
+        max: asMax(file, pattern['max'], `${where}.max`),
+      });
+    });
+  }
+
+  return { version: 1, default: fallback, keys, patterns };
+}
+
+function globToRegExp(glob: string): RegExp {
+  // Split on the wildcard first, so the escaping pass never has to carry a
+  // placeholder character through the string.
+  const pattern = glob
+    .split('*')
+    .map((part) => part.replace(/[.+?^${}()|[\]\\]/g, '\\$&'))
+    .join('.*');
+  return new RegExp(`^${pattern}$`);
+}
+
+const patternCache = new Map<string, RegExp>();
+
+/** Exact keys win over patterns, and the first matching pattern wins over the default. */
+export function limitFor(limits: Limits, key: string): number | null {
+  const exact = limits.keys[key];
+  if (exact !== undefined) return exact;
+
+  for (const pattern of limits.patterns) {
+    let re = patternCache.get(pattern.match);
+    if (!re) {
+      re = globToRegExp(pattern.match);
+      patternCache.set(pattern.match, re);
+    }
+    if (re.test(key)) return pattern.max;
+  }
+
+  return limits.default;
+}
+
+// ---------------------------------------------------------------------------
+// Width
+// ---------------------------------------------------------------------------
+
+const COMBINING = /\p{M}/u;
+
+const ZERO_WIDTH = new Set([0x200b, 0x200c, 0x200d, 0x200e, 0x200f, 0xfeff]);
+
+/** East Asian Wide and Fullwidth blocks, which occupy two columns. */
+const WIDE_RANGES: Array<[number, number]> = [
+  [0x1100, 0x115f],
+  [0x2e80, 0x303e],
+  [0x3041, 0x33ff],
+  [0x3400, 0x4dbf],
+  [0x4e00, 0x9fff],
+  [0xa000, 0xa4cf],
+  [0xa960, 0xa97f],
+  [0xac00, 0xd7a3],
+  [0xf900, 0xfaff],
+  [0xfe10, 0xfe19],
+  [0xfe30, 0xfe6f],
+  [0xff00, 0xff60],
+  [0xffe0, 0xffe6],
+  [0x17000, 0x18aff],
+  [0x1b000, 0x1b12f],
+  [0x1f300, 0x1f64f],
+  [0x1f900, 0x1f9ff],
+  [0x20000, 0x3fffd],
+];
+
+function isWide(cp: number): boolean {
+  for (const [start, end] of WIDE_RANGES) {
+    if (cp < start) return false;
+    if (cp <= end) return true;
+  }
+  return false;
+}
+
+/**
+ * Width in display columns rather than UTF-16 units: a CJK character occupies
+ * two columns, combining marks none. Counting `.length` would report Japanese
+ * as half its real size and any emoji as double.
+ */
+export function displayWidth(text: string): number {
+  let width = 0;
+  for (const ch of text) {
+    const cp = ch.codePointAt(0)!;
+    if (ZERO_WIDTH.has(cp) || (cp >= 0xfe00 && cp <= 0xfe0f)) continue;
+    if (COMBINING.test(ch)) continue;
+    width += isWide(cp) ? 2 : 1;
+  }
+  return width;
+}
+
+/** Splits on Laravel's top-level pipes, which select between forms. */
+function segments(text: string): string[] {
+  const out: string[] = [];
+  let depth = 0;
+  let current = '';
+  for (const ch of text) {
+    if (ch === '{' || ch === '[') depth++;
+    else if (ch === '}' || ch === ']') depth = Math.max(0, depth - 1);
+    if (ch === '|' && depth === 0) {
+      out.push(current);
+      current = '';
+      continue;
+    }
+    current += ch;
+  }
+  out.push(current);
+  return out;
+}
+
+/**
+ * An ICU plural carries every branch in one string but shows one at a time, and
+ * its selectors are not displayed at all, so measuring it would be meaningless.
+ */
+export function measurable(text: string): boolean {
+  return !looksLikeIcuPlural(text);
+}
+
+/** The widest thing the user can actually end up seeing. */
+export function renderedWidth(text: string, laravel: boolean): number {
+  if (!laravel) return displayWidth(text);
+  return Math.max(...segments(text).map((segment) => displayWidth(segment.trim())));
+}
+
+/**
+ * Conventional translation-expansion allowances: short strings grow much more
+ * in relative terms than long ones, so a single ratio would either miss real
+ * overflow or flag every button. These are rules of thumb, not a standard.
+ */
+export function allowanceFor(sourceWidth: number): number {
+  if (sourceWidth <= 10) return 3;
+  if (sourceWidth <= 20) return 2;
+  if (sourceWidth <= 30) return 1.8;
+  if (sourceWidth <= 50) return 1.6;
+  if (sourceWidth <= 70) return 1.4;
+  return 1.3;
+}