@jjlmoya/utils-language 1.2.0 → 1.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@jjlmoya/utils-language",
-    "version": "1.2.0",
+    "version": "1.4.0",
     "type": "module",
     "main": "./src/index.ts",
     "types": "./src/index.ts",

package/src/category/i18n/de.ts

@@ -3,14 +3,14 @@ import type { CategoryLocaleContent } from '../../types';
 export const content: CategoryLocaleContent = {
   slug: 'sprachen',
   title: 'Werkzeuge zum Sprachenlernen',
-  description: 'Private Browser Werkzeuge, die Sprachlernziele in praktische Lernplaene, Wochenroutinen und messbare Meilensteine verwandeln.',
+  description: 'Private Browser-Werkzeuge, die Sprachlernziele in praktische Lernpläne, Wochenroutinen und messbare Meilensteine verwandeln.',
   seo: [
-    { type: 'title', text: 'Werkzeuge fuer eine praktische Sprachlernplanung', level: 2 },
-    { type: 'paragraph', html: 'Eine Sprache lernt sich leichter, wenn aus einem grossen Ziel eine sichtbare Routine wird. Diese Sammlung beginnt mit einem Lernplaner, der GER Niveau, Zielniveau, Frist, Wochenzeit und bevorzugte Fertigkeiten verbindet.' },
-    { type: 'title', text: 'Fortschritt planen ohne Sprachfliessigkeit zu versprechen', level: 2 },
-    { type: 'paragraph', html: 'Der Planer nutzt breite Bereiche fuer angeleitetes Lernen, um den Arbeitsaufwand und die verfuegbare Zeit bis zur Frist zu schaetzen. Er ist eine Planungshilfe, kein Einstufungstest und keine Garantie.' },
-    { type: 'title', text: 'Privat und auf jedem Geraet nuetzlich', level: 2 },
+    { type: 'title', text: 'Werkzeuge für eine praktische Sprachlernplanung', level: 2 },
+    { type: 'paragraph', html: 'Eine Sprache lernt sich leichter, wenn aus einem großen Ziel eine sichtbare Routine wird. Diese Sammlung beginnt mit einem Lernplaner, der GER-Niveau, Zielniveau, Frist, Wochenzeit und bevorzugte Fertigkeiten verbindet.' },
+    { type: 'title', text: 'Fortschritt planen ohne Sprachflüssigkeit zu versprechen', level: 2 },
+    { type: 'paragraph', html: 'Der Planer nutzt breite Bereiche für angeleitetes Lernen, um den Arbeitsaufwand und die verfügbare Zeit bis zur Frist zu schätzen. Er ist eine Planungshilfe, kein Einstufungstest und keine Garantie.' },
+    { type: 'title', text: 'Privat und auf jedem Gerät nützlich', level: 2 },
     { type: 'paragraph', html: 'Auswahl, Niveau, Frist und Zeitplan bleiben im Browser. Es ist kein Konto erforderlich und die Eingaben werden nicht an einen Server gesendet.' },
-    { type: 'stats', items: [{ label: 'Werkzeug', value: '1', icon: 'mdi:tools' }, { label: 'Niveaus', value: 'A0 bis C2', icon: 'mdi:stairs-up' }, { label: 'Sprachen', value: '10', icon: 'mdi:translate' }, { label: 'Privatsphaere', value: 'Lokal', icon: 'mdi:shield-check' }] },
+    { type: 'stats', items: [{ label: 'Werkzeug', value: '1', icon: 'mdi:tools' }, { label: 'Niveaus', value: 'A0 bis C2', icon: 'mdi:stairs-up' }, { label: 'Sprachen', value: '10', icon: 'mdi:translate' }, { label: 'Privatsphäre', value: 'Lokal', icon: 'mdi:shield-check' }] },
   ],
 };

package/src/category/i18n/ja.ts

