emdash 1.3.0 → 1.3.1

package/src/database/repositories/menu.ts

@@ -16,6 +16,7 @@
 import type { Kysely, Selectable } from "kysely";
 import { ulid } from "ulidx";
 
+import { localeMatches, localeOrder } from "../../i18n/query.js";
 import { invalidateMenuObjectCache } from "../../object-cache/index.js";
 import { withTransaction } from "../transaction.js";
 import type { Database, MenuItemTable, MenuTable } from "../types.js";
@@ -34,6 +35,59 @@ export class MenuGoneError extends Error {
 	}
 }
 
+export class MenuItemParentError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "MenuItemParentError";
+	}
+}
+
+async function validateItemParents(
+	db: Kysely<Database>,
+	menuId: string,
+	changes: ReadonlyArray<{ id: string; parentId: string | null }>,
+	newItemId?: string,
+): Promise<void> {
+	const rows = await db
+		.selectFrom("_emdash_menu_items")
+		.select(["id", "parent_id"])
+		.where("menu_id", "=", menuId)
+		.execute();
+	const parents = new Map(rows.map((row) => [row.id, row.parent_id]));
+	if (newItemId !== undefined) parents.set(newItemId, null);
+
+	const originalParents = new Map(parents);
+	const scopedChanges = changes.filter((change) => parents.has(change.id));
+	// Overlay the whole batch before walking: a valid reorder may temporarily
+	// form a cycle if its entries are considered one at a time.
+	for (const change of scopedChanges) {
+		parents.set(change.id, change.parentId);
+	}
+
+	const validated = new Set<string>();
+	const changedIds = new Set(scopedChanges.map((change) => change.id));
+	for (const id of changedIds) {
+		const parentId = parents.get(id) ?? null;
+		if (id !== newItemId && parentId === originalParents.get(id)) continue;
+		if (parentId !== null && !parents.has(parentId)) {
+			throw new MenuItemParentError("Parent item must exist in the same menu");
+		}
+		const path = new Set<string>();
+		let cursor: string | null = id;
+		while (cursor !== null && !validated.has(cursor)) {
+			if (path.has(cursor)) {
+				throw new MenuItemParentError("A menu item cannot be its own ancestor");
+			}
+			// Deleted ancestors render as roots; unchanged legacy links must not
+			// prevent editing or reordering the remaining menu items.
+			if (!parents.has(cursor)) break;
+			path.add(cursor);
+			cursor = parents.get(cursor) ?? null;
+		}
+		for (const ancestorId of path) validated.add(ancestorId);
+	}
+}
+
 // ---------------------------------------------------------------------------
 // Entity shapes (camelCase — what the API returns)
 // ---------------------------------------------------------------------------
@@ -225,7 +279,8 @@ export class MenuRepository {
 				"m.translation_group",
 			])
 			.orderBy("m.name", "asc");
