Improve handling of singular strings in plural-form batches

When batches contain both singular and plural entries, the AI
sometimes returns `<f0>...<fN>` form tags for singular strings
(e.g., "30 files"). The parser accepted all forms, and the
post-validator blanked them for placeholder mismatches.

- Clarify prompt to show both formats when batch has mixed entries
- Extract only f0 when AI returns form tags for singular entries
- Initialize singular entries with 1 msgstr slot instead of pluralCount

Author: mrcasual

config/prompt.md

@@ -3,21 +3,21 @@ You are a professional translator specializing in software localization. Your ta
 ### Instructions
 
 1. **Translate each XML tag** and respond with the translated content in the same XML structure.
-2. **CRITICAL — Preserve placeholders exactly**: The translation MUST contain the **exact same placeholders** as the source (%s, %d, %1$s, etc.) — no more, no fewer. If none in source, none in translation. Use ASCII %, never ％.
+2. **CRITICAL — Preserve placeholders exactly**: The translation MUST contain the **exact same placeholders** as the source (%s, %d, %1$s, etc.) — no more, no fewer. If none in source, none in translation. Do NOT add %d or any placeholder that is not in the source. Always use standard ASCII percent sign (%), never the fullwidth ％ (U+FF05).
 3. **Preserve bracket placeholders**: [example], [product], {value} — keep as-is. Do NOT convert to %s/%1$s.
 4. **Preserve bracket tags**: [strong], [/strong], [link], [/link] — keep as-is. Do NOT convert to HTML.
 5. **Preserve formatting**: Keep line breaks, HTML tags, trailing whitespace unchanged.
 6. **Context/comments**: Use provided context and comment attributes.
-7. **Plural forms**: Provide exactly {{PLURAL_COUNT}} DISTINCT translations (f0, f1, ...). Rules:
-   - Arabic(6): f0=zero(plural), f1=one(singular,drop %d), f2=two(dual تان/تين,drop %d), f3=few(plural), f4=many(singular+%d), f5=other(singular+%d)
-   - Russian/Polish(3): f0=singular, f1=paucal(2-4), f2=plural(5+)
-   - French(2): f0=0+1, f1=2+
-   - Japanese/Chinese/Korean(1): f0 only, MUST keep %d
+7. **Singular vs. plural entries**:
+   - **Singular entries** (no `<singular>`/`<plural>` tags): Provide ONE translation. Do NOT use `<f0>`, `<f1>`, etc. — just `<t i="N">translation</t>`. Translate the string literally, even if it contains a number (e.g., "30 files" → translate as-is, do NOT split into plural forms).
+   - **Plural entries** (with `<singular>` and `<plural>` tags): Provide exactly {{PLURAL_COUNT}} DISTINCT translations using `<f0>`, `<f1>`, etc. Only use placeholders that exist in the source — if the source uses [number] instead of %d, use [number] in ALL forms, never add %d. Rules:
+     - Arabic(6): f0=zero(plural), f1=one(singular, may drop %d if source has it), f2=two(dual تان/تين, may drop %d if source has it), f3=few(plural), f4=many(plural), f5=other(plural)
+     - Russian/Polish(3): f0=singular, f1=paucal(2-4), f2=plural(5+)
+     - French(2): f0=0+1, f1=2+
+     - Japanese/Chinese/Korean(1): f0 only, MUST keep all placeholders
 
 ### Output Format
 
-```xml
-<t i="N">translation</t>
-```
+Singular: `<t i="N">translation</t>`
 
 Plural: `<t i="N"><f0>...</f0><f1>...</f1>...</t>`

src/utils/xmlTranslation.js

