@jant/core 0.6.15 → 0.7.0

package/src/lib/resolve-config.ts

@@ -12,15 +12,18 @@
 import type { Bindings } from "../types/bindings.js";
 import type { AppConfig } from "../types/config.js";
 import { CONFIG_FIELDS } from "../types/config.js";
-import type { FeedKind } from "../types/constants.js";
+import type { ArchiveLayout, FeedKind } from "../types/constants.js";
 import { ASSET_BASE_SEGMENT, getPublicAssetBasePath } from "./asset-path.js";
+import { resolveDiscoverMode } from "./discover.js";
 import {
   getAuthSecret,
   getConfiguredSingleSiteUrl,
   getConfiguredStorageDriver,
+  getDiscoverDefault,
   getEnvString,
 } from "./env.js";
-import { getPublicUrlForProvider, getMediaUrl } from "./image.js";
+import { parseLanguageList } from "../i18n/locales.js";
+import { getPublicUrlForProvider, getMediaUrl, getImageUrl } from "./image.js";
 import { normalizeTimeZone } from "./timezones.js";
 import { getSiteOrigin, getSitePathPrefix, normalizeSiteUrl } from "./url.js";
 
@@ -147,6 +150,13 @@ function parseFeedKind(value: string, fallback: FeedKind): FeedKind {
   return value === "latest" || value === "featured" ? value : fallback;
 }
 
