emdash 0.8.0 → 0.10.0

package/src/taxonomies/index.ts

@@ -1,105 +1,134 @@
 /**
- * Runtime API for taxonomies
+ * Runtime API for taxonomies.
  *
- * Provides functions to query taxonomy definitions and terms.
+ * All helpers are locale-aware. When a locale is not passed explicitly we fall
+ * back to the request context or the configured `defaultLocale` (see
+ * `i18n/resolve.ts`).
+ *
+ * Because `content_taxonomies.taxonomy_id` stores the translation_group (not a
+ * specific term id), the joins here are `taxonomies.translation_group =
+ * content_taxonomies.taxonomy_id` + filter by `taxonomies.locale`, which picks
+ * the right per-locale term.
  */
 
+import { resolveLocale, resolveLocaleChain } from "../i18n/resolve.js";
 import { getDb } from "../loader.js";
-import { requestCached, setRequestCacheEntry } from "../request-cache.js";
+import { peekRequestCache, requestCached, setRequestCacheEntry } from "../request-cache.js";
 import { chunks, SQL_BATCH_SIZE } from "../utils/chunks.js";
 import { isMissingTableError } from "../utils/db-errors.js";
 import type { TaxonomyDef, TaxonomyTerm, TaxonomyTermRow } from "./types.js";
 
+export interface TaxonomyQueryOptions {
+	locale?: string;
+}
+
 /**
  * No-op — kept for API compatibility.
- *
- * Used to invalidate a worker-lifetime "has any term assignments?" probe.
- * That probe added a query on every cold isolate to save one query on
- * sites with zero term assignments (i.e. the wrong tradeoff), so we
- * dropped it. The batch term join below returns an empty map for empty
- * sites at the same cost as the probe, without the pre-check.
  */
 export function invalidateTermCache(): void {
 	// Intentionally empty.
 }
 
 /**
- * Get all taxonomy definitions
+ * Get every taxonomy definition. Definitions are per-locale (one row per
+ * locale inside the same translation_group) — by default we resolve to the
+ * active locale.
  */