@@ -1,7 +1,7 @@
 import type { CategoryLocaleContent } from '../../types';
 
 export const content: CategoryLocaleContent = {
-  slug: 'gengo',
+  slug: 'language',
   title: '語学学習ツール',
   description: '語学の目標を実用的な学習計画、毎週の学習時間、確認できる到達目安に変える、ブラウザーで使えるプライベートなツールです。',
   seo: [

package/src/category/i18n/ko.ts

@@ -1,7 +1,7 @@
 import type { CategoryLocaleContent } from '../../types';
 
 export const content: CategoryLocaleContent = {
-  slug: 'eoneo',
+  slug: 'language',
   title: '언어 학습 도구',
   description: '언어 학습 목표를 실용적인 계획과 주간 학습 세션, 확인 가능한 중간 목표로 바꾸는 브라우저 기반 비공개 도구입니다.',
   seo: [

package/src/category/i18n/zh.ts

@@ -1,7 +1,7 @@
 import type { CategoryLocaleContent } from '../../types';
 
 export const content: CategoryLocaleContent = {
-  slug: 'yuyan',
+  slug: 'language',
   title: '语言学习工具',
   description: '在浏览器中使用的隐私工具，将语言目标转化为实用的学习计划、每周练习和可衡量的阶段目标。',
   seo: [

package/src/tests/category_quality.test.ts

@@ -0,0 +1,94 @@
+import { describe, expect, it } from 'vitest';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { languageCategory } from '../data';
+
+const EXPECTED_LOCALES = ['de', 'en', 'es', 'fr', 'id', 'it', 'ja', 'ko', 'nl', 'pl', 'pt', 'ru', 'sv', 'tr', 'zh'] as const;
+const EXPECTED_SLUGS = {
+  de: 'sprachen', en: 'language', es: 'idiomas', fr: 'langues', id: 'bahasa',
+  it: 'lingue', ja: 'language', ko: 'language', nl: 'talen', pl: 'jezyki', pt: 'idiomas',
+  ru: 'yazyki', sv: 'sprak', tr: 'diller', zh: 'language',
+} as const;
+const CATEGORY_DIR = join(process.cwd(), 'src', 'category', 'i18n');
+const SEO_TYPES = new Set(['title', 'paragraph', 'list', 'stats']);
+
+type CategoryContent = {
+  slug: string;
+  title: string;
+  description: string;
+  seo: Array<Record<string, unknown>>;
+};
+
+function sectionText(section: Record<string, unknown>): string {
+  const value = section.text ?? section.html ?? '';
+  return typeof value === 'string' ? value.replace(/<[^>]*>/g, '').trim() : '';
+}
+
+describe('Language category quality', () => {
+  it('has one registered category with a usable icon and unique tools', () => {
+    expect(languageCategory.icon.trim()).not.toBe('');
+    expect(languageCategory.tools.length).toBeGreaterThan(0);
+    const ids = languageCategory.tools.map((tool) => tool.id);
+    expect(new Set(ids).size).toBe(ids.length);
+  });
+
+  it('declares every locale in the category registry', () => {
+    expect(Object.keys(languageCategory.i18n).sort()).toEqual([...EXPECTED_LOCALES].sort());
+    for (const locale of EXPECTED_LOCALES) {
+      expect(typeof languageCategory.i18n[locale]).toBe('function');
+    }
+  });
+
+  it('keeps each locale source independent and explicit about its slug', () => {
+    expect(existsSync(join(CATEGORY_DIR, 'shared.ts'))).toBe(false);
+    for (const locale of EXPECTED_LOCALES) {
+      const source = readFileSync(join(CATEGORY_DIR, `${locale}.ts`), 'utf8');
+      expect(source, `${locale}.ts must declare its own slug`).toMatch(/(?:const\s+slug\s*=|\bslug\s*:)/);
+      expect(source, `${locale}.ts must not import a shared category translation`).not.toContain("from './shared'");
+    }
+  });
+
+  it('uses valid localized slugs and complete metadata in every locale', async () => {
+    for (const locale of EXPECTED_LOCALES) {
+      const content = await languageCategory.i18n[locale]!() as CategoryContent;
+      expect(content.slug).toBe(EXPECTED_SLUGS[locale]);
+      expect(content.slug).toMatch(/^[a-z0-9]+(?:-[a-z0-9]+)*$/);
+      expect(content.title.length).toBeGreaterThanOrEqual(5);
+      expect(content.title.length).toBeLessThanOrEqual(70);
+      expect(content.description.length).toBeGreaterThanOrEqual(20);
+      expect(content.description.length).toBeLessThanOrEqual(220);
+      expect(content.title).not.toMatch(/[|]/);
+      expect(content.description).not.toContain('\uFFFD');
+      expect(content.seo.length).toBeGreaterThan(0);
+    }
+  });
+
+  it('keeps SEO structure and useful text in parity with English', async () => {
+    const english = await languageCategory.i18n.en!() as CategoryContent;
+    const englishTypes = english.seo.map((section) => section.type);
+
+    for (const locale of EXPECTED_LOCALES) {
+      const content = await languageCategory.i18n[locale]!() as CategoryContent;
+      expect(content.seo.map((section) => section.type), locale).toEqual(englishTypes);
+      if (locale !== 'en') {
+        expect(content.title).not.toBe(english.title);
+      }
+
+      for (const section of content.seo) {
+        expect(SEO_TYPES.has(String(section.type)), `${locale} has an unsupported SEO section type`).toBe(true);
+        const text = sectionText(section);
+        if (section.type === 'title') {
+          expect(text.length, `${locale} SEO title is empty`).toBeGreaterThanOrEqual(8);
+        }
+        if (section.type === 'paragraph') {
+          expect(text.length, `${locale} SEO paragraph is too short`).toBeGreaterThanOrEqual(20);
+        }
+        if (section.type === 'stats') {
+          expect(Array.isArray(section.items), `${locale} SEO stats need items`).toBe(true);
+          expect((section.items as unknown[]).length).toBeGreaterThan(0);
+        }
+        expect(JSON.stringify(section)).not.toContain('\uFFFD');
+      }
+    }
+  });
+});

package/src/tests/category_slug_localization.test.ts

@@ -8,15 +8,15 @@ const EXPECTED_SLUGS = {
   fr: 'langues',
   id: 'bahasa',
   it: 'lingue',
-  ja: 'gengo',
-  ko: 'eoneo',
+  ja: 'language',
+  ko: 'language',
   nl: 'talen',
   pl: 'jezyki',
   pt: 'idiomas',
   ru: 'yazyki',
   sv: 'sprak',
   tr: 'diller',
-  zh: 'yuyan',
+  zh: 'language',
 } as const;
 
 describe('Category slug localization', () => {

package/src/tests/qa-test-helpers.ts

@@ -0,0 +1,31 @@
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { join, relative } from 'node:path';
+
+export const repositoryRoot = process.cwd();
+export const toolRoot = join(repositoryRoot, 'src', 'tool');
+
+export function listToolDirectories(): string[] {
+  return readdirSync(toolRoot)
+    .map((name) => join(toolRoot, name))
+    .filter((path) => statSync(path).isDirectory());
+}
+
+export function findFiles(directory: string, extensions: string[]): string[] {
+  const files: string[] = [];
+
+  for (const entry of readdirSync(directory, { withFileTypes: true })) {
+    const path = join(directory, entry.name);
+    if (entry.isDirectory()) files.push(...findFiles(path, extensions));
+    else if (extensions.some((extension) => entry.name.endsWith(extension))) files.push(path);
+  }
+
+  return files;
+}
+
+export function read(path: string): string {
+  return readFileSync(path, 'utf8');
+}
+
+export function displayPath(path: string): string {
+  return relative(repositoryRoot, path).replace(/\\/g, '/');
+}

package/src/tests/qa_bibliography_links.test.ts

@@ -0,0 +1,50 @@
+import { describe, expect, it } from 'vitest';
+import { ALL_TOOLS } from '../tools';
+import type { ToolLocaleContent } from '../types';
+
+interface LinkFailure {
+  tool: string;
+  message: string;
+}
+
+function validateLink(tool: string, entry: { url: string }, seen: Set<string>): LinkFailure[] {
+  const failures: LinkFailure[] = [];
+  let url: URL;
+  try {
+    url = new URL(entry.url);
+  } catch {
+    return [{ tool, message: `invalid URL: ${entry.url}` }];
+  }
+
+  if (url.protocol !== 'https:') {
+    failures.push({ tool, message: `non-HTTPS URL: ${entry.url}` });
+  }
+  if (url.pathname === '/' && !url.search && !url.hash) {
+    failures.push({ tool, message: `generic homepage, cite the exact document: ${entry.url}` });
+  }
+  if (seen.has(url.href)) {
+    failures.push({ tool, message: `duplicate source URL: ${entry.url}` });
+  }
+  seen.add(url.href);
+  return failures;
+}
+
+async function validateTool(tool: typeof ALL_TOOLS[number]): Promise<LinkFailure[]> {
+  const loader = tool.entry.i18n.en;
+  if (!loader) {
+    return [{ tool: tool.entry.id, message: 'English locale loader is missing' }];
+  }
+
+  const content = (await loader()) as ToolLocaleContent;
+  const seen = new Set<string>();
+  return (content.bibliography ?? []).flatMap((entry) => validateLink(tool.entry.id, entry, seen));
+}
+
+describe('QA: bibliography links are specific and usable', () => {
+  it('uses unique HTTPS links to exact source pages instead of generic homepages', async () => {
+    const failures = (await Promise.all(ALL_TOOLS.map(validateTool))).flat();
+
+    const messages = failures.map(({ tool, message }) => `${tool}: ${message}`);
+    expect(messages, `Bibliography hygiene failures:\n${messages.join('\n')}`).toEqual([]);
+  });
+});

package/src/tests/qa_claim_evidence.test.ts

@@ -0,0 +1,68 @@
+import { describe, expect, it } from 'vitest';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { displayPath, listToolDirectories, read } from './qa-test-helpers';
+
+const evidenceClaims = [
+  /\bofficial algorithm\b/i,
+  /\balgoritmo oficial\b/i,
+  /\b(?:records|data|rates|tables) updated(?:\s+(?:to|through)\s+20\d{2})?\b/i,
+  /\b(?:registros|datos|tasas|tablas) actualizad[oa]s?(?:\s+(?:a|hasta)\s+20\d{2})?\b/i,
+  /\b(?:validated|verified) (?:method|algorithm|calculation)\b/i,
+  /\b(?:método|algoritmo|cálculo) (?:validado|verificado)\b/i,
+  /\b(?:guarantees|ensures)\b/i,
+  /\bgarantiza\b/i,
+  /\bofficial (?:data|rate|calculation)\b/i,
+  /\b(?:datos|tasa|cálculo) oficial(?:es)?\b/i,
+];
+
+const requiredEvidenceFields = [
+  'reviewedAt',
+  'methodology',
+  'sources',
+  'referenceCases',
+  'limitations',
+];
+
+describe('QA: strong factual claims are traceable', () => {
+  it('requires machine-readable validation evidence beside tools making strong claims', () => {
+    const failures: string[] = [];
+
+    for (const directory of listToolDirectories()) {
+      const localePaths = ['en', 'es']
+        .map((locale) => join(directory, 'i18n', `${locale}.ts`))
+        .filter(existsSync);
+      const claims = localePaths.flatMap((path) => {
+        const source = read(path);
+        return evidenceClaims
+          .filter((pattern) => pattern.test(source))
+          .map((pattern) => `${displayPath(path)} matches ${pattern.source}`);
+      });
+      if (claims.length === 0) continue;
+
+      const evidencePath = join(directory, 'validation.ts');
+      if (!existsSync(evidencePath)) {
+        failures.push(`${displayPath(evidencePath)} missing; claims: ${claims.join(' | ')}`);
+        continue;
+      }
+
+      const evidence = read(evidencePath);
+      const missingFields = requiredEvidenceFields.filter(
+        (field) => !new RegExp(`\\b${field}\\s*:`).test(evidence),
+      );
+      if (missingFields.length > 0) {
+        failures.push(`${displayPath(evidencePath)} missing fields: ${missingFields.join(', ')}`);
+      }
+    }
+
+    expect(
+      failures,
+      [
+        'Claims such as official, validated, guaranteed or updated need inspectable evidence.',
+        'Add validation.ts with reviewedAt, methodology, sources, referenceCases and limitations,',
+        'or weaken/remove the unsupported claim.',
+        ...failures,
+      ].join('\n'),
+    ).toEqual([]);
+  });
+});

package/src/tests/qa_logic_reference_coverage.test.ts

@@ -0,0 +1,45 @@
+import { describe, expect, it } from 'vitest';
+import { basename, join } from 'node:path';
+import { existsSync } from 'node:fs';
+import {
+  displayPath,
+  findFiles,
+  listToolDirectories,
+  read,
+  repositoryRoot,
+} from './qa-test-helpers';
+
+function hasDedicatedLogicTest(toolDirectory: string): boolean {
+  const localCandidates = [
+    join(toolDirectory, 'logic.test.ts'),
+    join(toolDirectory, 'logic.spec.ts'),
+    join(toolDirectory, '__tests__', 'logic.test.ts'),
+    join(toolDirectory, '__tests__', 'logic.spec.ts'),
+  ];
+  if (localCandidates.some(existsSync)) return true;
+
+  const toolName = basename(toolDirectory);
+  const centralTests = findFiles(join(repositoryRoot, 'src', 'tests'), ['.test.ts', '.spec.ts']);
+  return centralTests.some((testPath) => {
+    const source = read(testPath).replace(/\\/g, '/');
+    return source.includes(`/tool/${toolName}/logic`) || source.includes(`../tool/${toolName}/logic`);
+  });
+}
+
+describe('QA: calculation logic has reference tests', () => {
+  it('gives every public calculator logic module its own behavioral test suite', () => {
+    const failures = listToolDirectories()
+      .filter((directory) => existsSync(join(directory, 'logic.ts')))
+      .filter((directory) => !hasDedicatedLogicTest(directory))
+      .map((directory) => `${displayPath(join(directory, 'logic.ts'))} -> no test imports this module`);
+
+    expect(
+      failures,
+      [
+        'Add behavioral tests through each logic module public API.',
+        'At minimum cover a documented reference case, boundaries, invalid input and invariants.',
+        ...failures,
+      ].join('\n'),
+    ).toEqual([]);
+  });
+});

package/src/tests/qa_runtime_i18n.test.ts

@@ -0,0 +1,99 @@
+import { describe, expect, it } from 'vitest';
+import { basename, join } from 'node:path';
+import { existsSync } from 'node:fs';
+import {
+  displayPath,
+  findFiles,
+  listToolDirectories,
+  read,
+  repositoryRoot,
+} from './qa-test-helpers';
+
+interface VisibleLiteral {
+  line: number;
+  value: string;
+}
+
+const domTextAssignment = /\.(?:innerText|textContent|innerHTML)\s*=/;
+const quotedLiteral = /(['"`])((?:\\.|(?!\1).)*)\1/g;
+
+function visibleWords(value: string): string {
+  return value
+    .replace(/\$\{[^}]*\}/g, ' ')
+    .replace(/<[^>]+>/g, ' ')
+    .replace(/&[a-z]+;/gi, ' ')
+    .replace(/[\d\p{P}\p{S}_]+/gu, ' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+function isTechnicalLiteral(value: string): boolean {
+  return ['.', '#', '['].some((prefix) => value.startsWith(prefix))
+    || /^data-[a-z0-9-]+$/i.test(value);
+}
+
+function hardcodedVisibleLiterals(source: string): VisibleLiteral[] {
+  const failures: VisibleLiteral[] = [];
+
+  source.split(/\r?\n/).forEach((line, index) => {
+    if (!domTextAssignment.test(line)) return;
+
+    const assignment = line.slice(line.search(domTextAssignment));
+    for (const match of assignment.matchAll(quotedLiteral)) {
+      if (isTechnicalLiteral(match[2])) continue;
+      const words = visibleWords(match[2]);
+      if (words && /\p{L}/u.test(words)) {
+        failures.push({ line: index + 1, value: match[2] });
+      }
+    }
+  });
+
+  return failures;
+}
+
+function runtimeSources(toolDirectory: string): string {
+  return findFiles(toolDirectory, ['.astro', '.ts', '.js'])
+    .filter((path) => !path.includes(`${join(toolDirectory, 'i18n')}`))
+    .filter((path) => basename(path) !== 'ui.ts')
+    .map(read)
+    .join('\n');
+}
+
+describe('QA: runtime copy is localized', () => {
+  const componentFiles = findFiles(join(repositoryRoot, 'src', 'tool'), ['.astro']);
+
+  it('does not write user-facing string literals directly into the DOM', () => {
+    const failures = componentFiles.flatMap((path) =>
+      hardcodedVisibleLiterals(read(path)).map(
+        ({ line, value }) => `${displayPath(path)}:${line} -> ${JSON.stringify(value)}`,
+      ),
+    );
+
+    expect(
+      failures,
+      `Move visible browser copy to the tool UI locale contract:\n${failures.join('\n')}`,
+    ).toEqual([]);
+  });
+
+  it('uses every string declared by each UI locale contract', () => {
+    const failures: string[] = [];
+
+    for (const directory of listToolDirectories()) {
+      const uiPath = join(directory, 'ui.ts');
+      if (!existsSync(uiPath)) continue;
+
+      const keys = Array.from(read(uiPath).matchAll(/^\s*(\w+)\??:\s*string\s*;/gm), (match) => match[1]);
+      const runtime = runtimeSources(directory);
+      const unused = keys.filter((key) => !new RegExp(`\\b${key}\\b`).test(runtime));
+
+      if (unused.length > 0) {
+        failures.push(`${displayPath(uiPath)} -> unused: ${unused.join(', ')}`);
+      }
+    }
+
+    expect(
+      failures,
+      `Unused locale keys are dead copy or may mean the browser bypasses translations:\n${failures.join('\n')}`,
+    ).toEqual([]);
+  });
+});

package/src/tool/language-learning-study-plan-planner/index.ts

@@ -1,4 +1,11 @@
-export { languageLearningStudyPlanPlanner, LANGUAGE_LEARNING_STUDY_PLAN_PLANNER_TOOL } from './entry';
+import type { ToolDefinition } from '../../types';
+import {
+  LANGUAGE_LEARNING_STUDY_PLAN_PLANNER_TOOL as languageLearningStudyPlanPlannerDefinition,
+} from './entry';
+
+export { languageLearningStudyPlanPlanner } from './entry';
 export type { LanguagePlannerUI, LanguageLearningStudyPlanPlannerLocaleContent } from './entry';
 export { calculateStudyPlan, GUIDED_HOURS_FROM_BEGINNER, LEVEL_LABELS, PRIORITY_ALLOCATIONS, STUDY_LEVELS } from './logic';
 export type { LanguagePlannerInputs, PlanStatus, SkillAllocation, StudyLevel, StudyMilestone, StudyPlan } from './types';
+
+export const LANGUAGE_LEARNING_STUDY_PLAN_PLANNER_TOOL: ToolDefinition = languageLearningStudyPlanPlannerDefinition;

package/src/tool/language-learning-study-plan-planner/validation.ts

@@ -0,0 +1,15 @@
+export const validation = {
+  reviewedAt: '2026-08-29',
+  methodology: 'The planner uses broad guided-learning hour ranges as a planning estimate, subtracts the current level range from the target level range, and compares the result with weeks available at the selected weekly pace.',
+  sources: [
+    'https://www.coe.int/en/web/common-european-framework-reference-languages',
+    'https://www.cambridge.org/elt/blog/2020/08/19/how-long-learn-language/',
+  ],
+  referenceCases: [
+    { currentLevel: 'A1', targetLevel: 'B1', expectedHoursRange: '260-300' },
+  ],
+  limitations: [
+    'The ranges are planning estimates, not a placement test or a guarantee of fluency.',
+    'Language distance, previous exposure, study quality, and real-world practice can materially change the time required.',
+  ],
+};