+function parseArchiveLayout(
+  value: string,
+  fallback: ArchiveLayout,
+): ArchiveLayout {
+  return value === "list" || value === "grid" ? value : fallback;
+}
+
 /**
  * Build a complete AppConfig from environment bindings and DB settings.
  *
@@ -198,6 +208,7 @@ export function resolveConfig(
   // Resolve avatar URL from storage key
   const siteAvatar = allSettings["SITE_AVATAR"] ?? "";
   let siteAvatarUrl = "";
+  let siteAvatarThumbUrl = "";
   if (siteAvatar) {
     const publicUrl = getPublicUrlForProvider(
       storageDriver,
@@ -206,6 +217,17 @@ export function resolveConfig(
       localPublicUrl,
     );
     siteAvatarUrl = getMediaUrl(siteAvatar, publicUrl, sitePathPrefix);
+    // The header and drawer marks render this at 32px and 24px, on every page,
+    // in parallel with the render-blocking stylesheet. An untransformed avatar
+    // is whatever the author uploaded — commonly a 512px PNG — so it competes
+    // for the critical path with tens of times the bytes it can use. 128px
+    // still covers a high-DPR header and a theme that enlarges the mark.
+    siteAvatarThumbUrl = getImageUrl(siteAvatarUrl, imageTransformUrl, {
+      width: 128,
+      quality: 80,
+      format: "auto",
+      fit: "scale-down",
+    });
   }
 
   // Description is "explicit" when set in DB or ENV (not just the default)
@@ -216,6 +238,16 @@ export function resolveConfig(
     ? !!dbDescription
     : !!envDescription;
 
+  // The owner's stored choice and the deployment's default stay apart, and
+  // the registry default must not stand in for either: an absent row is what
+  // lets `noindex` decide, and an absent binding is what makes Discover
+  // opt-in for a self-hosted site.
+  const discoverStoredValue = allSettings["DISCOVER"];
+  const discoverDefaultValue = getDiscoverDefault(env);
+  const noindex = demoMode || resolve("NOINDEX", allSettings, env) === "true";
+  const rssFeedsEnabled =
+    resolve("RSS_FEEDS_ENABLED", allSettings, env) === "true";
+
   return {
     // Site identity (DB > ENV > Default)
     siteName: resolve("SITE_NAME", allSettings, env),
@@ -223,19 +255,34 @@ export function resolveConfig(
     siteDescriptionExplicit,
     siteLanguage: resolve("SITE_LANGUAGE", allSettings, env),
     dashboardLanguage: resolve("DASHBOARD_LANGUAGE", allSettings, env),
-    cjkSerifFont: resolve("CJK_SERIF_FONT", allSettings, env),
+    multilingualEnabled:
+      resolve("MULTILINGUAL_ENABLED", allSettings, env) === "true",
+    additionalLanguages: parseLanguageList(
+      resolve("ADDITIONAL_LANGUAGES", allSettings, env),
+    ),
     mainRssFeed: parseFeedKind(
       resolve("MAIN_RSS_FEED", allSettings, env),
       "featured",
     ),
+    archiveDefaultLayout: parseArchiveLayout(
+      resolve("ARCHIVE_DEFAULT_LAYOUT", allSettings, env),
+      "list",
+    ),
     timeZone: normalizeTimeZone(resolve("TIME_ZONE", allSettings, env)),
     siteFooter: resolve("SITE_FOOTER", allSettings, env),
     showJantBrandingOnHome:
       resolve("SHOW_JANT_BRANDING_ON_HOME", allSettings, env) === "true",
-    noindex: demoMode || resolve("NOINDEX", allSettings, env) === "true",
+    noindex,
+    discover: resolveDiscoverMode({
+      storedValue: discoverStoredValue,
+      defaultValue: discoverDefaultValue,
+      demoMode,
+      noindex,
+      rssFeedsEnabled,
+    }),
     publicApiEnabled:
       resolve("PUBLIC_API_ENABLED", allSettings, env) === "true",
-    rssFeedsEnabled: resolve("RSS_FEEDS_ENABLED", allSettings, env) === "true",
+    rssFeedsEnabled,
 
     // Infrastructure (ENV only)
     siteUrl,
@@ -318,6 +365,7 @@ export function resolveConfig(
     siteAvatar,
     showHeaderAvatar: allSettings["SHOW_HEADER_AVATAR"] === "true",
     siteAvatarUrl,
+    siteAvatarThumbUrl,
     faviconVersion: allSettings["SITE_FAVICON_VERSION"] ?? "",
 
     // Rate limiting (ENV only). Defaults are conservative enough for a

package/src/lib/schemas.ts

@@ -10,11 +10,13 @@
 
 import { z } from "zod";
 import {
+  ARCHIVE_LAYOUTS,
   FORMATS,
   STATUSES,
   VISIBILITIES,
   SORT_ORDERS,
   COLLECTION_SORT_ORDERS,
+  SMART_COLLECTION_SORT_ORDERS,
   NAV_ITEM_TYPES,
   SYSTEM_NAV_KEY_VALUES,
   MAX_MEDIA_ATTACHMENTS,
@@ -30,14 +32,20 @@ import {
   type ConfigEditorDefinition,
   type ConfigKey,
 } from "../types.js";
-import { isCjkSerifFont } from "../i18n/detect.js";
 import {
+  formatLanguageList,
   isLocale,
   isValidContentLanguage,
   normalizeContentLanguage,
+  parseLanguageList,
 } from "../i18n/locales.js";
 import { ValidationError } from "./errors.js";
 import { createTypeIdSchema, ID_PREFIX } from "./ids.js";
+import {
+  FILTER_DIMENSION_KEYS,
+  FILTER_DIMENSIONS,
+  type PostFilterSelection,
+} from "./filter-dimensions.js";
 import { normalizeSlug } from "./slug-format.js";
 import { isReservedPath } from "./constants.js";
 import { sanitizeUrl, normalizePath } from "./url.js";
@@ -69,6 +77,27 @@ export function normalizeEmail(email: string): string {
   return email.trim().toLowerCase();
 }
 
+/**
+ * A display name to open an account under, before the author has given one.
+ *
+ * The first setup screen asks for credentials only, so better-auth needs a
+ * name it can create the row with; the second screen overwrites it with the
+ * site's name. This stands in only for the gap between the two, and for the
+ * setup that is abandoned in it — which is why it is the address the author
+ * just typed rather than a placeholder they would not recognise.
+ *
+ * @param email - The normalized address the account is being opened under
+ * @returns The part before the `@`, or the whole address when there is none
+ * @example
+ * ```ts
+ * deriveAccountName("owner@example.com");
+ * // Returns: "owner"
+ * ```
+ */
+export function deriveAccountName(email: string): string {
+  return email.split("@")[0]?.trim() || email;
+}
+
 /** Trim, strip control characters, and collapse to undefined when empty. */
 function sanitizeText(maxLength: number) {
   return z
@@ -172,7 +201,10 @@ export const SystemNavKeySchema = z.enum(SYSTEM_NAV_KEY_VALUES);
 export const RedirectTypeSchema = z.enum(["301", "302"]);
 
 /**
- * Custom URL target type enum schema
+ * Custom URL target type enum schema.
+ *
+ * Every kind a stored path can be, including `archive` — which is read and
+ * listed but no longer created. See {@link CreatableCustomUrlTargetTypeSchema}.
  */
 export const CustomUrlTargetTypeSchema = z.enum([
   "post",
@@ -181,6 +213,20 @@ export const CustomUrlTargetTypeSchema = z.enum([
   "archive",
 ]);
 
+/**
+ * The target kinds a new custom URL may take.
+ *
+ * `archive` is absent: hand-typing `format=note&title=none` into a text field
+ * is the problem smart collections exist to replace, and a form that stopped
+ * offering it while the endpoint still accepted it would not have stopped
+ * offering it. Existing archive paths keep working indefinitely.
+ */
+export const CreatableCustomUrlTargetTypeSchema = z.enum([
+  "post",
+  "collection",
+  "redirect",
+]);
+
 /**
  * Rating schema (1-5 integer)
  */
@@ -193,9 +239,24 @@ export const RatingSchema = z.coerce
   .or(z.literal("").transform(() => undefined))
   .transform((v) => (v === 0 ? undefined : v));
 
+/**
+ * Any syntactically valid BCP 47 tag, normalized to canonical case.
+ *
+ * Deliberately open: Jant ships dashboard catalogs for a handful of locales but
+ * content can be written in any language.
+ */
+export const ContentLanguageSchema = z
+  .string()
+  .trim()
+  .refine(isValidContentLanguage, {
+    message: "Enter a valid BCP 47 language tag (e.g. en, zh-Hans, ja).",
+  })
+  .transform(normalizeContentLanguage);
+
 const PostIdSchema = createTypeIdSchema(ID_PREFIX.post);
 const MediaIdSchema = createTypeIdSchema(ID_PREFIX.media);
 const CollectionIdSchema = createTypeIdSchema(ID_PREFIX.collection);
+const SmartCollectionIdSchema = createTypeIdSchema(ID_PREFIX.smartCollection);
 const CollectionDirectoryItemIdSchema = createTypeIdSchema(
   ID_PREFIX.collectionDirectoryItem,
 );
@@ -294,6 +355,12 @@ const PostFieldsSchema = z.object({
     .optional(),
   replyToId: PostIdSchema.optional(),
   quietReply: z.boolean().optional(),
+  // Content language. The post service normalizes and enforces the
+  // thread-uniform rule; this only rejects tags that are not BCP 47 at all.
+  language: ContentLanguageSchema.optional().or(
+    z.literal("").transform(() => undefined),
+  ),
+  translationOfId: PostIdSchema.optional(),
   publishedAt: z.number().int().positive().optional(),
   mediaIds: z.array(MediaIdSchema).max(MAX_MEDIA_ATTACHMENTS).optional(),
   mediaAlts: z.record(MediaIdSchema, z.string()).optional(),
@@ -566,6 +633,14 @@ export const CreateNavItemSchema = z.discriminatedUnion("type", [
     label: sanitizeText(100).pipe(z.string().min(1)).optional(),
     placement: z.enum(["header", "more"]).optional(),
   }),
+  // Placed exactly like a collection — the label follows the target's title
+  // and the URL follows its address; only which column holds the key differs.
+  z.object({
+    type: z.literal("smart_collection"),
+    smartCollectionId: SmartCollectionIdSchema,
+    label: sanitizeText(100).pipe(z.string().min(1)).optional(),
+    placement: z.enum(["header", "more"]).optional(),
+  }),
   z.object({
     type: z.literal("page"),
     postId: PostIdSchema,
@@ -620,6 +695,19 @@ export const CreateCollectionDirectoryItemSchema = z.discriminatedUnion(
   ],
 );
 
+/**
+ * A row in the collections directory, as the drag surface names it.
+ *
+ * A placed row is named by its directory row id. A collection or smart
+ * collection that has never been placed is named by its own id, because that is
+ * all the directory has to render — moving one is what gives it a row.
+ */
+export const CollectionDirectoryRowIdSchema = z.union([
+  CollectionDirectoryItemIdSchema,
+  CollectionIdSchema,
+  SmartCollectionIdSchema,
+]);
+
 export const UpdateCollectionDirectoryItemSchema = z.object({
   label: z.union([CollectionDirectoryLabelSchema, z.null()]).optional(),
   url: CollectionDirectoryLinkUrlSchema.optional(),
@@ -633,6 +721,7 @@ export {
   NavItemIdSchema,
   PathIdSchema,
   PostIdSchema,
+  SmartCollectionIdSchema,
 };
 
 /**
@@ -677,6 +766,61 @@ export const CreateCollectionSchema = z.object({
  */
 export const UpdateCollectionSchema = CreateCollectionSchema.partial();
 
+/**
+ * What a stored selection may hold — the validator a create or update request
+ * runs its conditions through.
+ *
+ * Assembled from the dimension registry rather than restated, so a new
+ * dimension is accepted by every endpoint the moment it is declared, and a
+ * dimension whose stored vocabulary is narrower than its URL one (`visibility`)
+ * is narrow everywhere at once.
+ *
+ * The registry itself carries plain predicates, not schemas, because the smart
+ * collection dialog compiles it into the browser bundle. The Zod wrapper lives
+ * here, on the server side of that line, where request bodies are validated and
+ * a rejected condition still has to say which one it was.
+ */
+export const PostFilterSelectionSchema = z
+  .object(
+    Object.fromEntries(
+      FILTER_DIMENSION_KEYS.map((key) => [
+        key,
+        z
+          .custom((value) => FILTER_DIMENSIONS[key].storage.isStorable(value), {
+            message: `Invalid value for the ${key} condition`,
+          })
+          .optional(),
+      ]),
+    ),
+  )
+  .strict() as unknown as z.ZodType<PostFilterSelection>;
+
+/**
+ * API request body schema for creating a smart collection.
+ *
+ * The conditions come from the dimension registry rather than being restated
+ * here, so a new dimension is accepted the moment it is declared and a stored
+ * vocabulary narrower than the URL one (`visibility` never being `private`)
+ * is narrow at every entry point at once.
+ */
+export const CreateSmartCollectionSchema = z.object({
+  slug: CollectionSlugSchema,
+  title: CollectionTitleSchema,
+  description: CollectionDescriptionValueSchema.nullable().optional(),
+  // Omitted means no conditions, which is the honest spelling of "every post".
+  selection: PostFilterSelectionSchema.optional(),
+  sort: z.enum(SMART_COLLECTION_SORT_ORDERS).optional(),
+  layout: z.enum(ARCHIVE_LAYOUTS).nullable().optional(),
+});
+
+export const UpdateSmartCollectionSchema =
+  CreateSmartCollectionSchema.partial();
+
+/** The body of a preview request: the conditions, and nothing else. */
+export const SmartCollectionPreviewSchema = z.object({
+  selection: PostFilterSelectionSchema.optional(),
+});
+
 export const SiteNameSettingSchema = sanitizeSettingText(MAX_SITE_NAME_LENGTH);
 export const SiteDescriptionSettingSchema = sanitizeSettingText(
   MAX_SITE_DESCRIPTION_LENGTH,
@@ -808,11 +952,16 @@ export function normalizeEditableSettingValue(
         );
       }
       break;
-    case "CJK_SERIF_FONT":
-      if (!isCjkSerifFont(normalized)) {
-        throw new ValidationError("Choose an available CJK font fallback.");
+    case "MULTILINGUAL_ENABLED":
+      if (normalized !== "true" && normalized !== "false") {
+        throw new ValidationError("Multilingual content is on or off.");
       }
       break;
+    case "ADDITIONAL_LANGUAGES":
+      // Re-serialized from the parsed form so a hand-written value cannot
+      // store blanks, duplicates, or non-canonical casing.
+      normalized = formatLanguageList(parseLanguageList(normalized));
+      break;
     case "TIME_ZONE":
       if (!isSupportedTimeZone(normalized)) {
         throw new ValidationError("Choose a valid time zone.");
@@ -837,11 +986,10 @@ export const CreateCustomUrlSchema = z.object({
       "Path must contain only lowercase alphanumeric characters, hyphens, slashes, and dots",
     )
     .transform((p) => (p.startsWith("/") ? p : `/${p}`)),
-  targetType: CustomUrlTargetTypeSchema,
+  targetType: CreatableCustomUrlTargetTypeSchema,
   targetId: z.string().optional(),
   toPath: z.string().optional(),
   redirectType: RedirectTypeSchema.optional(),
-  archiveQuery: z.string().optional(),
 });
 
 // =============================================================================
@@ -849,10 +997,13 @@ export const CreateCustomUrlSchema = z.object({
 // =============================================================================
 
 /**
- * Setup form validation schema
+ * The first of the two screens a self-hosted site is set up through.
+ *
+ * Credentials and nothing else. Everything about the site itself waits for the
+ * second screen, which is the same screen a hosted site shows — so the two
+ * install kinds converge instead of keeping two forms that drift.
  */
-export const SetupSchema = z.object({
-  siteName: z.string().min(1, "Site name is required"),
+export const SetupAccountSchema = z.object({
   email: z
     .string()
     .transform(normalizeEmail)
@@ -863,6 +1014,46 @@ export const SetupSchema = z.object({
     .max(128),
 });
 
+/**
+ * Setup on a site whose shell already exists and is already named.
+ *
+ * A control plane created the site and its owner, so the only thing left to
+ * settle is the language its author writes in — the one fact no header, host,
+ * or billing record can supply.
+ */
+export const SetupLanguageSchema = z.object({
+  contentLanguage: ContentLanguageSchema,
+  /**
+   * The Jant Discover answer, from the checkbox on the setup screen.
+   *
+   * Optional, and absence is not `false`: an older client or a scripted setup
+   * sends nothing, and that has to keep meaning "leave the deployment default
+   * in force" rather than "the author said no".
+   */
+  discover: z.boolean().optional(),
+});
+
+/**
+ * The second of the two self-hosted screens: the same questions the hosted
+ * screen asks, plus the name only a self-hosted site is still missing.
+ *
+ * Which of the two applies is not a property of the form but of the site — a
+ * site that already has a name is never asked for one — so the route picks the
+ * schema by reading the stored name rather than trusting a field.
+ */
+export const SetupSiteSchema = SetupLanguageSchema.extend({
+  // The message is set twice over on purpose: `.min(1)` catches a field left
+  // blank, and the type-level `error` catches a form that carried no field at
+  // all. Without the second, a scripted setup is told "expected string,
+  // received undefined" — which names nothing the author can act on.
+  siteName: z
+    .string({ error: "Site name is required" })
+    .min(1, "Site name is required"),
+});
+
+/** The answers the last setup screen collects from either install kind. */
+export type SetupLanguageAnswers = z.infer<typeof SetupLanguageSchema>;
+
 /**
  * Sign-in form validation schema
  */

package/src/lib/site-header-fragment.tsx

@@ -29,7 +29,8 @@ export async function renderSiteHeaderHtml(c: Context<Env>): Promise<string> {
         links={navData.links}
         currentPath={navData.currentPath}
         sitePathPrefix={navData.sitePathPrefix}
-        siteAvatarUrl={navData.siteAvatarUrl}
+        basePath={navData.basePath}
+        siteAvatarThumbUrl={navData.siteAvatarThumbUrl}
         showHeaderAvatar={navData.showHeaderAvatar}
       />
     </I18nProvider>,

package/src/lib/site-unavailable-page.ts

@@ -0,0 +1,47 @@
+/**
+ * Standalone page served when a site resolves but is suspended.
+ *
+ * Kept deliberately self-contained (no theme, no site services, no i18n
+ * catalog): it renders before any site context exists, and the site whose
+ * theme we would otherwise use is exactly the one that is unavailable.
+ *
+ * The copy stays provider-neutral. Hosted deployments pass their brand across
+ * the boundary through `HOSTED_CONTROL_PLANE_PROVIDER_NAME` /
+ * `HOSTED_CONTROL_PLANE_BASE_URL`, which turn the last line into a real link
+ * back to the control plane; a self-hosted instance renders the same page
+ * without one.
+ */
+
+import { getHostedControlPlaneProviderLabel } from "./env.js";
+import { getHostedControlPlaneDashboardUrl } from "./hosted-signin.js";
+import { escapeHtml } from "./html.js";
+
+export function renderSiteUnavailablePage(
+  env: object | undefined | null,
+): string {
+  const providerLabel = getHostedControlPlaneProviderLabel(env);
+  const dashboardUrl = getHostedControlPlaneDashboardUrl(env);
+
+  const ownerLine =
+    dashboardUrl && providerLabel
+      ? `<p>If it's your site, sign in to <a href="${escapeHtml(dashboardUrl)}">${escapeHtml(providerLabel)}</a> to bring it back online.</p>`
+      : `<p>If it's your site, sign in to your hosting provider to bring it back online.</p>`;
+
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta name="robots" content="noindex">
+<title>This site is offline</title>
+<style>body{font-family:system-ui,sans-serif;display:flex;justify-content:center;align-items:center;min-height:100vh;margin:0;background:#fafafa;color:#111;padding:24px}div{max-width:460px;text-align:left}h1{font-size:1.25rem;font-weight:600;margin:0 0 12px}p{color:#4a4a4a;line-height:1.6;margin:12px 0}a{color:#0f766e}@media(prefers-color-scheme:dark){body{background:#111;color:#fafafa}p{color:#a1a1a1}a{color:#2dd4bf}}</style>
+</head>
+<body>
+<div>
+<h1>This site is offline</h1>
+<p>There's nothing to read here right now &mdash; the site's hosting has stopped.</p>
+${ownerLine}
+</div>
+</body>
+</html>`;
+}

package/src/lib/slug.ts

@@ -5,7 +5,7 @@
  * Handles three cases: user-provided slug, title-based slug, and random-only slug.
  */
 
-import { slugify } from "./url.js";
+import { slugify } from "./slugify.js";
 import { generateRandomId } from "./nanoid.js";
 import { isReservedPath } from "./constants.js";
 import { ValidationError, ConflictError } from "./errors.js";
@@ -19,6 +19,21 @@ export interface SlugOptions {
   title?: string;
   /** Length of random IDs */
   idLength: number;
+  /**
+   * URL form of the post's language (lowercased BCP 47 tag, e.g. `zh-hant`),
+   * set only for posts written in a non-primary language. Used as the first
+   * fallback when a title-based slug collides, so the transliterations of a
+   * translated pair land on `shu-ping` and `shu-ping-en` rather than a random
+   * suffix. Omitted for primary-language posts: the bare namespace belongs to
+   * them, and a language suffix among same-language posts distinguishes nothing.
+   */
+  languageSuffix?: string;
+  /**
+   * URL prefixes currently served by language views. A slug matching one would
+   * be shadowed by that view and never resolve, so it is treated as reserved
+   * for as long as the language is configured.
+   */
+  reservedPrefixes?: readonly string[];
   /** Callback to check if a slug is available (checks post slugs + path_registry paths) */
   isAvailable: (slug: string) => Promise<boolean>;
 }
@@ -28,7 +43,7 @@ export interface SlugOptions {
  *
  * Resolution order:
  * 1. User-provided slug → validate format, check reserved, check availability
- * 2. Title exists → slugify(title), append -{randomId} if conflict
+ * 2. Title exists → slugify(title), then -{languageSuffix}, then -{randomId}
  * 3. No title → pure random ID
  *
  * @param opts - Slug generation options
@@ -42,16 +57,33 @@ export interface SlugOptions {
  * // Title-based
  * await generatePostSlug({ title: "Hello World", idLength: 5, isAvailable: check });
  *
+ * // Title-based in a secondary language, colliding with an existing slug
+ * await generatePostSlug({
+ *   title: "書評",
+ *   languageSuffix: "en",
+ *   idLength: 5,
+ *   isAvailable: check,
+ * }); // => "shu-ping-en"
+ *
  * // Random
  * await generatePostSlug({ idLength: 5, isAvailable: check });
  * ```
  */
 export async function generatePostSlug(opts: SlugOptions): Promise<string> {
-  const { slug, title, idLength, isAvailable } = opts;
+  const {
+    slug,
+    title,
+    idLength,
+    languageSuffix,
+    reservedPrefixes = [],
+    isAvailable,
+  } = opts;
+  const isReserved = (candidate: string) =>
+    isReservedPath(candidate, reservedPrefixes);
 
   // Case 1: User-provided slug
   if (slug) {
-    if (isReservedPath(slug)) {
+    if (isReserved(slug)) {
       throw new ValidationError(
         `Slug "${slug}" is reserved and cannot be used`,
       );
@@ -66,15 +98,27 @@ export async function generatePostSlug(opts: SlugOptions): Promise<string> {
   // Case 2: Title-based slug
   if (title) {
     const base = slugify(title);
-    if (base && !isReservedPath(base)) {
+    if (base && !isReserved(base)) {
       const available = await isAvailable(base);
       if (available) return base;
+
+      // A readable language suffix beats a random one, and it is exactly the
+      // collision a translated pair produces.
+      if (languageSuffix) {
+        const languageCandidate = `${base}-${languageSuffix}`;
+        if (
+          !isReserved(languageCandidate) &&
+          (await isAvailable(languageCandidate))
+        ) {
+          return languageCandidate;
+        }
+      }
     }
 
     // Append random suffix on conflict or reserved base
     for (let i = 0; i < MAX_RETRIES; i++) {
       const candidate = `${base || generateRandomId(idLength)}-${generateRandomId(idLength)}`;
-      if (!isReservedPath(candidate) && (await isAvailable(candidate))) {
+      if (!isReserved(candidate) && (await isAvailable(candidate))) {
         return candidate;
       }
     }
@@ -86,7 +130,7 @@ export async function generatePostSlug(opts: SlugOptions): Promise<string> {
   // Case 3: Pure random
   for (let i = 0; i < MAX_RETRIES; i++) {
     const candidate = generateRandomId(idLength);
-    if (!isReservedPath(candidate) && (await isAvailable(candidate))) {
+    if (!isReserved(candidate) && (await isAvailable(candidate))) {
       return candidate;
     }
   }