@jjlmoya/utils-language 1.5.0 → 1.6.0

package/package.json

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

package/src/category/i18n/en.ts

@@ -10,7 +10,7 @@ export const content: CategoryLocaleContent = {
     { type: 'title', text: 'Language Learning Tools for Practical Study Planning', level: 2 },
     { type: 'paragraph', html: 'Learning a language is easier to sustain when a broad goal becomes a small, visible routine. This focused collection starts with a study plan planner that connects your current CEFR level, target level, deadline, weekly time, and preferred skills into a clear weekly rhythm.' },
     { type: 'title', text: 'Plan Progress Without Promising Fluency', level: 2 },
-    { type: 'paragraph', html: 'The planner uses broad guided-learning ranges associated with CEFR progression to estimate a workload and surface the time available before your deadline. It is a planning aid, not a placement test, course recommendation, or guarantee of fluency. Results vary with language pair, previous exposure, study quality, and real-world practice.' },
+    { type: 'paragraph', html: 'The planner uses broad guided-learning ranges associated with CEFR progression to estimate a workload and surface the time available before your deadline. It is a planning aid, not a placement test, course recommendation, or promise of fluency. Results vary with language pair, previous exposure, study quality, and real-world practice.' },
     { type: 'title', text: 'Private and Useful on Any Device', level: 2 },
     { type: 'paragraph', html: 'Your language choices, level, deadline, and schedule stay in your browser. No account is required, and the planner does not send your study inputs to a server. Use the result as a starting point, then adjust it when your weekly life or progress changes.' },
     { type: 'stats', items: [

package/src/tests/category_seo_quality.test.ts

@@ -0,0 +1,76 @@
+import { describe, expect, it } from 'vitest';
+import type { CategoryLocaleContent } from '../types';
+
+const EXPECTED_LOCALES = [
+  'de', 'en', 'es', 'fr', 'id', 'it', 'ja', 'ko', 'nl', 'pl', 'pt', 'ru', 'sv', 'tr', 'zh',
+] as const;
+const COMPACT_LOCALES = new Set(['ja', 'ko', 'zh']);
+
+const localeModules = import.meta.glob('../category/i18n/*.ts', { eager: true }) as Record<
+  string,
+  { content: CategoryLocaleContent }
+>;
+
+function textFrom(value: unknown): string {
+  if (typeof value === 'string') return value.replace(/<[^>]*>/g, ' ');
+  if (Array.isArray(value)) return value.map(textFrom).join(' ');
+  if (value && typeof value === 'object') return Object.values(value).map(textFrom).join(' ');
+  return '';
+}
+
+const STRONG_CLAIM = /\b(?:garantiz\w*|guarante\w*|validat(?:ed)|valid(?:ated|ado|ada|ados|adas|ée|ées)|actualizad\w*)\b/iu;
+
+function getContents(): Map<string, CategoryLocaleContent> {
+  return new Map(
+    Object.entries(localeModules).map(([file, module]) => [file.match(/\/([a-z]{2})\.ts$/u)?.[1] ?? file, module.content]),
+  );
+}
+
+function validateContent(locale: string, content: CategoryLocaleContent): string[] {
+  const failures: string[] = [];
+  const check = (condition: boolean, message: string) => { if (!condition) failures.push(`${locale}: ${message}`); };
+  const minimumTitleLength = COMPACT_LOCALES.has(locale) ? 4 : 12;
+  const minimumDescriptionLength = COMPACT_LOCALES.has(locale) ? 20 : 60;
+  check(content.title.trim().length >= minimumTitleLength && content.title.trim().length <= 70, 'title must use a useful 4/12–70 character length');
+  check(content.description.trim().length >= minimumDescriptionLength && content.description.trim().length <= 180, 'description must use a useful 20/60–180 character length');
+  check(content.seo.length >= 2, 'SEO needs at least two sections');
+
+  const seoText = textFrom(content.seo).replace(/\s+/g, ' ').trim();
+  const minimumSeoLength = COMPACT_LOCALES.has(locale) ? 120 : 240;
+  check(seoText.length >= minimumSeoLength, 'SEO copy must contain the minimum visible copy for its script');
+  check(content.seo.filter((section) => section.type === 'title').length >= 1, 'SEO needs a section heading');
+  check(!/[�]/u.test(seoText), 'SEO contains replacement characters');
+  check(!/ {2,}/u.test(seoText), 'SEO contains duplicated whitespace');
+  check(!STRONG_CLAIM.test(seoText), 'SEO contains an unsupported strong claim');
+
+  check(content.slug.trim().length > 0 && /^[a-z0-9-]+$/u.test(content.slug), 'slug must be a non-empty URL-safe value');
+  return failures;
+}
+
+describe('Category SEO quality contract', () => {
+  it('has one content file for every configured locale', () => {
+    const contents = getContents();
+    expect([...contents.keys()].sort()).toEqual([...EXPECTED_LOCALES].sort());
+  });
+
+  it('keeps metadata, SEO structure and copy quality above the minimum in every locale', () => {
+    const contents = getContents();
+    const english = contents.get('en');
+    expect(english, 'English category content is required as the structural reference').toBeDefined();
+
+    const failures = EXPECTED_LOCALES.flatMap((locale) => {
+      const content = contents.get(locale);
+      return content ? validateContent(locale, content) : [];
+    });
+
+    const englishShape = english?.seo.map((section) => section.type);
+    for (const locale of EXPECTED_LOCALES) {
+      const content = contents.get(locale);
+      if (content && JSON.stringify(content.seo.map((section) => section.type)) !== JSON.stringify(englishShape)) {
+        failures.push(`${locale}: SEO section types must match English`);
+      }
+    }
+
+    expect(failures, 'category SEO quality failures').toEqual([]);
+  }, 30000);
+});

package/src/tests/qa_runtime_i18n.test.ts

@@ -40,10 +40,10 @@ function hardcodedVisibleLiterals(source: string): VisibleLiteral[] {
 
     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 (isTechnicalLiteral(match[2]!)) continue;
+      const words = visibleWords(match[2]!);
       if (words && /\p{L}/u.test(words)) {
-        failures.push({ line: index + 1, value: match[2] });
+        failures.push({ line: index + 1, value: match[2]! });
       }
     }
   });

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

@@ -4,6 +4,7 @@ import {
 } from './entry';
 
 export type { LanguagePlannerUI, LanguageLearningStudyPlanPlannerLocaleContent } from './entry';
+export { languageLearningStudyPlanPlanner } 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';