-		if (options.locale !== undefined) query = query.where("m.locale", "=", options.locale);
+		if (options.locale !== undefined)
+			query = query.where(localeMatches("m.locale", options.locale));
 		const rows = await query.execute();
 
 		return rows.map((row) => ({
@@ -249,12 +304,15 @@ export class MenuRepository {
 	 * is supplied) and to detect AMBIGUOUS_LOCALE situations (`length > 1`).
 	 */
 	async findByName(name: string, options: { locale?: string } = {}): Promise<Menu[]> {
-		let query = this.db
-			.selectFrom("_emdash_menus")
-			.selectAll()
-			.where("name", "=", name)
-			.orderBy("locale", "asc");
-		if (options.locale !== undefined) query = query.where("locale", "=", options.locale);
+		let query = this.db.selectFrom("_emdash_menus").selectAll().where("name", "=", name);
+		if (options.locale !== undefined) {
+			query = query
+				.where(localeMatches("locale", options.locale))
+				.orderBy(localeOrder("locale", options.locale), "asc")
+				.orderBy("id", "asc");
+		} else {
+			query = query.orderBy("locale", "asc");
+		}
 		const rows = await query.execute();
 		return rows.map(rowToMenu);
 	}
@@ -295,7 +353,7 @@ export class MenuRepository {
 			.selectFrom("_emdash_menus")
 			.select("id")
 			.where("name", "=", name)
-			.where("locale", "=", locale)
+			.where(localeMatches("locale", locale))
 			.executeTakeFirst();
 		return row !== undefined;
 	}
@@ -460,6 +518,10 @@ export class MenuRepository {
 	 * item's own id, matching the migration 036 backfill.
 	 */
 	async createItem(menuId: string, locale: string, input: CreateMenuItemInput): Promise<MenuItem> {
+		const id = ulid();
+		if (input.parentId !== undefined) {
+			await validateItemParents(this.db, menuId, [{ id, parentId: input.parentId }], id);
+		}
 		let sortOrder = input.sortOrder ?? 0;
 		if (input.sortOrder === undefined) {
 			const maxOrder = await this.db
@@ -472,7 +534,6 @@ export class MenuRepository {
 			sortOrder = ((maxOrder?.max as number) ?? -1) + 1;
 		}
 
-		const id = ulid();
 		await this.db
 			.insertInto("_emdash_menu_items")
 			.values({
@@ -520,6 +581,9 @@ export class MenuRepository {
 			.where("menu_id", "=", menuId)
 			.executeTakeFirst();
 		if (!existing) return null;
+		if (input.parentId !== undefined) {
+			await validateItemParents(this.db, menuId, [{ id: itemId, parentId: input.parentId }]);
+		}
 
 		const values: Record<string, unknown> = {};
 		if (input.label !== undefined) values.label = input.label;
@@ -634,8 +698,8 @@ export class MenuRepository {
 	 * malicious payload cannot move foreign items into this menu's siblings.
 	 */
 	async reorderItems(menuId: string, items: ReorderItem[]): Promise<MenuItem[]> {
-		invalidateMenuObjectCache();
-		return withTransaction(this.db, async (trx) => {
+		const updated = await withTransaction(this.db, async (trx) => {
+			await validateItemParents(trx, menuId, items);
 			for (const item of items) {
 				await trx
 					.updateTable("_emdash_menu_items")
@@ -653,5 +717,7 @@ export class MenuRepository {
 				.execute();
 			return rows.map(rowToMenuItem);
 		});
+		invalidateMenuObjectCache();
+		return updated;
 	}
 }

package/src/database/repositories/taxonomy-def.ts

@@ -1,5 +1,6 @@
 import { sql, type Kysely } from "kysely";
 
+import { localeMatches, localeOrder } from "../../i18n/query.js";
 import type { Database } from "../types.js";
 
 /**
@@ -20,8 +21,8 @@ export interface TaxonomyStructure {
  * A row that has no group yet, because code without the group table wrote it
  * during a rolling deploy, reads its own copy.
  */
-export function selectTaxonomyDefs(db: Kysely<Database>) {
-	return db
+export function selectTaxonomyDefs(db: Kysely<Database>, locale?: string) {
+	let query = db
 		.selectFrom("_emdash_taxonomy_defs as d")
 		.leftJoin("_emdash_taxonomy_def_groups as g", "g.name", "d.name")
 		.select([
@@ -35,6 +36,12 @@ export function selectTaxonomyDefs(db: Kysely<Database>) {
 			sql<number>`coalesce(g.hierarchical, d.hierarchical)`.as("hierarchical"),
 			sql<string | null>`coalesce(g.collections, d.collections)`.as("collections"),
 		]);
+	if (locale !== undefined) {
+		query = query
+			.where(localeMatches("d.locale", locale))
+			.orderBy(localeOrder("d.locale", locale), "asc");
+	}
+	return query;
 }
 
 /**

package/src/database/repositories/taxonomy.ts

@@ -1,6 +1,8 @@
 import { sql, type Kysely, type Selectable } from "kysely";
 import { ulid } from "ulidx";
 
+import { getLocaleCandidates, getLocaleChainRank, getLocaleRank } from "../../i18n/config.js";
+import { localeMatches, localeOrder } from "../../i18n/query.js";
 import { invalidateTaxonomyObjectCache } from "../../object-cache/index.js";
 import { chunks, SQL_BATCH_SIZE } from "../../utils/chunks.js";
 import { slugify } from "../../utils/slugify.js";
@@ -255,8 +257,11 @@ export class TaxonomyRepository {
 			.selectAll()
 			.where("name", "=", name)
 			.where("slug", "=", slug);
-		if (locale !== undefined) query = query.where("locale", "=", locale);
-		const row = await query.orderBy("locale", "asc").executeTakeFirst();
+		if (locale !== undefined) query = query.where(localeMatches("locale", locale));
+		const row = await query
+			.orderBy(locale !== undefined ? localeOrder("locale", locale) : "locale", "asc")
+			.orderBy("id", "asc")
+			.executeTakeFirst();
 		return row ? this.rowToTaxonomy(row) : null;
 	}
 
@@ -268,7 +273,7 @@ export class TaxonomyRepository {
 			.select("slug")
 			.where("name", "=", name)
 			.where((eb) => eb.or([eb("slug", "=", baseSlug), eb("slug", "like", `${baseSlug}-%`)]));
-		if (locale !== undefined) query = query.where("locale", "=", locale);
+		if (locale !== undefined) query = query.where(localeMatches("locale", locale));
 		const candidates = await query.execute();
 		if (!candidates.some((candidate) => candidate.slug === baseSlug)) return baseSlug;
 
@@ -300,7 +305,7 @@ export class TaxonomyRepository {
 			.orderBy("label", "asc")
 			.orderBy("id", "asc");
 
-		if (options.locale !== undefined) query = query.where("locale", "=", options.locale);
+		if (options.locale !== undefined) query = query.where(localeMatches("locale", options.locale));
 
 		if (options.parentId !== undefined) {
 			if (options.parentId === null) {
@@ -324,7 +329,7 @@ export class TaxonomyRepository {
 			.selectFrom("taxonomies")
 			.selectAll()
 			.where("name", "=", name)
-			.where("locale", "in", locales)
+			.where((eb) => eb.or(locales.map((candidate) => localeMatches("locale", candidate))))
 			.orderBy("sort_order", "asc")
 			.orderBy("label", "asc")
 			.orderBy("id", "asc")
@@ -335,7 +340,13 @@ export class TaxonomyRepository {
 			const term = this.rowToTaxonomy(row);
 			const group = term.translationGroup ?? term.id;
 			const current = selected.get(group);
-			if (!current || term.locale === locale) selected.set(group, term);
+			if (
+				!current ||
+				getLocaleChainRank(term.locale, [locale, defaultLocale]) <
+					getLocaleChainRank(current.locale, [locale, defaultLocale])
+			) {
+				selected.set(group, term);
+			}
 		}
 		return [...selected.values()].toSorted(
 			(a, b) =>
@@ -347,7 +358,7 @@ export class TaxonomyRepository {
 		const limit = Math.max(1, Math.min(options.limit ?? 50, 100));
 		let query = this.db.selectFrom("taxonomies").selectAll().where("name", "=", name);
 
-		if (options.locale !== undefined) query = query.where("locale", "=", options.locale);
+		if (options.locale !== undefined) query = query.where(localeMatches("locale", options.locale));
 
 		if (options.parentId !== undefined) {
 			query =
@@ -397,7 +408,7 @@ export class TaxonomyRepository {
 			.orderBy("sort_order", "asc")
 			.orderBy("label", "asc")
 			.orderBy("id", "asc");
-		if (locale !== undefined) query = query.where("locale", "=", locale);
+		if (locale !== undefined) query = query.where(localeMatches("locale", locale));
 
 		const rows = await query.execute();
 		return rows.map((row) => this.rowToTaxonomy(row));
@@ -742,10 +753,25 @@ export class TaxonomyRepository {
 			.where("content_taxonomies.entry_id", "=", entryGroup);
 
 		if (taxonomyName) query = query.where("taxonomies.name", "=", taxonomyName);
-		if (locale !== undefined) query = query.where("taxonomies.locale", "=", locale);
+		if (locale !== undefined) query = query.where(localeMatches("taxonomies.locale", locale));
 
 		const rows = await query.orderBy("taxonomies.locale", "asc").execute();
-		return rows.map((row) => this.rowToTaxonomy(row));
+		const terms = rows.map((row) => this.rowToTaxonomy(row));
+		if (locale === undefined) return terms;
+		const selected = new Map<string, Taxonomy>();
+		for (const term of terms) {
+			const group = term.translationGroup ?? term.id;
+			const current = selected.get(group);
+			if (
+				!current ||
+				getLocaleRank(term.locale, locale) < getLocaleRank(current.locale, locale) ||
+				(getLocaleRank(term.locale, locale) === getLocaleRank(current.locale, locale) &&
+					term.id < current.id)
+			) {
+				selected.set(group, term);
+			}
+		}
+		return [...selected.values()];
 	}
 
 	async getTermAssignmentsForEntry(
@@ -777,11 +803,18 @@ export class TaxonomyRepository {
 			byGroup.set(row.assignment_group, variants);
 		}
 
+		const chain = [locale, ...(defaultLocale !== locale ? [defaultLocale] : [])];
+		const chainLimit =
+			getLocaleChainRank(defaultLocale, chain) + getLocaleCandidates(defaultLocale).length;
 		return Array.from(byGroup, ([translationGroup, variants]) => {
-			const term =
-				variants.find((variant) => variant.locale === locale) ??
-				variants.find((variant) => variant.locale === defaultLocale) ??
-				null;
+			const candidates = variants
+				.filter((variant) => getLocaleChainRank(variant.locale, chain) < chainLimit)
+				.toSorted(
+					(a, b) =>
+						getLocaleChainRank(a.locale, chain) - getLocaleChainRank(b.locale, chain) ||
+						a.id.localeCompare(b.id),
+				);
+			const term = candidates[0] ?? null;
 			return {
 				translationGroup,
 				term,

package/src/database/repositories/types.ts

@@ -31,6 +31,8 @@ export interface CreateContentInput {
 }
 
 export interface UpdateContentInput {
+	/** Stored locale, supplied by the content handler for alias-aware slug checks. */
+	locale?: string;
 	data?: Record<string, unknown>;
 	status?: string;
 	slug?: string | null;
@@ -41,6 +43,8 @@ export interface UpdateContentInput {
 	/** Revision author, separate from entry ownership. */
 	revisionAuthorId?: string | null;
 	primaryBylineId?: string | null;
+	/** `null` drops the entry's draft revision pointer. */
+	draftRevisionId?: null;
 }
 
 /** SEO fields for content items */
@@ -450,3 +454,10 @@ export class ContentMutationConflictError extends Error {
 		this.name = "ContentMutationConflictError";
 	}
 }
+
+export class ContentSlugConflictError extends Error {
+	constructor() {
+		super("The slug is already used by another content entry");
+		this.name = "ContentSlugConflictError";
+	}
+}

package/src/emdash-runtime.ts

@@ -61,6 +61,7 @@ import {
 	MIGRATION_RACE_WAIT_MS,
 	MigrationFailedError,
 	MigrationLockHeldError,
+	MigrationRowLimitError,
 } from "./database/migrations/runner.js";
 import { AuditRepository } from "./database/repositories/audit.js";
 import { CommentRepository } from "./database/repositories/comment.js";
@@ -632,7 +633,7 @@ interface DbHolder {
 	 * through the migration advisory lock (#1744). Entries expire after
 	 * DB_INIT_FAILURE_BACKOFF_MS; a successful init clears them.
 	 */
-	failures: Map<string, { at: number; message: string }>;
+	failures: Map<string, { at: number; message: string; cause?: unknown }>;
 }
 const globalSymbolStore = globalThis as Record<symbol, unknown>;
 function getDbHolder(): DbHolder {
@@ -660,6 +661,24 @@ function getDbHolder(): DbHolder {
  */
 const DB_INIT_FAILURE_BACKOFF_MS = 30_000;
 
+/**
+ * The most content rows auto mode migrates inside a deployed Worker request.
+ * Datetime normalization (079) issues about one statement per row it changes,
+ * a paid Worker invocation stops at 10,000 subrequests and 30 s of CPU by
+ * default, and the migrations around it need some of that budget too.
+ */
+const WORKER_AUTO_MIGRATION_CONTENT_ROW_LIMIT = 5_000;
+
+/** Local development enforces no Worker limits, and Node has none. */
+function autoMigrationContentRowLimit(): number | undefined {
+	if (import.meta.env.DEV) return undefined;
+	const onWorkers =
+		typeof navigator !== "undefined" &&
+		typeof navigator.userAgent === "string" &&
+		navigator.userAgent.includes("Cloudflare-Workers");
+	return onWorkers ? WORKER_AUTO_MIGRATION_CONTENT_ROW_LIMIT : undefined;
+}
+
 /**
  * Auto-seed runs at most once per isolate per database. Its lock + "done" set
  * live on globalThis (same bundler-duplication reasoning as the db cache) so a
@@ -2422,6 +2441,7 @@ export class EmDashRuntime {
 			if (Date.now() - failure.at < DB_INIT_FAILURE_BACKOFF_MS) {
 				throw new Error(
 					`Database initialization is backing off after a recent migration failure: ${failure.message}`,
+					{ cause: failure.cause },
 				);
 			}
 			// Expired — drop it so the map only ever holds active backoffs.
@@ -2442,18 +2462,25 @@ export class EmDashRuntime {
 				const db = new Kysely<Database>({ dialect, log: kyselyLogOption() });
 
 				try {
-					await enforceRuntimeMigrationPolicy(db, deps.migrationMode ?? "auto");
+					await enforceRuntimeMigrationPolicy(db, deps.migrationMode ?? "auto", {
+						contentRowLimit: autoMigrationContentRowLimit(),
+					});
 				} catch (error) {
-					// Only a failed migration run, or a lock its holder left behind,
-					// backs off. Waiting behind a slow concurrent migrator, pending
-					// migrations in check mode, and errors from the applied-migration
-					// check on an up-to-date database (a lost connection, an
-					// unavailable replica) stay retryable, so the next request tries
-					// again.
-					if (error instanceof MigrationFailedError || error instanceof MigrationLockHeldError) {
+					// Only a failed migration run, a lock its holder left behind, or
+					// content migrations too large for a request back off. Waiting
+					// behind a slow concurrent migrator, pending migrations in check
+					// mode, and errors from the applied-migration check on an
+					// up-to-date database (a lost connection, an unavailable replica)
+					// stay retryable, so the next request tries again.
+					if (
+						error instanceof MigrationFailedError ||
+						error instanceof MigrationLockHeldError ||
+						error instanceof MigrationRowLimitError
+					) {
 						holder.failures.set(cacheKey, {
 							at: Date.now(),
-							message: error instanceof Error ? error.message : String(error),
+							message: error.message,
+							cause: error,
 						});
 					}
 					// Every attempt builds a fresh dialect/pool; close it or each

package/src/fields/image.ts

@@ -6,6 +6,7 @@ const mediaSchema = z.object({
 	id: z.string(),
 	src: z.string().optional(),
 	alt: z.string().optional(),
+	caption: z.string().optional(),
 	width: z.number().optional(),
 	height: z.number().optional(),
 	filename: z.string().optional(),

package/src/i18n/config.ts

@@ -8,6 +8,8 @@
 export interface I18nConfig {
 	defaultLocale: string;
 	locales: string[];
+	/** Astro locale codes mapped to their canonical content locale paths. */
+	localeAliases?: Record<string, string>;
 	fallback?: Record<string, string>;
 	prefixDefaultLocale?: boolean;
 }
@@ -36,13 +38,60 @@ export function getI18nConfig(): I18nConfig | null {
 	return configStore()[I18N_CONFIG_KEY] ?? null;
 }
 
-/** Match a locale to the exact casing used by the site configuration. */
-export function resolveConfiguredLocale(locale: string): string {
-	const config = getI18nConfig();
+/** Match a locale path or Astro code to the canonical content locale. */
+export function resolveConfiguredLocale(
+	locale: string,
+	config: I18nConfig | null = getI18nConfig(),
+): string {
+	const configured = config?.locales.find(
+		(candidate) => candidate.toLowerCase() === locale.toLowerCase(),
+	);
+	if (configured) return configured;
+
+	const aliased = Object.entries(config?.localeAliases ?? {}).find(
+		([code]) => code.toLowerCase() === locale.toLowerCase(),
+	)?.[1];
+	if (aliased === undefined) return locale;
+
 	return (
-		config?.locales.find((configured) => configured.toLowerCase() === locale.toLowerCase()) ??
-		locale
+		config?.locales.find((candidate) => candidate.toLowerCase() === aliased.toLowerCase()) ??
+		aliased
+	);
+}
+
+/** Stored locale spellings for one configured locale, in read-preference order. */
+export function getLocaleCandidates(locale: string): string[] {
+	const canonical = resolveConfiguredLocale(locale);
+	const candidates = [canonical];
+	const seen = new Set([canonical.toLowerCase()]);
+	for (const code of Object.keys(getI18nConfig()?.localeAliases ?? {})) {
+		if (resolveConfiguredLocale(code) === canonical && !seen.has(code.toLowerCase())) {
+			candidates.push(code);
+			seen.add(code.toLowerCase());
+		}
+	}
+	return candidates;
+}
+
+/** Rank a stored row's locale for a lookup by path or code. */
+export function getLocaleRank(stored: string, requested: string): number {
+	const candidates = getLocaleCandidates(requested);
+	const rank = candidates.findIndex(
+		(candidate) => candidate.toLowerCase() === stored.toLowerCase(),
 	);
+	return rank === -1 ? candidates.length : rank;
+}
+
+/** Rank stored locale variants before moving to the next fallback locale. */
+export function getLocaleChainRank(stored: string, chain: readonly string[]): number {
+	let offset = 0;
+	for (const locale of chain) {
+		const candidates = getLocaleCandidates(locale);
+		const rank = getLocaleRank(stored, locale);
+		if (rank < candidates.length) return offset + rank;
+		offset += candidates.length;
+	}
+	return offset;
 }
 
 /** Whether a string matches the locale-code subset accepted by EmDash. */
@@ -59,10 +108,8 @@ export function resolveContentCreateLocale(
 		if (typeof locale !== "string") {
 			throw new Error("Invalid locale code: expected a string");
 		}
-		const configured = config?.locales.find(
-			(candidate) => candidate.toLowerCase() === locale.toLowerCase(),
-		);
-		if (configured) return configured;
+		const configured = resolveConfiguredLocale(locale, config);
+		if (config?.locales.includes(configured)) return configured;
 		if (!isValidLocaleCode(locale)) {
 			throw new Error(`Invalid locale code: "${locale}"`);
 		}
@@ -93,13 +140,14 @@ export function getFallbackChain(locale: string): string[] {
 	const config = getI18nConfig();
 	if (!config) return [locale];
 
+	locale = resolveConfiguredLocale(locale, config);
 	const chain: string[] = [locale];
 	let current = locale;
 	const visited = new Set<string>([locale]);
 
 	while (config.fallback?.[current]) {
 		// eslint-disable-next-line typescript/no-unnecessary-type-assertion -- noUncheckedIndexedAccess
-		const next = config.fallback[current]!;
+		const next = resolveConfiguredLocale(config.fallback[current]!, config);
 		if (visited.has(next)) break; // prevent cycles
 		chain.push(next);
 		visited.add(next);

package/src/i18n/normalize.ts

@@ -1,4 +1,4 @@
-import type { I18nConfig } from "./config.js";
+import { resolveConfiguredLocale, type I18nConfig } from "./config.js";
 
 export interface AstroLocaleObject {
 	path: string;
@@ -15,7 +15,11 @@ export interface AstroI18nInput {
 export function normalizeAstroI18n(config: AstroI18nInput | null | undefined): I18nConfig | null {
 	if (!config) return null;
 
-	return {
+	const aliases = config.locales.flatMap((locale) =>
+		typeof locale === "string" ? [] : locale.codes.map((code) => [code, locale.path]),
+	);
+	const normalized: I18nConfig = {
+		...(aliases.length > 0 ? { localeAliases: Object.fromEntries(aliases) } : {}),
 		defaultLocale: config.defaultLocale,
 		locales: config.locales.map((locale) => (typeof locale === "string" ? locale : locale.path)),
 		fallback: config.fallback
@@ -28,4 +32,14 @@ export function normalizeAstroI18n(config: AstroI18nInput | null | undefined): I
 		prefixDefaultLocale:
 			typeof config.routing === "object" ? (config.routing.prefixDefaultLocale ?? false) : false,
 	};
+	normalized.defaultLocale = resolveConfiguredLocale(config.defaultLocale, normalized);
+	if (normalized.fallback) {
+		normalized.fallback = Object.fromEntries(
+			Object.entries(normalized.fallback).map(([from, to]) => [
+				resolveConfiguredLocale(from, normalized),
+				resolveConfiguredLocale(to, normalized),
+			]),
+		);
+	}
+	return normalized;
 }

package/src/i18n/query.ts

@@ -0,0 +1,47 @@
+import { sql, type SqlBool } from "kysely";
+
+import { getI18nConfig, getLocaleCandidates } from "./config.js";
+
+/** Match both canonical paths and code-stamped rows written by older versions. */
+export function localeMatches(column: string, locale: string) {
+	const candidates = getLocaleCandidates(locale);
+	if (candidates.length === 1) return sql<SqlBool>`${sql.ref(column)} = ${candidates[0]}`;
+	return sql<SqlBool>`${sql.ref(column)} IN (${sql.join(candidates)})`;
+}
+
+/** Prefer the configured path, then its Astro codes in configuration order. */
+export function localeOrder(column: string, locale: string) {
+	const candidates = getLocaleCandidates(locale);
+	return sql<number>`CASE lower(${sql.ref(column)}) ${sql.join(
+		candidates.map((candidate, rank) => sql`WHEN ${candidate.toLowerCase()} THEN ${sql.lit(rank)}`),
+		sql` `,
+	)} ELSE ${sql.lit(candidates.length)} END`;
+}
+
+/** Compare locale columns without losing rows stored under an Astro code. */
+export function canonicalLocaleColumn(column: string) {
+	const aliases = (getI18nConfig()?.locales ?? []).flatMap((locale) =>
+		getLocaleCandidates(locale)
+			.slice(1)
+			.map((code) => ({ code, locale })),
+	);
+	if (aliases.length === 0) return sql<string>`${sql.ref(column)}`;
+	return sql<string>`CASE lower(${sql.ref(column)}) ${sql.join(
+		aliases.map(({ code, locale }) => sql`WHEN ${code.toLowerCase()} THEN ${locale.toLowerCase()}`),
+		sql` `,
+	)} ELSE lower(${sql.ref(column)}) END`;
+}
+
+/** Rank a row's code within its own configured locale; paths always rank first. */
+export function storedLocaleOrder(column: string) {
+	const aliases = (getI18nConfig()?.locales ?? []).flatMap((locale) =>
+		getLocaleCandidates(locale)
+			.slice(1)
+			.map((code, index) => ({ code, rank: index + 1 })),
+	);
+	if (aliases.length === 0) return sql<number>`0`;
+	return sql<number>`CASE lower(${sql.ref(column)}) ${sql.join(
+		aliases.map(({ code, rank }) => sql`WHEN ${code.toLowerCase()} THEN ${sql.lit(rank)}`),
+		sql` `,
+	)} ELSE 0 END`;
+}

package/src/i18n/resolve.ts

@@ -8,7 +8,12 @@
  */
 
 import { getRequestContext } from "../request-context.js";
-import { getFallbackChain, getI18nConfig, isI18nEnabled } from "./config.js";
+import {
+	getFallbackChain,
+	getI18nConfig,
+	isI18nEnabled,
+	resolveConfiguredLocale,
+} from "./config.js";
 
 /**
  * Resolve the locale to use for a query given an optional explicit value.
@@ -16,9 +21,9 @@ import { getFallbackChain, getI18nConfig, isI18nEnabled } from "./config.js";
  * treat that as "do not filter by locale".
  */
 export function resolveLocale(explicit?: string): string | undefined {
-	if (explicit !== undefined) return explicit;
+	if (explicit !== undefined) return resolveConfiguredLocale(explicit);
 	const ctxLocale = getRequestContext()?.locale;
-	if (ctxLocale !== undefined) return ctxLocale;
+	if (ctxLocale !== undefined) return resolveConfiguredLocale(ctxLocale);
 	const cfg = getI18nConfig();
 	if (cfg && isI18nEnabled()) return cfg.defaultLocale;
 	return undefined;

package/src/import/wxr-taxonomies.ts

@@ -34,6 +34,7 @@ import {
 } from "../database/repositories/taxonomy-def.js";
 import { TaxonomyRepository } from "../database/repositories/taxonomy.js";
 import type { Database } from "../database/types.js";
+import { localeMatches, localeOrder } from "../i18n/query.js";
 import { invalidateTermCache } from "../taxonomies/index.js";
 
 /**
@@ -292,8 +293,8 @@ async function findExistingTerms(
 			.where((eb) =>
 				eb.or(batch.map((d) => eb.and([eb("name", "=", d.taxonomyName), eb("slug", "=", d.slug)]))),
 			)
-			.$if(locale !== undefined, (qb) => qb.where("locale", "=", locale!))
-			.orderBy("locale", "asc")
+			.$if(locale !== undefined, (qb) => qb.where(localeMatches("locale", locale!)))
+			.orderBy(locale !== undefined ? localeOrder("locale", locale) : "locale", "asc")
 			.execute();
 
 		for (const row of batchRows) {