Fuzzy first sync: push machine translations up, pull proofread answers down

CHANGELOG.md

@@ -4,6 +4,26 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 versioning follows [Semantic Versioning](https://semver.org/). While at 0.x,
 minor releases may break. Releases are tagged `vX.Y.Z` and publish from CI.
 
+## [Unreleased]
+
+### Added
+
+- `pushTranslations`, which carries every held catalogue of a supported language
+  to the platform with its fuzzy flags, trimmed to the template so a stale file
+  revives nothing, and holding back every answer the platform has settled so a
+  push never overwrites a reviewer.
+- `addLanguage` on the platform seam, and the push adds and fills a supported
+  language the platform does not list yet.
+- Upload pacing, one paced retry when the platform answers its rate refusal.
+- A fuzzy aware merge, where a reviewed answer settles a fuzzy one and a fuzzy
+  export never replaces a settled answer, restored answers keeping their flag.
+- `unreviewed`, which names the answers still carrying the fuzzy flag.
+
+### Changed
+
+- Clearing a fuzzy flag alone now counts as a meaningful change, so a pull
+  writes an approval home even when the text did not move.
+
 ## [0.2.0] - 2026-08-24
 
 ### Added

src/build.ts

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: Apache-2.0
 
 export { compileCatalog, serializeCatalog } from './compile.js'
-export { mismatched, orphaned, untranslated } from './gates.js'
+export { mismatched, orphaned, unreviewed, untranslated } from './gates.js'
 export { pinnedVersions, resolvedVersions } from './lockfile.js'
 export { goMessages, goString, messages, pot } from './pot.js'
 export type { Found, PotOptions } from './pot.js'

src/gates.ts

@@ -3,6 +3,7 @@
 import { po } from 'gettext-parser'
 
 import { METADATA, held, keyOf } from './catalog.js'
+import { fuzzyOf } from './merge.js'
 
 /**
  * Returns every key a catalogue carries a filled translation for.
@@ -59,6 +60,23 @@ export function orphaned(source: string, template: string): string[] {
 	return carried
 }
 
+/**
+ * Returns every message whose answer still carries the fuzzy flag.
+ * @param source - The catalogue as PO text.
+ * @returns The keys answered but not yet reviewed.
+ */
+export function unreviewed(source: string): string[] {
+	const waiting: string[] = []
+	for (const [context, entries] of Object.entries(po.parse(source).translations)) {
+		for (const [msgid, entry] of Object.entries(entries)) {
+			if (msgid !== METADATA && fuzzyOf(entry) && entry.msgstr.some((form) => form !== '')) {
+				waiting.push(keyOf(context, msgid))
+			}
+		}
+	}
+	return waiting
+}
+
 /** NAMED is a placeholder naming what goes into it. */
 const NAMED = /%\(([A-Za-z_][A-Za-z0-9_]*)\)[bcdieEfgGosuxX]/g
 

src/merge.ts

@@ -18,6 +18,19 @@ export function localeOf(code: string): string {
 	return region === undefined ? language : `${language}-${region.toUpperCase()}`
 }
 
+/**
+ * Returns the code the platform names a language by, bare when its region repeats it.
+ * @param locale - The language as a catalogue file names it.
+ * @returns The code as the platform writes it.
+ */
+export function platformCodeOf(locale: string): string {
+	const [language, region] = locale.split('-')
+	if (region === undefined || region.toLowerCase() === language) {
+		return language
+	}
+	return `${language}-${region.toLowerCase()}`
+}
+
 /**
  * Returns the language the site knows a platform code as, if it knows one.
  * @param code - The language as the platform names it.
@@ -117,22 +130,62 @@ export function namedByTemplate(incoming: string, template: string): string {
 }
 
 /**
- * Returns the forms a catalogue keeps, taking each answered form over an empty one.
- * @param ours - The forms as committed.
- * @param theirs - The forms the platform exported.
- * @returns The forms, answered wherever either side answers them.
+ * Reports whether an entry carries the fuzzy flag.
+ * @param entry - The entry as parsed.
+ * @returns Whether the entry is fuzzy.
  */
-function mergedForms(ours: string[], theirs: string[]): string[] {
-	const held: string[] = []
-	for (let at = 0; at < Math.max(ours.length, theirs.length); at += 1) {
-		const arrived = theirs[at] ?? ''
-		held.push(arrived === '' ? (ours[at] ?? '') : arrived)
+export function fuzzyOf(entry: GetTextTranslation): boolean {
+	return /(^|,)\s*fuzzy\s*(,|$)/.test(entry.comments?.flag ?? '')
+}
+
+/**
+ * Writes whether an entry is fuzzy, leaving its other flags standing.
+ * @param entry - The entry to mark.
+ * @param fuzzy - Whether the entry is fuzzy.
+ */
+function flaggedFuzzy(entry: GetTextTranslation, fuzzy: boolean): void {
+	const others = (entry.comments?.flag ?? '')
+		.split(',')
+		.map((flag) => flag.trim())
+		.filter((flag) => flag !== '' && flag !== 'fuzzy')
+	const flags = fuzzy ? [...others, 'fuzzy'] : others
+	if (flags.length > 0) {
+		entry.comments = { ...entry.comments, flag: flags.join(', ') }
+		return
+	}
+	if (entry.comments !== undefined) {
+		delete entry.comments.flag
 	}
-	return held
 }
 
 /**
- * Writes one committed answer into a catalogue that arrived without every form of it.
+ * Returns the forms a merge keeps and which sides answered them.
+ * @param preferred - The forms that win wherever they are answered.
+ * @param fallback - The forms filling what the preferred side holds empty.
+ * @returns The forms and whether each side supplied any of them.
+ */
+function mergedForms(
+	preferred: string[],
+	fallback: string[],
+): { forms: string[], tookPreferred: boolean, tookFallback: boolean } {
+	const forms: string[] = []
+	let tookPreferred = false
+	let tookFallback = false
+	for (let at = 0; at < Math.max(preferred.length, fallback.length); at += 1) {
+		const wanted = preferred[at] ?? ''
+		if (wanted !== '') {
+			forms.push(wanted)
+			tookPreferred = true
+			continue
+		}
+		forms.push(fallback[at] ?? '')
+		tookFallback = tookFallback || (fallback[at] ?? '') !== ''
+	}
+	return { forms, tookPreferred, tookFallback }
+}
+
+/**
+ * Writes one committed answer into a catalogue that arrived without every settled form of it.
  * @param held - The catalogue the platform exported, as parsed.
  * @param context - The context the answer sits under.
  * @param msgid - The message the answer belongs to.
@@ -151,7 +204,33 @@ function restoring(
 		return
 	}
 	arrived.msgid_plural ??= entry.msgid_plural
-	arrived.msgstr = mergedForms(entry.msgstr, arrived.msgstr)
+	const settled = settledForms(entry, arrived)
+	arrived.msgstr = settled.forms
+	flaggedFuzzy(arrived, settled.fuzzy)
+}
+
+/**
+ * Returns the merged forms of one answered message and whether they stay fuzzy.
+ * @param entry - The committed answer.
+ * @param arrived - The answer the platform exported.
+ * @returns The forms to keep and the fuzzy state they carry.
+ */
+function settledForms(
+	entry: GetTextTranslation,
+	arrived: GetTextTranslation,
+): { forms: string[], fuzzy: boolean } {
+	const ourFuzzy = fuzzyOf(entry)
+	const theirFuzzy = fuzzyOf(arrived)
+	const oursFirst = theirFuzzy && !ourFuzzy
+	const preferred = oursFirst ? entry.msgstr : arrived.msgstr
+	const fallback = oursFirst ? arrived.msgstr : entry.msgstr
+	const merged = mergedForms(preferred, fallback)
+	const preferredFuzzy = oursFirst ? ourFuzzy : theirFuzzy
+	const fallbackFuzzy = oursFirst ? theirFuzzy : ourFuzzy
+	return {
+		forms: merged.forms,
+		fuzzy: (merged.tookPreferred && preferredFuzzy) || (merged.tookFallback && fallbackFuzzy),
+	}
 }
 
 /**
@@ -176,21 +255,46 @@ export function keepingAnswers(current: string, incoming: string, template: stri
 	return po.compile(held, COMPILED).toString()
 }
 
+/**
+ * Returns a catalogue without the messages an export already answers and nobody may overwrite.
+ * @param source - The catalogue as committed.
+ * @param exported - The catalogue the platform exported.
+ * @returns The catalogue, holding only what the platform has not settled.
+ */
+export function withoutSettled(source: string, exported: string): string {
+	const theirs = po.parse(exported).translations
+	const held = po.parse(source)
+	for (const [context, entries] of Object.entries(held.translations)) {
+		for (const [msgid, entry] of Object.entries(entries)) {
+			const arrived = ownEntry(theirs[context], msgid)
+			if (msgid === METADATA || arrived === undefined || fuzzyOf(arrived)) {
+				continue
+			}
+			if (arrived.msgstr.length > 0 && arrived.msgstr.every((form) => form !== '')) {
+				delete held.translations[context][msgid]
+				continue
+			}
+			entry.msgstr = entry.msgstr.map((form, at) => arrived.msgstr[at] || form)
+		}
+	}
+	return po.compile(held, COMPILED).toString()
+}
+
 /** Answers is what one language's export carries, keyed by context and message. */
-type Answers = Record<string, Record<string, string[]>>
+type Answers = Record<string, Record<string, { msgstr: string[], fuzzy: boolean }>>
 
 /**
  * Returns the translations a catalogue holds, without the headers an export restamps.
  * @param source - The catalogue as PO text.
- * @returns The translations, keyed by context and message.
+ * @returns The translations with their fuzzy state, keyed by context and message.
  */
 function answersOf(source: string): Answers {
 	const held: Answers = {}
 	for (const [context, entries] of Object.entries(po.parse(source).translations).sort()) {
 		held[context] = {}
 		for (const [msgid, entry] of Object.entries(entries).sort()) {
 			if (msgid !== METADATA) {
-				held[context][msgid] = entry.msgstr
+				held[context][msgid] = { msgstr: entry.msgstr, fuzzy: fuzzyOf(entry) }
 			}
 		}
 	}