@@ -75,11 +75,12 @@ export function buildXmlPrompt(batch, targetLang, pluralCount, dictionaryMatches
 	prompt += xmlTags + '\n\nRespond:\n';
 
 	if (hasPlurals) {
-		prompt += `For entries with <singular> and <plural> tags, provide ${pluralCount} translations:\n\n`;
-
 		const formTags = Array.from({ length: pluralCount }, (_, i) => `<f${i}>translation for form ${i}</f${i}>`).join('');
 
-		prompt += `Format: <t i="N">${formTags}</t>\n`;
+		prompt += `For entries with <singular> and <plural> tags, provide ${pluralCount} plural forms:\n`;
+		prompt += `Format: <t i="N">${formTags}</t>\n\n`;
+		prompt += `For all other entries (no <singular>/<plural>), provide a single translation:\n`;
+		prompt += `Format: <t i="N">translation</t>\n`;
 	} else {
 		prompt += `Format: <t i="N">translation</t>\n`;
 	}
@@ -200,7 +201,7 @@ function validatePluralForms(forms, originalMsgid, expectedCount, itemId, logger
 export function parseXmlResponse(xmlResponse, batch, pluralCount, logger, dictionaryCount = 0, verbosityLevel = 1) {
 	const result = batch.map((entry) => ({
 		msgid: entry.msgid,
-		msgstr: Array(pluralCount).fill(''),
+		msgstr: Array(entry.msgid_plural ? pluralCount : 1).fill(''),
 	}));
 
 	const validationStats = createEmptyValidationStats();
@@ -249,8 +250,9 @@ export function parseXmlResponse(xmlResponse, batch, pluralCount, logger, dictio
 			}
 
 			const hasFormTags = block.includes('<f0>');
+			const isSingularEntry = !batch[batchIndex].msgid_plural;
 
-			if (hasFormTags) {
+			if (hasFormTags && !isSingularEntry) {
 				const forms = [];
 
 				for (let i = 0; i < pluralCount; i++) {
@@ -278,6 +280,17 @@ export function parseXmlResponse(xmlResponse, batch, pluralCount, logger, dictio
 				}
 
 				result[batchIndex].msgstr = correctedForms;
+			} else if (hasFormTags && isSingularEntry) {
+				// AI incorrectly returned plural forms for a singular entry.
+				// Extract only form 0 and discard the rest.
+				const formRegex = /<f0>(.*?)<\/f0>/s;
+				const formMatch = block.match(formRegex);
+
+				if (formMatch) {
+					const translation = normalizeNbsp(decodeXmlEntities(formMatch[1]), batch[batchIndex].msgid);
+
+					result[batchIndex].msgstr = [translation];
+				}
 			} else {
 				const contentMatch = block.match(/<t[^>]*>(.*?)<\/t>/s);
 

tests/integration/openai-with-dictionary.test.js

@@ -223,7 +223,7 @@ describe('OpenAI Provider with Dictionary Integration', () => {
 		expect(promptMessage).toContain('<source i="1" placeholders="none">item</source>');
 		expect(promptMessage).toContain('<singular>One item</singular>');
 		expect(promptMessage).toContain('<plural>%d items</plural>');
-		expect(promptMessage).toContain('For entries with <singular> and <plural> tags, provide 2 translations');
+		expect(promptMessage).toContain('For entries with <singular> and <plural> tags, provide 2 plural forms');
 	});
 
 	it('should handle API errors gracefully with dictionary', async () => {

tests/unit/placeholderValidation.test.js

@@ -539,4 +539,36 @@ describe('placeholder validation', () => {
 			expect(translations[0].msgstr[0]).toBe('لا عناصر');
 		});
 	});
+
+	describe('singular entries with form tags', () => {
+		it('should extract only f0 when AI returns plural forms for a singular entry', () => {
+			// AI incorrectly returns <f0>...<f5> for a singular string like "30 files".
+			const batch = [{ msgid: '30 files' }];
+			const forms = ['30 ملفًا', '30 ملف', '30 ملفان', '%d ملفات', '%d ملفًا', '%d ملف'];
+			const { translations } = parseXmlResponse(xml([forms]), batch, 6, mockLogger);
+
+			expect(translations[0].msgstr).toHaveLength(1);
+			expect(translations[0].msgstr[0]).toBe('30 ملفًا');
+		});
+
+		it('should initialize singular entries with 1 msgstr slot', () => {
+			const batch = [{ msgid: 'Hello' }, { msgid: 'One item', msgid_plural: '%d items' }];
+			const { translations } = parseXmlResponse('', batch, 6, mockLogger);
+
+			expect(translations[0].msgstr).toHaveLength(1);
+			expect(translations[1].msgstr).toHaveLength(6);
+		});
+
+		it('should not trigger placeholder warnings for discarded plural forms', () => {
+			const { logger, warnings } = createSpyLogger();
+			const batch = [{ msgid: '30 files' }];
+			// AI adds %d in forms 3-5 — these should be discarded, not warned about.
+			const forms = ['30 ملفًا', '30 ملف', '30 ملفان', '%d ملفات', '%d ملفًا', '%d ملف'];
+			parseXmlResponse(xml([forms]), batch, 6, logger);
+
+			const placeholderWarnings = warnings.filter((w) => w.includes('Placeholder mismatch'));
+
+			expect(placeholderWarnings).toHaveLength(0);
+		});
+	});
 });

tests/unit/xmlTranslationWithDictionary.test.js

@@ -59,7 +59,7 @@ describe('XML Translation with Dictionary', () => {
 			expect(result.xmlPrompt).toContain('<source i="1" placeholders="none">item</source>');
 			expect(result.xmlPrompt).toContain('<singular>One item</singular>');
 			expect(result.xmlPrompt).toContain('<plural>%d items</plural>');
-			expect(result.xmlPrompt).toContain('For entries with <singular> and <plural> tags, provide 2 translations');
+			expect(result.xmlPrompt).toContain('For entries with <singular> and <plural> tags, provide 2 plural forms');
 		});
 
 		it('should escape XML in dictionary terms', () => {