@jjlmoya/utils-games-development 1.52.0 → 1.53.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@jjlmoya/utils-games-development",
-    "version": "1.52.0",
+    "version": "1.53.0",
     "type": "module",
     "main": "./src/index.ts",
     "types": "./src/index.ts",

package/src/entries.ts

@@ -8,12 +8,14 @@ export { audioLoopPointFinder } from './tool/audioLoopPointFinder/entry';
 export type { AudioLoopPointFinderUI, AudioLoopPointFinderLocaleContent } from './tool/audioLoopPointFinder/entry';
 export { saveFileEditor } from './tool/saveFileEditor/entry';
 export type { SaveFileEditorUI, SaveFileEditorLocaleContent } from './tool/saveFileEditor/entry';
+export { localizationSanitizer } from './tool/localizationSanitizer/entry';
+export type { LocalizationSanitizerUI, LocalizationSanitizerLocaleContent } from './tool/localizationSanitizer/entry';
 export { gamesCategory } from './category';
 import { steamCapsuleGenerator } from './tool/steamCapsuleGenerator/entry';
 import { itchioGameTester } from './tool/itchioGameTester/entry';
 import { spriteSheetPacker } from './tool/spriteSheetPacker/entry';
 import { audioLoopPointFinder } from './tool/audioLoopPointFinder/entry';
 import { saveFileEditor } from './tool/saveFileEditor/entry';
+import { localizationSanitizer } from './tool/localizationSanitizer/entry';
 
-export const ALL_ENTRIES = [steamCapsuleGenerator, itchioGameTester, spriteSheetPacker, audioLoopPointFinder, saveFileEditor];
-
+export const ALL_ENTRIES = [steamCapsuleGenerator, itchioGameTester, spriteSheetPacker, audioLoopPointFinder, saveFileEditor, localizationSanitizer];

package/src/tests/locale_completeness.test.ts

@@ -3,6 +3,6 @@ import { ALL_TOOLS } from '../tools';
 
 describe('Locale Completeness Validation', () => {
   it('five tools are registered', () => {
-    expect(ALL_TOOLS.length).toBe(5);
+    expect(ALL_TOOLS.length).toBe(6);
   });
 });

package/src/tests/tool_validation.test.ts