-export async function getTaxonomyDefs(): Promise<TaxonomyDef[]> {
-	return requestCached("taxonomy-defs:all", async () => {
+export async function getTaxonomyDefs(options: TaxonomyQueryOptions = {}): Promise<TaxonomyDef[]> {
+	const locale = resolveLocale(options.locale);
+	return requestCached(`taxonomy-defs:${locale ?? "*"}`, async () => {
 		const db = await getDb();
-
-		const rows = await db.selectFrom("_emdash_taxonomy_defs").selectAll().execute();
-
-		return rows.map((row) => ({
-			id: row.id,
-			name: row.name,
-			label: row.label,
-			labelSingular: row.label_singular ?? undefined,
-			hierarchical: row.hierarchical === 1,
-			collections: row.collections ? JSON.parse(row.collections) : [],
-		}));
+		let query = db.selectFrom("_emdash_taxonomy_defs").selectAll();
+		if (locale !== undefined) query = query.where("locale", "=", locale);
+		const rows = await query.execute();
+		return rows.map(rowToTaxonomyDef);
 	});
 }
 
 /**
- * Get a single taxonomy definition by name
+ * Get a single taxonomy definition by name. Uses the fallback chain so even
+ * if there is no translation for the active locale we still return something.
+ *
+ * If `getTaxonomyDefs()` has already loaded the full list in this request
+ * (which happens during entry-term hydration on every page that renders a
+ * collection), search the matching def in memory rather than running a
+ * second query against `_emdash_taxonomy_defs`.
  */
-export async function getTaxonomyDef(name: string): Promise<TaxonomyDef | null> {
-	return requestCached(`taxonomy-def:${name}`, async () => {
-		const db = await getDb();
+export async function getTaxonomyDef(
+	name: string,
+	options: TaxonomyQueryOptions = {},
+): Promise<TaxonomyDef | null> {
+	const chain = resolveLocaleChain(options.locale);
+	const peekKey = `taxonomy-defs:${resolveLocale(options.locale) ?? "*"}`;
+	const allDefs = peekRequestCache<TaxonomyDef[]>(peekKey);
+	if (allDefs) {
+		const defs = await allDefs;
+		if (chain.length === 0) return defs.find((d) => d.name === name) ?? null;
+		for (const locale of chain) {
+			const found = defs.find((d) => d.name === name && d.locale === locale);
+			if (found) return found;
+		}
+		return null;
+	}
 
-		const row = await db
-			.selectFrom("_emdash_taxonomy_defs")
-			.selectAll()
-			.where("name", "=", name)
-			.executeTakeFirst();
+	return requestCached(`taxonomy-def:${name}:${chain.join(",")}`, async () => {
+		const db = await getDb();
 
-		if (!row) return null;
+		if (chain.length === 0) {
+			const row = await db
+				.selectFrom("_emdash_taxonomy_defs")
+				.selectAll()
+				.where("name", "=", name)
+				.orderBy("locale", "asc")
+				.executeTakeFirst();
+			return row ? rowToTaxonomyDef(row) : null;
+		}
 
-		return {
-			id: row.id,
-			name: row.name,
-			label: row.label,
-			labelSingular: row.label_singular ?? undefined,
-			hierarchical: row.hierarchical === 1,
-			collections: row.collections ? JSON.parse(row.collections) : [],
-		};
+		for (const locale of chain) {
+			const row = await db
+				.selectFrom("_emdash_taxonomy_defs")
+				.selectAll()
+				.where("name", "=", name)
+				.where("locale", "=", locale)
+				.executeTakeFirst();
+			if (row) return rowToTaxonomyDef(row);
+		}
+		return null;
 	});
 }
 
 /**
- * Get all terms for a taxonomy (as tree for hierarchical, flat for tags)
+ * All terms of a taxonomy in a specific locale (flat for non-hierarchical,
+ * tree for hierarchical).
  */
-export async function getTaxonomyTerms(taxonomyName: string): Promise<TaxonomyTerm[]> {
-	return requestCached(`taxonomy-terms:${taxonomyName}`, async () => {
+export async function getTaxonomyTerms(
+	taxonomyName: string,
+	options: TaxonomyQueryOptions = {},
+): Promise<TaxonomyTerm[]> {
+	const locale = resolveLocale(options.locale);
+	return requestCached(`taxonomy-terms:${taxonomyName}:${locale ?? "*"}`, async () => {
 		const db = await getDb();
 
-		// Get taxonomy definition to check if hierarchical
-		const def = await getTaxonomyDef(taxonomyName);
+		const def = await getTaxonomyDef(taxonomyName, options);
 		if (!def) return [];
 
-		// Get all terms for this taxonomy
-		const rows = await db
+		let termsQuery = db
 			.selectFrom("taxonomies")
 			.selectAll()
 			.where("name", "=", taxonomyName)
-			.orderBy("label", "asc")
-			.execute();
+			.orderBy("label", "asc");
+		if (locale !== undefined) termsQuery = termsQuery.where("locale", "=", locale);
+		const rows = await termsQuery.execute();
 
-		// Count entries for each term
+		// Counts are keyed by translation_group (what the pivot stores).
 		const countsResult = await db
 			.selectFrom("content_taxonomies")
 			.select(["taxonomy_id"])
 			.select((eb) => eb.fn.count<number>("entry_id").as("count"))
 			.groupBy("taxonomy_id")
 			.execute();
-
 		const counts = new Map<string, number>();
-		for (const row of countsResult) {
-			counts.set(row.taxonomy_id, row.count);
-		}
+		for (const row of countsResult) counts.set(row.taxonomy_id, row.count);
 
 		const flatTerms: TaxonomyTermRow[] = rows.map((row) => ({
 			id: row.id,
@@ -108,12 +137,11 @@ export async function getTaxonomyTerms(taxonomyName: string): Promise<TaxonomyTe
 			label: row.label,
 			parent_id: row.parent_id,
 			data: row.data,
+			locale: row.locale,
+			translation_group: row.translation_group,
 		}));
 
-		// If hierarchical, build tree. Otherwise return flat
-		if (def.hierarchical) {
-			return buildTree(flatTerms, counts);
-		}
+		if (def.hierarchical) return buildTree(flatTerms, counts);
 
 		return flatTerms.map((term) => ({
 			id: term.id,
@@ -121,50 +149,71 @@ export async function getTaxonomyTerms(taxonomyName: string): Promise<TaxonomyTe
 			slug: term.slug,
 			label: term.label,
 			children: [],
-			count: counts.get(term.id) ?? 0,
+			count: counts.get(term.translation_group ?? term.id) ?? 0,
+			locale: term.locale,
+			translationGroup: term.translation_group,
 		}));
 	});
 }
 
 /**
- * Get a single term by taxonomy and slug
+ * Get a single term by (taxonomy, slug). Honours the fallback chain — if the
+ * slug exists in a fallback locale, we return that row (useful for deep-linking
+ * to a term page when the translation is missing).
  */
-export async function getTerm(taxonomyName: string, slug: string): Promise<TaxonomyTerm | null> {
+export async function getTerm(
+	taxonomyName: string,
+	slug: string,
+	options: TaxonomyQueryOptions = {},
+): Promise<TaxonomyTerm | null> {
 	const db = await getDb();
+	const chain = resolveLocaleChain(options.locale);
 
-	const row = await db
-		.selectFrom("taxonomies")
-		.selectAll()
-		.where("name", "=", taxonomyName)
-		.where("slug", "=", slug)
-		.executeTakeFirst();
+	let row: Awaited<ReturnType<ReturnType<typeof selectTerm>["executeTakeFirst"]>>;
+	const selectTerm = () =>
+		db
+			.selectFrom("taxonomies")
+			.selectAll()
+			.where("name", "=", taxonomyName)
+			.where("slug", "=", slug);
+
+	if (chain.length === 0) {
+		row = await selectTerm().orderBy("locale", "asc").executeTakeFirst();
+	} else {
+		row = undefined;
+		for (const locale of chain) {
+			row = await selectTerm().where("locale", "=", locale).executeTakeFirst();
+			if (row) break;
+		}
+	}
 
 	if (!row) return null;
 
-	// Get entry count
 	const countResult = await db
 		.selectFrom("content_taxonomies")
 		.select((eb) => eb.fn.count<number>("entry_id").as("count"))
-		.where("taxonomy_id", "=", row.id)
+		.where("taxonomy_id", "=", row.translation_group ?? row.id)
 		.executeTakeFirst();
-
 	const count = countResult?.count ?? 0;
 
-	// Get children if hierarchical
-	const childRows = await db
+	let childrenQuery = db
 		.selectFrom("taxonomies")
 		.selectAll()
 		.where("parent_id", "=", row.id)
-		.orderBy("label", "asc")
-		.execute();
+		.orderBy("label", "asc");
+	const termLocale = row.locale;
+	if (termLocale) childrenQuery = childrenQuery.where("locale", "=", termLocale);
+	const childRows = await childrenQuery.execute();
 
-	const children = childRows.map((child) => ({
+	const children = childRows.map<TaxonomyTerm>((child) => ({
 		id: child.id,
 		name: child.name,
 		slug: child.slug,
 		label: child.label,
 		parentId: child.parent_id ?? undefined,
 		children: [],
+		locale: child.locale,
+		translationGroup: child.translation_group,
 	}));
 
 	return {
@@ -176,89 +225,75 @@ export async function getTerm(taxonomyName: string, slug: string): Promise<Taxon
 		description: row.data ? JSON.parse(row.data).description : undefined,
 		children,
 		count,
+		locale: row.locale,
+		translationGroup: row.translation_group,
 	};
 }
 
 /**
- * Get terms assigned to an entry
+ * Terms assigned to a content entry, resolved into the active locale. Terms
+ * whose translation_group lacks a row in the requested locale are omitted.
  */
 export function getEntryTerms(
 	collection: string,
 	entryId: string,
 	taxonomyName?: string,
+	options: TaxonomyQueryOptions = {},
 ): Promise<TaxonomyTerm[]> {
-	return requestCached(`terms:${collection}:${entryId}:${taxonomyName ?? "*"}`, async () => {
-		const db = await getDb();
+	const locale = resolveLocale(options.locale);
+	return requestCached(
+		`terms:${collection}:${entryId}:${taxonomyName ?? "*"}:${locale ?? "*"}`,
+		async () => {
+			const db = await getDb();
 
-		let query = db
-			.selectFrom("content_taxonomies")
-			.innerJoin("taxonomies", "taxonomies.id", "content_taxonomies.taxonomy_id")
-			.selectAll("taxonomies")
-			.where("content_taxonomies.collection", "=", collection)
-			.where("content_taxonomies.entry_id", "=", entryId);
-
-		if (taxonomyName) {
-			query = query.where("taxonomies.name", "=", taxonomyName);
-		}
+			let query = db
+				.selectFrom("content_taxonomies")
+				.innerJoin("taxonomies", "taxonomies.translation_group", "content_taxonomies.taxonomy_id")
+				.selectAll("taxonomies")
+				.where("content_taxonomies.collection", "=", collection)
+				.where("content_taxonomies.entry_id", "=", entryId);
 
-		const rows = await query.execute();
+			if (taxonomyName) query = query.where("taxonomies.name", "=", taxonomyName);
+			if (locale !== undefined) query = query.where("taxonomies.locale", "=", locale);
 
-		return rows.map((row) => ({
-			id: row.id,
-			name: row.name,
-			slug: row.slug,
-			label: row.label,
-			parentId: row.parent_id ?? undefined,
-			children: [],
-		}));
-	});
+			const rows = await query.execute();
+			return rows.map<TaxonomyTerm>((row) => ({
+				id: row.id,
+				name: row.name,
+				slug: row.slug,
+				label: row.label,
+				parentId: row.parent_id ?? undefined,
+				children: [],
+				locale: row.locale,
+				translationGroup: row.translation_group,
+			}));
+		},
+	);
 }
 
 /**
- * Get terms for multiple entries in a single query (batched API)
- *
- * This is more efficient than calling getEntryTerms for each entry
- * when you need terms for a list of entries.
- *
- * @param collection - The collection type (e.g., "posts")
- * @param entryIds - Array of entry IDs
- * @param taxonomyName - The taxonomy name (e.g., "categories")
- * @returns Map from entry ID to array of terms
+ * Terms for multiple entries of one taxonomy, single query.
  */
 export async function getTermsForEntries(
 	collection: string,
 	entryIds: string[],
 	taxonomyName: string,
+	options: TaxonomyQueryOptions = {},
 ): Promise<Map<string, TaxonomyTerm[]>> {
 	const result = new Map<string, TaxonomyTerm[]>();
-
-	// Initialize all entry IDs with empty arrays so callers can always
-	// expect the key to be present.
 	const uniqueIds = [...new Set(entryIds)];
-	for (const id of uniqueIds) {
-		result.set(id, []);
-	}
-
-	if (uniqueIds.length === 0) {
-		return result;
-	}
+	for (const id of uniqueIds) result.set(id, []);
+	if (uniqueIds.length === 0) return result;
 
 	const db = await getDb();
+	const locale = resolveLocale(options.locale);
 
-	// Chunk the IN clause so we stay below D1's ~100 bound-parameter limit
-	// (and equivalent limits on other dialects). Matches getContentBylinesMany.
-	//
-	// Sites with no term assignments get back empty rows for one query —
-	// the previous "has any term assignments" probe spent a round-trip on
-	// every request to save that single query on empty sites, which is
-	// backwards. Pre-migration databases (content_taxonomies missing) fall
-	// through to the `isMissingTableError` catch and return empties.
 	for (const chunk of chunks(uniqueIds, SQL_BATCH_SIZE)) {
 		let rows;
 		try {
-			rows = await db
+			let query = db
 				.selectFrom("content_taxonomies")
-				.innerJoin("taxonomies", "taxonomies.id", "content_taxonomies.taxonomy_id")
+				.innerJoin("taxonomies", "taxonomies.translation_group", "content_taxonomies.taxonomy_id")
 				.select([
 					"content_taxonomies.entry_id",
 					"taxonomies.id",
@@ -266,18 +301,20 @@ export async function getTermsForEntries(
 					"taxonomies.slug",
 					"taxonomies.label",
 					"taxonomies.parent_id",
+					"taxonomies.locale",
+					"taxonomies.translation_group",
 				])
 				.where("content_taxonomies.collection", "=", collection)
 				.where("content_taxonomies.entry_id", "in", chunk)
-				.where("taxonomies.name", "=", taxonomyName)
-				.execute();
+				.where("taxonomies.name", "=", taxonomyName);
+			if (locale !== undefined) query = query.where("taxonomies.locale", "=", locale);
+			rows = await query.execute();
 		} catch (error) {
 			if (isMissingTableError(error)) return result;
 			throw error;
 		}
 
 		for (const row of rows) {
-			const entryId = row.entry_id;
 			const term: TaxonomyTerm = {
 				id: row.id,
 				name: row.name,
@@ -285,12 +322,11 @@ export async function getTermsForEntries(
 				label: row.label,
 				parentId: row.parent_id ?? undefined,
 				children: [],
+				locale: row.locale,
+				translationGroup: row.translation_group,
 			};
-
-			const terms = result.get(entryId);
-			if (terms) {
-				terms.push(term);
-			}
+			const terms = result.get(row.entry_id);
+			if (terms) terms.push(term);
 		}
 	}
 
@@ -298,57 +334,29 @@ export async function getTermsForEntries(
 }
 
 /**
- * Batch-fetch terms for multiple entries across ALL taxonomies in a single query.
- *
- * Returns a Map keyed by entry ID, where each value is a Record keyed by
- * taxonomy name with the matching terms as an array. Used by
- * getEmDashCollection to eagerly hydrate `entry.data.terms` and avoid
- * the N+1 pattern that callers hit when they loop and call getEntryTerms.
- *
- * Pre-migration databases (content_taxonomies missing) return an empty
- * Map — the join falls through to the `isMissingTableError` branch.
+ * Batch-fetch terms for multiple entries across ALL taxonomies in one query.
+ * Primes the request-cache for subsequent per-entry calls to `getEntryTerms`.
  */
 export async function getAllTermsForEntries(
 	collection: string,
 	entryIds: string[],
+	options: TaxonomyQueryOptions = {},
 ): Promise<Map<string, Record<string, TaxonomyTerm[]>>> {
 	const result = new Map<string, Record<string, TaxonomyTerm[]>>();
-
-	// Initialize unique entry IDs with empty objects so callers can always
-	// expect the key to be present. Deduping also reduces wasted bound
-	// parameters when a caller accidentally passes duplicates.
 	const uniqueIds = [...new Set(entryIds)];
-	for (const id of uniqueIds) {
-		result.set(id, {});
-	}
-
-	if (uniqueIds.length === 0) {
-		return result;
-	}
+	for (const id of uniqueIds) result.set(id, {});
+	if (uniqueIds.length === 0) return result;
 
 	const db = await getDb();
+	const locale = resolveLocale(options.locale);
+	const applicableTaxonomyNames = await getCollectionTaxonomyNames(collection, { locale });
 
-	// Look up which taxonomies apply to this collection. Used below to
-	// seed empty arrays for taxonomies the entry has no terms in — so
-	// callers (including the pre-populated getEntryTerms cache) get a
-	// deterministic `[]` back rather than a cache miss that triggers a DB
-	// round-trip just to confirm "no terms".
-	const applicableTaxonomyNames = await getCollectionTaxonomyNames(collection);
-
-	// Chunk the IN clause to stay below D1's ~100 bound-parameter limit
-	// (and equivalent limits on other dialects). Matches getContentBylinesMany.
-	//
-	// Previously we did a separate "has any assignments" probe to skip the
-	// join on empty sites. That traded one query per request for a query
-	// saved only on empty sites — backwards. Now the join runs directly
-	// (returning zero rows cheaply) and pre-migration databases are caught
-	// by the `isMissingTableError` branch below.
 	for (const chunk of chunks(uniqueIds, SQL_BATCH_SIZE)) {
 		let rows;
 		try {
-			rows = await db
+			let query = db
 				.selectFrom("content_taxonomies")
-				.innerJoin("taxonomies", "taxonomies.id", "content_taxonomies.taxonomy_id")
+				.innerJoin("taxonomies", "taxonomies.translation_group", "content_taxonomies.taxonomy_id")
 				.select([
 					"content_taxonomies.entry_id",
 					"taxonomies.id",
@@ -356,15 +364,18 @@ export async function getAllTermsForEntries(
 					"taxonomies.slug",
 					"taxonomies.label",
 					"taxonomies.parent_id",
+					"taxonomies.locale",
+					"taxonomies.translation_group",
 				])
 				.where("content_taxonomies.collection", "=", collection)
 				.where("content_taxonomies.entry_id", "in", chunk)
-				.orderBy("taxonomies.label", "asc")
-				.execute();
+				.orderBy("taxonomies.label", "asc");
+			if (locale !== undefined) query = query.where("taxonomies.locale", "=", locale);
+			rows = await query.execute();
 		} catch (error) {
 			if (isMissingTableError(error)) {
 				for (const id of uniqueIds) {
-					primeEntryTermsCache(collection, id, {}, applicableTaxonomyNames);
+					primeEntryTermsCache(collection, id, {}, applicableTaxonomyNames, locale);
 				}
 				return result;
 			}
@@ -372,7 +383,6 @@ export async function getAllTermsForEntries(
 		}
 
 		for (const row of rows) {
-			const entryId = row.entry_id;
 			const term: TaxonomyTerm = {
 				id: row.id,
 				name: row.name,
@@ -380,25 +390,19 @@ export async function getAllTermsForEntries(
 				label: row.label,
 				parentId: row.parent_id ?? undefined,
 				children: [],
+				locale: row.locale,
+				translationGroup: row.translation_group,
 			};
-
-			const byTaxonomy = result.get(entryId);
+			const byTaxonomy = result.get(row.entry_id);
 			if (!byTaxonomy) continue;
 			const existing = byTaxonomy[row.name];
-			if (existing) {
-				existing.push(term);
-			} else {
-				byTaxonomy[row.name] = [term];
-			}
+			if (existing) existing.push(term);
+			else byTaxonomy[row.name] = [term];
 		}
 	}
 
-	// Prime the request-scoped cache so legacy callers of getEntryTerms
-	// (which still work per-entry) hit the in-memory cache instead of
-	// re-querying. This is what gives us the N+1 win in existing templates
-	// without requiring them to be rewritten.
 	for (const [entryId, byTaxonomy] of result) {
-		primeEntryTermsCache(collection, entryId, byTaxonomy, applicableTaxonomyNames);
+		primeEntryTermsCache(collection, entryId, byTaxonomy, applicableTaxonomyNames, locale);
 	}
 
 	return result;
@@ -410,9 +414,12 @@ export async function getAllTermsForEntries(
  *
  * Returns an empty list when taxonomies haven't been defined yet.
  */
-async function getCollectionTaxonomyNames(collection: string): Promise<string[]> {
+async function getCollectionTaxonomyNames(
+	collection: string,
+	options: TaxonomyQueryOptions,
+): Promise<string[]> {
 	try {
-		const defs = await getTaxonomyDefs();
+		const defs = await getTaxonomyDefs(options);
 		return defs.filter((d) => d.collections.includes(collection)).map((d) => d.name);
 	} catch (error) {
 		if (isMissingTableError(error)) return [];
@@ -437,44 +444,64 @@ function primeEntryTermsCache(
 	entryId: string,
 	byTaxonomy: Record<string, TaxonomyTerm[]>,
 	applicableTaxonomyNames: string[],
+	locale: string | undefined,
 ): void {
-	// Seed every applicable taxonomy with at least [] so
-	// getEntryTerms(collection, id, "tag") doesn't miss the cache when an
-	// entry has no tags.
+	const localeKey = locale ?? "*";
 	for (const name of applicableTaxonomyNames) {
-		setRequestCacheEntry(`terms:${collection}:${entryId}:${name}`, byTaxonomy[name] ?? []);
+		setRequestCacheEntry(
+			`terms:${collection}:${entryId}:${name}:${localeKey}`,
+			byTaxonomy[name] ?? [],
+		);
 	}
-	// Also seed individual names that show up in data but aren't listed
-	// as applicable (e.g. taxonomy reassigned to a different collection
-	// since the terms were written).
 	for (const [name, terms] of Object.entries(byTaxonomy)) {
-		setRequestCacheEntry(`terms:${collection}:${entryId}:${name}`, terms);
+		setRequestCacheEntry(`terms:${collection}:${entryId}:${name}:${localeKey}`, terms);
 	}
-	// Flattened `*` view — all terms across all taxonomies in one array.
 	const allTerms = Object.values(byTaxonomy).flat();
-	setRequestCacheEntry(`terms:${collection}:${entryId}:*`, allTerms);
+	setRequestCacheEntry(`terms:${collection}:${entryId}:*:${localeKey}`, allTerms);
 }
 
 /**
- * Get entries by term (wraps getEmDashCollection)
+ * Get entries by term. Both the lookup (term slug in the active locale) and
+ * the content query respect the active locale.
  */
 export async function getEntriesByTerm(
 	collection: string,
 	taxonomyName: string,
 	termSlug: string,
+	options: TaxonomyQueryOptions = {},
 ): Promise<Array<{ id: string; data: Record<string, unknown> }>> {
 	const { getEmDashCollection } = await import("../query.js");
 
-	// Build options as the expected type — getEmDashCollection accepts
-	// a generic options object with `where` for filtering by taxonomy
-	const options: Record<string, unknown> = {
+	const queryOptions: Record<string, unknown> = {
 		where: { [taxonomyName]: termSlug },
 	};
-	const { entries } = await getEmDashCollection(collection, options);
-
+	if (options.locale !== undefined) queryOptions.locale = options.locale;
+	const { entries } = await getEmDashCollection(collection, queryOptions);
 	return entries;
 }
 
+function rowToTaxonomyDef(row: {
+	id: string;
+	name: string;
+	label: string;
+	label_singular: string | null;
+	hierarchical: number;
+	collections: string | null;
+	locale: string;
+	translation_group: string | null;
+}): TaxonomyDef {
+	return {
+		id: row.id,
+		name: row.name,
+		label: row.label,
+		labelSingular: row.label_singular ?? undefined,
+		hierarchical: row.hierarchical === 1,
+		collections: row.collections ? JSON.parse(row.collections) : [],
+		locale: row.locale,
+		translationGroup: row.translation_group,
+	};
+}
+
 /**
  * Build tree structure from flat terms
  */
@@ -482,7 +509,6 @@ function buildTree(flatTerms: TaxonomyTermRow[], counts: Map<string, number>): T
 	const map = new Map<string, TaxonomyTerm>();
 	const roots: TaxonomyTerm[] = [];
 
-	// First pass: create nodes
 	for (const term of flatTerms) {
 		map.set(term.id, {
 			id: term.id,
@@ -492,11 +518,12 @@ function buildTree(flatTerms: TaxonomyTermRow[], counts: Map<string, number>): T
 			parentId: term.parent_id ?? undefined,
 			description: term.data ? JSON.parse(term.data).description : undefined,
 			children: [],
-			count: counts.get(term.id) ?? 0,
+			count: counts.get(term.translation_group ?? term.id) ?? 0,
+			locale: term.locale,
+			translationGroup: term.translation_group,
 		});
 	}
 
-	// Second pass: build tree
 	for (const term of map.values()) {
 		if (term.parentId && map.has(term.parentId)) {
 			map.get(term.parentId)!.children.push(term);