@@ -5,7 +5,7 @@ import { gamesCategory } from '../data';
 describe('Tool Validation Suite', () => {
   describe('Library Registration', () => {
     it('should have 5 tools in ALL_TOOLS', () => {
-      expect(ALL_TOOLS.length).toBe(5);
+      expect(ALL_TOOLS.length).toBe(6);
     });
 
     it('gamesCategory should be defined', () => {

package/src/tool/localizationSanitizer/app-client.ts

@@ -0,0 +1,270 @@
+import { detectTranslationFormat, sanitizeTranslationFile, type SanitizerIssue, type SanitizerResult, type TranslationFormat } from './logic';
+
+const SAMPLE_CSV = 'key,en,es,fr\nmenu.play,Play,"Jugar, ahora",Jouer\nmenu.pause,Pause,,Pause\nmenu.play,Play again,Reproducir,Jouer encore\nmenu.quit,Quit,Salir,\n';
+
+function createElement<K extends keyof HTMLElementTagNameMap>(tagName: K, className?: string): HTMLElementTagNameMap[K] {
+  const element = document.createElement(tagName);
+  if (className) element.className = className;
+  return element;
+}
+
+function datasetText(root: HTMLElement, key: string): string { return root.dataset[key] || ''; }
+
+function issueLabel(root: HTMLElement, item: SanitizerIssue): string {
+  const labels: Record<SanitizerIssue['kind'], string> = {
+    empty: datasetText(root, 'emptyIssue'),
+    duplicate: datasetText(root, 'duplicateIssue'),
+    malformed: datasetText(root, 'malformedIssue'),
+    parse: datasetText(root, 'parseIssue'),
+  };
+  return labels[item.kind];
+}
+
+function renderIssueCard(root: HTMLElement, item: SanitizerIssue): HTMLElement {
+  const card = createElement('div', `ls-issue-card ls-issue-${item.kind}`);
+  const marker = createElement('span', 'ls-issue-marker');
+  const copy = createElement('div', 'ls-issue-copy');
+  const title = createElement('strong');
+  title.textContent = issueLabel(root, item);
+  const detail = createElement('span');
+  const location = item.kind === 'parse' ? '' : `${datasetText(root, 'rowLabel')} ${item.row} · ${item.column ? `${datasetText(root, 'columnLabel')} ${item.column}` : datasetText(root, 'keyLabel')} ${item.key || '—'}`;
+  detail.textContent = location;
+  copy.append(title, detail);
+  card.append(marker, copy);
+  return card;
+}
+
+function renderIssues(root: HTMLElement, result: SanitizerResult | null): void {
+  const list = root.querySelector<HTMLElement>('#ls-issue-list');
+  if (!list) return;
+  list.replaceChildren();
+  if (!result) return;
+  if (result.issues.length === 0) {
+    const success = createElement('div', 'ls-no-issues');
+    success.textContent = datasetText(root, 'noIssues');
+    list.append(success);
+    return;
+  }
+  result.issues.slice(0, 40).forEach((item) => list.append(renderIssueCard(root, item)));
+  if (result.issues.length > 40) {
+    const more = createElement('span', 'ls-issue-more');
+    more.textContent = `+${result.issues.length - 40}`;
+    list.append(more);
+  }
+}
+
+function renderEmptyState(root: HTMLElement): HTMLElement {
+  const empty = createElement('div', 'ls-empty-state');
+  const grid = createElement('span', 'ls-empty-grid');
+  grid.setAttribute('aria-hidden', 'true');
+  const title = createElement('strong');
+  title.textContent = datasetText(root, 'waitingTitle');
+  const subtitle = createElement('span');
+  subtitle.textContent = datasetText(root, 'waitingSubtitle');
+  empty.append(grid, title, subtitle);
+  return empty;
+}
+
+function renderPreviewTable(result: SanitizerResult): HTMLElement {
+  const table = createElement('table', 'ls-table');
+  const thead = createElement('thead');
+  const headingRow = createElement('tr');
+  result.headers.forEach((header) => {
+    const heading = createElement('th');
+    heading.textContent = header;
+    headingRow.append(heading);
+  });
+  thead.append(headingRow);
+  const body = createElement('tbody');
+  result.rows.slice(0, 12).forEach((row) => {
+    const tableRow = createElement('tr');
+    row.forEach((value) => {
+      const cell = createElement('td');
+      cell.textContent = value;
+      if (!value.trim()) cell.classList.add('is-empty');
+      tableRow.append(cell);
+    });
+    body.append(tableRow);
+  });
+  table.append(thead, body);
+  return table;
+}
+
+function renderPreview(root: HTMLElement, result: SanitizerResult | null): void {
+  const preview = root.querySelector<HTMLElement>('#ls-preview');
+  if (!preview) return;
+  preview.replaceChildren();
+  if (!result || !result.valid) {
+    preview.append(renderEmptyState(root));
+    return;
+  }
+  preview.append(renderPreviewTable(result));
+  if (result.rows.length > 12) {
+    const note = createElement('span', 'ls-preview-note');
+    note.textContent = `+${result.rows.length - 12}`;
+    preview.append(note);
+  }
+}
+
+function updateElementText(root: HTMLElement, selector: string, text: string): void {
+  const element = root.querySelector<HTMLElement>(selector);
+  if (element) element.textContent = text;
+}
+
+function updateCounts(root: HTMLElement, result: SanitizerResult | null): void {
+  updateElementText(root, '#ls-empty-count', result ? String(result.stats.emptyCells) : '0');
+  updateElementText(root, '#ls-duplicate-count', result ? String(result.stats.duplicateKeys) : '0');
+  updateElementText(root, '#ls-malformed-count', result ? String(result.stats.malformedRows) : '0');
+  updateElementText(root, '#ls-clean-count', result ? String(result.stats.cleanRows) : '0');
+}
+
+function updateHealth(root: HTMLElement, result: SanitizerResult | null): void {
+  const ring = root.querySelector<HTMLElement>('#ls-health-ring');
+  if (!result) {
+    updateElementText(root, '#ls-health-value', '--');
+    updateElementText(root, '#ls-health-status', datasetText(root, 'waitingTitle'));
+    updateElementText(root, '#ls-health-subtitle', datasetText(root, 'waitingSubtitle'));
+    if (ring) ring.style.setProperty('--health-angle', '0deg');
+    return;
+  }
+  const { stats } = result;
+  const score = result.valid ? Math.max(0, 100 - (stats.emptyCells * 4) - (stats.duplicateKeys * 18) - (stats.malformedRows * 12)) : 0;
+  updateElementText(root, '#ls-health-value', `${score}`);
+  updateElementText(root, '#ls-health-status', score === 100 ? datasetText(root, 'readyStatus') : datasetText(root, 'reviewStatus'));
+  updateElementText(root, '#ls-health-subtitle', result.valid ? `${stats.totalRows} → ${stats.cleanRows}` : datasetText(root, 'parseIssue'));
+  if (ring) ring.style.setProperty('--health-angle', `${score * 3.6}deg`);
+}
+
+function updateButtons(root: HTMLElement, result: SanitizerResult | null): void {
+  const downloadButton = root.querySelector<HTMLButtonElement>('#ls-download-button');
+  const copyButton = root.querySelector<HTMLButtonElement>('#ls-copy-button');
+  const disabled = !result || !result.valid || result.cleanText.length === 0;
+  if (downloadButton) downloadButton.disabled = disabled;
+  if (copyButton) copyButton.disabled = disabled;
+}
+
+function renderResult(root: HTMLElement, result: SanitizerResult | null): void {
+  updateCounts(root, result);
+  updateHealth(root, result);
+  updateButtons(root, result);
+}
+
+function setFormatButtons(root: HTMLElement, format: TranslationFormat): void {
+  root.querySelectorAll<HTMLButtonElement>('.ls-format-button[data-format]').forEach((button) => {
+    const isActive = button.dataset.format === format;
+    button.classList.toggle('is-active', isActive);
+    button.setAttribute('aria-pressed', String(isActive));
+  });
+}
+
+interface AppState {
+  source: string;
+  format: TranslationFormat;
+  fileName: string;
+  result: SanitizerResult | null;
+}
+
+function bindDragEvents(dropZone: HTMLElement, onFile: (file: File) => void): void {
+  dropZone.addEventListener('dragover', (e) => { e.preventDefault(); dropZone.classList.add('is-dragging'); });
+  dropZone.addEventListener('dragleave', () => dropZone.classList.remove('is-dragging'));
+  dropZone.addEventListener('drop', (e) => {
+    e.preventDefault();
+    dropZone.classList.remove('is-dragging');
+    if (e.dataTransfer?.files[0]) onFile(e.dataTransfer.files[0]);
+  });
+}
+
+function bindDropZoneInput(dropZone: HTMLElement, fileInput: HTMLInputElement, onFile: (file: File) => void): void {
+  dropZone.addEventListener('click', (e) => { if (!(e.target as HTMLElement).closest('button')) fileInput.click(); });
+  dropZone.addEventListener('keydown', (e) => { if (e.key === 'Enter' || e.key === ' ') { e.preventDefault(); fileInput.click(); } });
+  bindDragEvents(dropZone, onFile);
+}
+
+function bindExportActions(root: HTMLElement, getState: () => AppState, announce: (msg: string) => void): void {
+  root.querySelector('#ls-download-button')?.addEventListener('click', () => {
+    const state = getState();
+    if (!state.result?.valid) return;
+    const blob = new Blob([state.result.cleanText], { type: state.format === 'csv' ? 'text/csv;charset=utf-8' : 'application/json;charset=utf-8' });
+    const url = URL.createObjectURL(blob);
+    const a = createElement('a');
+    a.href = url;
+    a.download = `${state.fileName}.clean.${state.format === 'csv' ? 'csv' : 'json'}`;
+    a.click();
+    URL.revokeObjectURL(url);
+  });
+  root.querySelector('#ls-copy-button')?.addEventListener('click', async () => {
+    const state = getState();
+    if (!state.result?.valid) return;
+    try {
+      await navigator.clipboard.writeText(state.result.cleanText);
+      announce(datasetText(root, 'copiedMessage'));
+    } catch { announce(datasetText(root, 'parseIssue')); }
+  });
+}
+
+interface AppHandlers {
+  processSource: (source: string, name: string, format?: TranslationFormat) => void;
+  clearWorkspace: () => void;
+  readFile: (file: File) => void;
+}
+
+function bindAppEvents(root: HTMLElement, state: AppState, handlers: AppHandlers, announce: (msg: string) => void): void {
+  const fileInput = root.querySelector<HTMLInputElement>('#ls-file-input');
+  const dropZone = root.querySelector<HTMLElement>('#ls-drop-zone');
+  root.querySelector('#ls-browse-button')?.addEventListener('click', () => fileInput?.click());
+  if (dropZone && fileInput) bindDropZoneInput(dropZone, fileInput, handlers.readFile);
+  fileInput?.addEventListener('change', () => { if (fileInput.files?.[0]) handlers.readFile(fileInput.files[0]); });
+  root.querySelectorAll<HTMLButtonElement>('.ls-format-button').forEach((b) => {
+    b.addEventListener('click', () => {
+      const fmt = b.dataset.format as TranslationFormat;
+      state.format = fmt;
+      setFormatButtons(root, fmt);
+      if (state.source) handlers.processSource(state.source, `${state.fileName}.${fmt}`, fmt);
+    });
+  });
+  root.querySelector('#ls-sample-button')?.addEventListener('click', () => handlers.processSource(SAMPLE_CSV, datasetText(root, 'sampleFileName'), 'csv'));
+  root.querySelector('#ls-clear-button')?.addEventListener('click', handlers.clearWorkspace);
+  bindExportActions(root, () => state, announce);
+}
+
+function createSourceProcessor(root: HTMLElement, state: AppState, announce: (msg: string) => void) {
+  const fileNameEl = root.querySelector<HTMLElement>('#ls-file-name');
+  return (source: string, name: string, format = detectTranslationFormat(name, source)) => {
+    state.source = source;
+    state.fileName = name.replace(/\.[^/.]+$/, '') || 'localization';
+    state.format = format;
+    setFormatButtons(root, format);
+    state.result = sanitizeTranslationFile(source, format);
+    if (fileNameEl) fileNameEl.textContent = name;
+    renderResult(root, state.result);
+    renderIssues(root, state.result);
+    renderPreview(root, state.result);
+    announce(state.result.valid ? `${state.result.stats.cleanRows}` : datasetText(root, 'parseIssue'));
+  };
+}
+
+export function initLocalizationSanitizerApp(): void {
+  const root = document.getElementById('localization-sanitizer-root');
+  if (!root || root.dataset.initialized === 'true') return;
+  root.dataset.initialized = 'true';
+  const fileInput = root.querySelector<HTMLInputElement>('#ls-file-input');
+  const fileNameEl = root.querySelector<HTMLElement>('#ls-file-name');
+  const liveStatus = root.querySelector<HTMLElement>('#ls-live-status');
+  const state: AppState = { source: '', format: 'csv', fileName: 'localization', result: null };
+  const announce = (msg: string) => { if (liveStatus) liveStatus.textContent = msg; };
+  const processSource = createSourceProcessor(root, state, announce);
+  const clearWorkspace = () => {
+    state.source = ''; state.result = null; state.fileName = 'localization';
+    if (fileInput) fileInput.value = '';
+    if (fileNameEl) fileNameEl.textContent = datasetText(root, 'waitingTitle');
+    renderResult(root, null); renderIssues(root, null); renderPreview(root, null); announce('');
+  };
+  const readFile = (file: File) => {
+    const reader = new FileReader();
+    reader.addEventListener('load', () => processSource(String(reader.result || ''), file.name));
+    reader.addEventListener('error', () => announce(datasetText(root, 'parseIssue')));
+    reader.readAsText(file);
+  };
+  bindAppEvents(root, state, { processSource, clearWorkspace, readFile }, announce);
+  renderResult(root, null);
+}

package/src/tool/localizationSanitizer/bibliography.astro

@@ -0,0 +1,6 @@
+---
+import { Bibliography as SharedBibliography } from '@jjlmoya/utils-shared';
+import { bibliographyEntries } from './bibliography';
+---
+
+<SharedBibliography links={bibliographyEntries} />

package/src/tool/localizationSanitizer/bibliography.ts

@@ -0,0 +1,14 @@
+export const bibliographyEntries = [
+  {
+    name: 'Godot ResourceImporterCSVTranslation Documentation',
+    url: 'https://docs.godotengine.org/en/stable/classes/class_resourceimportercsvtranslation.html',
+  },
+  {
+    name: 'Unity Localization CSV Import and Export Documentation',
+    url: 'https://docs.unity3d.com/Packages/com.unity.localization@1.5/manual/CSV.html',
+  },
+  {
+    name: 'RFC 4180 Common Format and MIME Type for CSV Files',
+    url: 'https://datatracker.ietf.org/doc/html/rfc4180',
+  },
+];

package/src/tool/localizationSanitizer/component.astro

@@ -0,0 +1,116 @@
+---
+import type { LocalizationSanitizerUI } from './ui';
+import './localization-sanitizer.css';
+
+interface Props {
+  ui: LocalizationSanitizerUI;
+}
+
+const { ui } = Astro.props;
+---
+
+<div
+  class="ls-root"
+  id="localization-sanitizer-root"
+  data-csv-tab={ui.csvTab}
+  data-json-tab={ui.jsonTab}
+  data-ready-status={ui.readyStatus}
+  data-review-status={ui.reviewStatus}
+  data-empty-cells-label={ui.emptyCellsLabel}
+  data-duplicate-keys-label={ui.duplicateKeysLabel}
+  data-malformed-rows-label={ui.malformedRowsLabel}
+  data-clean-rows-label={ui.cleanRowsLabel}
+  data-no-issues={ui.noIssues}
+  data-empty-issue={ui.emptyIssue}
+  data-duplicate-issue={ui.duplicateIssue}
+  data-malformed-issue={ui.malformedIssue}
+  data-parse-issue={ui.parseIssue}
+  data-row-label={ui.rowLabel}
+  data-column-label={ui.columnLabel}
+  data-key-label={ui.keyLabel}
+  data-sample-file-name={ui.sampleFileName}
+  data-file-type-note={ui.fileTypeNote}
+  data-waiting-title={ui.waitingTitle}
+  data-waiting-subtitle={ui.waitingSubtitle}
+  data-copied-message={ui.copiedMessage}
+>
+  <div class="ls-topline">
+    <div>
+      <span class="ls-kicker">LOCALIZATION QA</span>
+      <strong id="ls-file-name">{ui.waitingTitle}</strong>
+    </div>
+    <span class="ls-privacy-note">{ui.privacyNote}</span>
+  </div>
+
+  <div class="ls-format-bar" aria-label={ui.formatLabel} role="group">
+    <span class="ls-format-label">{ui.formatLabel}</span>
+    <button type="button" class="ls-format-button is-active" data-format="csv" aria-pressed="true">{ui.csvTab}</button>
+    <button type="button" class="ls-format-button" data-format="json" aria-pressed="false">{ui.jsonTab}</button>
+    <button type="button" class="ls-format-button" id="ls-clear-button">{ui.clearButton}</button>
+  </div>
+
+  <section class="ls-drop-panel" id="ls-drop-zone" aria-label={ui.inputLabel} tabindex="0">
+    <input id="ls-file-input" type="file" accept=".csv,.json,text/csv,application/json" hidden aria-label={ui.browseButton} />
+    <div class="ls-drop-mark" aria-hidden="true"><span>CSV</span><span>JSON</span></div>
+    <div class="ls-drop-copy">
+      <strong>{ui.dropTitle}</strong>
+      <span>{ui.dropSubtitle}</span>
+      <span class="ls-file-type-note">{ui.fileTypeNote}</span>
+    </div>
+    <div class="ls-drop-actions">
+      <button type="button" class="ls-button ls-button-primary" id="ls-browse-button">{ui.browseButton}</button>
+      <button type="button" class="ls-button ls-button-quiet" id="ls-sample-button">{ui.sampleButton}</button>
+    </div>
+  </section>
+
+  <div class="ls-workbench">
+    <aside class="ls-inspector">
+      <div class="ls-section-heading">
+        <span class="ls-section-index">01</span>
+        <div><span class="ls-section-eyebrow">INSPECTION</span><h2>{ui.healthLabel}</h2></div>
+      </div>
+      <div class="ls-health-card">
+        <div class="ls-health-ring" id="ls-health-ring"><span id="ls-health-value">--</span></div>
+        <div><strong id="ls-health-status">{ui.waitingTitle}</strong><span id="ls-health-subtitle">{ui.waitingSubtitle}</span></div>
+      </div>
+      <div class="ls-stat-list" aria-live="polite">
+        <div class="ls-stat-row"><span class="ls-stat-dot ls-dot-empty"></span><span>{ui.emptyCellsLabel}</span><strong id="ls-empty-count">0</strong></div>
+        <div class="ls-stat-row"><span class="ls-stat-dot ls-dot-duplicate"></span><span>{ui.duplicateKeysLabel}</span><strong id="ls-duplicate-count">0</strong></div>
+        <div class="ls-stat-row"><span class="ls-stat-dot ls-dot-malformed"></span><span>{ui.malformedRowsLabel}</span><strong id="ls-malformed-count">0</strong></div>
+        <div class="ls-stat-row ls-stat-row-clean"><span class="ls-stat-dot ls-dot-clean"></span><span>{ui.cleanRowsLabel}</span><strong id="ls-clean-count">0</strong></div>
+      </div>
+      <div class="ls-issue-section">
+        <div class="ls-section-heading ls-section-heading-small"><span class="ls-section-index">02</span><h2>{ui.issueListTitle}</h2></div>
+        <div id="ls-issue-list" class="ls-issue-list" aria-live="polite"></div>
+      </div>
+    </aside>
+
+    <section class="ls-preview-panel">
+      <div class="ls-section-heading">
+        <span class="ls-section-index">03</span>
+        <div><span class="ls-section-eyebrow">DATA VIEW</span><h2>{ui.previewTitle}</h2><p>{ui.previewSubtitle}</p></div>
+      </div>
+      <div id="ls-preview" class="ls-preview-frame">
+        <div class="ls-empty-state"><span class="ls-empty-grid" aria-hidden="true"></span><strong>{ui.waitingTitle}</strong><span>{ui.waitingSubtitle}</span></div>
+      </div>
+      <div class="ls-export-card">
+        <div class="ls-export-copy"><span class="ls-section-eyebrow">CLEAN OUTPUT</span><h2>{ui.exportTitle}</h2><p>{ui.exportSubtitle}</p></div>
+        <div class="ls-export-actions">
+          <button type="button" class="ls-button ls-button-primary" id="ls-download-button" disabled>{ui.downloadButton}</button>
+          <button type="button" class="ls-button ls-button-outline" id="ls-copy-button" disabled>{ui.copyButton}</button>
+        </div>
+      </div>
+    </section>
+  </div>
+  <p id="ls-live-status" class="ls-live-status" aria-live="polite"></p>
+</div>
+
+<script>
+  import { initLocalizationSanitizerApp } from './app-client';
+
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', initLocalizationSanitizerApp);
+  } else {
+    initLocalizationSanitizerApp();
+  }
+</script>

package/src/tool/localizationSanitizer/csv-parser.ts

@@ -0,0 +1,95 @@
+import type { ParsedCsvRow } from './types';
+
+interface CsvState {
+  rows: ParsedCsvRow[];
+  row: string[];
+  field: string;
+  inQuotes: boolean;
+  quoteClosed: boolean;
+  malformed: boolean;
+}
+
+function createCsvState(): CsvState {
+  return {
+    rows: [],
+    row: [],
+    field: '',
+    inQuotes: false,
+    quoteClosed: false,
+    malformed: false,
+  };
+}
+
+function flushRow(state: CsvState): void {
+  const values = [...state.row, state.field];
+  if (values.some((value) => value.trim() !== '')) {
+    state.rows.push({ values, malformed: state.malformed });
+  }
+  state.row = [];
+  state.field = '';
+  state.quoteClosed = false;
+  state.malformed = false;
+}
+
+function handleQuotedChar(state: CsvState, character: string, nextCharacter: string): number {
+  if (character === '"' && nextCharacter === '"') {
+    state.field += '"';
+    return 1;
+  }
+  if (character === '"') {
+    state.inQuotes = false;
+    state.quoteClosed = true;
+  } else {
+    state.field += character;
+  }
+  return 0;
+}
+
+function handleUnquotedChar(state: CsvState, character: string, nextCharacter: string): void {
+  if (character === '"') {
+    if (state.field.length === 0) {
+      state.inQuotes = true;
+    } else {
+      state.malformed = true;
+      state.field += character;
+    }
+  } else if (character === ',') {
+    state.row.push(state.field);
+    state.field = '';
+    state.quoteClosed = false;
+  } else if (character === '\n' || (character === '\r' && nextCharacter !== '\n')) {
+    flushRow(state);
+  } else {
+    if (state.quoteClosed) state.malformed = true;
+    state.field += character;
+  }
+}
+
+function processCsvChar(state: CsvState, source: string, index: number): number {
+  const character = source[index] ?? '';
+  const nextCharacter = source[index + 1] ?? '';
+  if (state.inQuotes) {
+    return handleQuotedChar(state, character, nextCharacter);
+  }
+  handleUnquotedChar(state, character, nextCharacter);
+  return 0;
+}
+
+export function parseCsvRows(source: string): ParsedCsvRow[] {
+  const state = createCsvState();
+  for (let index = 0; index < source.length; index += 1) {
+    index += processCsvChar(state, source, index);
+  }
+  if (state.inQuotes) state.malformed = true;
+  if (state.field.length > 0 || state.row.length > 0 || state.malformed) {
+    flushRow(state);
+  }
+  return state.rows;
+}
+
+export function csvEscape(value: string): string {
+  if (/[",\n\r]/.test(value)) {
+    return `"${value.replaceAll('"', '""')}"`;
+  }
+  return value;
+}

package/src/tool/localizationSanitizer/csv-sanitizer.ts

@@ -0,0 +1,98 @@
+import { csvEscape, parseCsvRows } from './csv-parser';
+import { EMPTY_STATS, type IssueInput, type ParsedCsvRow, type SanitizerIssue, type SanitizerResult, type TranslationFormat } from './types';
+
+export function normalizedHeaders(headers: string[]): string[] {
+  return headers.map((header, index) => header.trim() || `column_${index + 1}`);
+}
+
+export function keyColumnIndex(headers: string[]): number {
+  const index = headers.findIndex((header) => /^(key|id|identifier|loc[_-]?key)$/i.test(header.trim()));
+  return index >= 0 ? index : 0;
+}
+
+export function issue(input: IssueInput): SanitizerIssue {
+  return { ...input };
+}
+
+export function emptyResult(format: TranslationFormat, detail: string): SanitizerResult {
+  return {
+    format, valid: false, headers: [], rows: [], cleanText: '',
+    issues: [issue({ kind: 'parse', row: 1, column: '', key: '', detail })],
+    stats: { ...EMPTY_STATS },
+  };
+}
+
+function normalizeCsvRowValues(originalValues: string[], expectedColumns: number): string[] {
+  if (originalValues.length > expectedColumns) {
+    return originalValues.slice(0, expectedColumns - 1).concat(originalValues.slice(expectedColumns - 1).join(','));
+  }
+  return originalValues.concat(Array.from({ length: Math.max(0, expectedColumns - originalValues.length) }, () => ''));
+}
+
+interface CheckRowParams {
+  parsedRow: ParsedCsvRow;
+  rowNumber: number;
+  expectedColumns: number;
+  keyIndex: number;
+  headers: string[];
+}
+
+function checkRowIssues(params: CheckRowParams): { values: string[]; key: string; rowIssues: SanitizerIssue[] } {
+  const { parsedRow, rowNumber, expectedColumns, keyIndex, headers } = params;
+  const values = normalizeCsvRowValues(parsedRow.values, expectedColumns);
+  const key = (values[keyIndex] ?? '').trim();
+  const rowIssues: SanitizerIssue[] = [];
+
+  if (parsedRow.malformed || parsedRow.values.length !== expectedColumns) {
+    rowIssues.push(issue({ kind: 'malformed', row: rowNumber, column: '', key, detail: parsedRow.malformed ? 'unescaped_quote' : `expected_${expectedColumns}_columns` }));
+  }
+  if (!key) {
+    rowIssues.push(issue({ kind: 'empty', row: rowNumber, column: headers[keyIndex] ?? '', key: '', detail: 'empty_key' }));
+  }
+  values.forEach((value, columnIndex) => {
+    if (columnIndex !== keyIndex && value.trim() === '') {
+      rowIssues.push(issue({ kind: 'empty', row: rowNumber, column: headers[columnIndex] ?? '', key, detail: 'empty_translation' }));
+    }
+  });
+
+  return { values, key, rowIssues };
+}
+
+function computeCsvStats(totalRows: number, cleanRowsCount: number, issues: SanitizerIssue[]) {
+  return {
+    totalRows, cleanRows: cleanRowsCount,
+    emptyCells: issues.filter((item) => item.kind === 'empty').length,
+    duplicateKeys: issues.filter((item) => item.kind === 'duplicate').length,
+    malformedRows: new Set(issues.filter((item) => item.kind === 'malformed').map((item) => item.row)).size,
+  };
+}
+
+export function sanitizeCsv(source: string): SanitizerResult {
+  const parsedRows = parseCsvRows(source.replace(/^\uFEFF/, ''));
+  if (parsedRows.length === 0) return emptyResult('csv', 'empty_file');
+
+  const headers = normalizedHeaders(parsedRows[0]?.values ?? []);
+  const keyIndex = keyColumnIndex(headers);
+  const expectedColumns = headers.length;
+  const issues: SanitizerIssue[] = [];
+  const rows: string[][] = [];
+  const seenKeys = new Set<string>();
+
+  parsedRows.slice(1).forEach((parsedRow, sourceIndex) => {
+    const rowNumber = sourceIndex + 2;
+    const { values, key, rowIssues } = checkRowIssues({ parsedRow, rowNumber, expectedColumns, keyIndex, headers });
+    issues.push(...rowIssues);
+    if (key && seenKeys.has(key)) {
+      issues.push(issue({ kind: 'duplicate', row: rowNumber, column: headers[keyIndex] ?? '', key, detail: 'duplicate_key' }));
+    } else if (key) {
+      seenKeys.add(key);
+      rows.push(values);
+    }
+  });
+
+  return {
+    format: 'csv', valid: true, headers, rows,
+    cleanText: [headers, ...rows].map((row) => row.map(csvEscape).join(',')).join('\n'),
+    issues, stats: computeCsvStats(parsedRows.length - 1, rows.length, issues),
+  };
+}