@secorto/i18n 0.0.4

package/src/core/extract-id.ts

@@ -0,0 +1,39 @@
+import type { Locales } from './locale'
+
+/**
+ * Extracts the locale and cleanId from an entryId of the form "es/my-post".
+ * Locale validation is delegated to the Locales value object.
+ *
+ * @param entryId Raw entry identifier (e.g., "es/my-post")
+ * @param locales Locales value object created via createLocales()
+ * @returns An object containing the validated locale and cleanId
+ * @throws Error if the entryId is malformed or the locale is invalid
+ */
+export function extractCleanId<L extends string>(
+  entryId: string,
+  locales: Locales<L>
+): { locale: L; id: string } {
+  if (!entryId) {
+    throw new Error('entryId cannot be empty')
+  }
+
+  const firstSlash = entryId.indexOf('/')
+  if (firstSlash <= 0) {
+    throw new Error(`Invalid entryId "${entryId}" — missing locale prefix`)
+  }
+
+  const rawLocale = entryId.slice(0, firstSlash)
+
+  if (!locales.isValid(rawLocale)) {
+    throw new Error(
+      `Invalid entryId "${entryId}". Unknown locale prefix "${rawLocale}". Expected one of: ${locales.all.join(', ')}.`
+    )
+  }
+
+  const cleanId = entryId.slice(firstSlash + 1)
+
+  return {
+    locale: rawLocale,
+    id: cleanId
+  }
+}

package/src/core/index.ts

@@ -0,0 +1,4 @@
+export * from './locale'
+export * from './translationLink'
+export * from './standalone'
+export * from './extract-id'

package/src/core/locale.ts

@@ -0,0 +1,30 @@
+export interface Locales<L extends string> {
+  readonly all: readonly L[]
+  fromString(lang: string | undefined): L
+  isValid(lang: string): lang is L
+}
+
+function isLocale<L extends string>(
+  locales: readonly L[],
+  lang: string
+): lang is L {
+  return locales.includes(lang as L)
+}
+
+export function createLocales<L extends string>(
+  locales: readonly L[]
+): Locales<L> {
+  return {
+    all: locales,
+
+    fromString(lang) {
+      if (!lang) throw new TypeError(`Invalid language: ${lang}`)
+      if (isLocale(locales, lang)) return lang
+      throw new TypeError(`Invalid language: ${lang}`)
+    },
+
+    isValid(lang): lang is L {
+      return isLocale(locales, lang)
+    }
+  }
+}

package/src/core/standalone.ts

@@ -0,0 +1,96 @@
+import { extractCleanId } from './extract-id'
+import type { Locales } from './locale'
+import {
+  availableLink,
+  draftLink,
+  missingLink,
+  type TranslationLink,
+} from './translationLink'
+
+/**
+ * Represents a localized standalone page.
+ */
+export interface StandalonePageEntry {
+  /**
+   * Route to the page.
+   */
+  route: string
+
+  /**
+   * Indicates whether the page exists only as a draft.
+   */
+  draft?: boolean
+}
+
+/**
+* Maps a page identifier to its localized standalone page entries.
+*
+* The first key represents the page identifier and the nested keys represent
+* locales.
+*/
+export type StandalonePageIndex<
+  K extends string,
+  L extends string,
+> = Record<
+  K,
+  Partial<Record<L, StandalonePageEntry>>
+>
+
+/**
+ * Creates translation links for a standalone page.
+ *
+ * Validates that:
+ * - the translation key is indexed
+ * - the current route belongs to the indexed translation group
+ */
+export function createStandalonePageLinks<
+  L extends string,
+>(
+  path: string,
+  translationKey: string,
+  index: StandalonePageIndex<string, L>,
+  locales: Locales<L>,
+): TranslationLink<L>[] {
+  const { locale: currentLocale, id: currentRoute } = extractCleanId(
+    path,
+    locales,
+  )
+
+  const group = index[translationKey]
+
+  if (!group) {
+    throw new Error(
+      `Standalone page '${translationKey}' is not indexed.`,
+    )
+  }
+
+  const currentEntry = group[currentLocale]
+
+  if (!currentEntry) {
+    throw new Error(
+      `Standalone page '${translationKey}' has no entry for locale '${currentLocale}'.`,
+    )
+  }
+
+  if (currentEntry.route !== currentRoute) {
+    throw new Error(
+      `Route '${path}' does not belong to standalone page '${translationKey}'.`,
+    )
+  }
+
+  return locales.all.map(locale => {
+    const entry = group[locale]
+
+    if (!entry) {
+      return missingLink(locale)
+    }
+
+    const href = `/${locale}/${entry.route}`
+
+    if (entry.draft) {
+      return draftLink(href, locale)
+    }
+
+    return availableLink(href, locale)
+  })
+}

package/src/core/translationLink.ts

@@ -0,0 +1,130 @@
+/**
+ * Represents a translation that is available and can be accessed by users.
+ */
+export type AvailableLink<L extends string> = {
+  type: 'available'
+  href: string
+  locale: L
+}
+
+/**
+ * Represents a translation that does not exist for the given locale.
+ */
+export type MissingLink<L extends string> = {
+  type: 'missing'
+  href: null
+  locale: L
+}
+
+/**
+ * Represents a translation that exists as a draft but is not yet publicly available.
+ */
+export type DraftLink<L extends string> = {
+  type: 'draft'
+  href: string
+  locale: L
+}
+
+/**
+ * Represents the state of a translation for a locale.
+ */
+export type TranslationLink<L extends string> =
+  | AvailableLink<L>
+  | MissingLink<L>
+  | DraftLink<L>
+
+/**
+ * Represents a translation link that can be accessed, either as a published
+ * translation (`available`) or as a draft (`draft`).
+ */
+export type AccessibleTranslationLink<L extends string> =
+  | AvailableLink<L>
+  | DraftLink<L>
+
+
+/**
+ * Creates an available translation link.
+ */
+export function availableLink<L extends string>(
+  href: string,
+  lang: L
+): AvailableLink<L> {
+  return { type: 'available', href, locale: lang }
+}
+
+/**
+ * Creates a missing translation link.
+ */
+export function missingLink<L extends string>(
+  lang: L
+): MissingLink<L> {
+  return { type: 'missing', href: null, locale: lang }
+}
+
+/**
+ * Creates a draft translation link.
+ */
+export function draftLink<L extends string>(
+  href: string,
+  lang: L
+): DraftLink<L> {
+  return { type: 'draft', href, locale: lang }
+}
+
+/** Returns whether the link is accessible. */
+export function isAccessible<L extends string>(link: TranslationLink<L>): link is AccessibleTranslationLink<L> {
+  return link.type === 'available' || link.type === 'draft'
+}
+
+/** Returns whether the link is available. */
+export function isAvailable<L extends string>(link: TranslationLink<L>): link is AvailableLink<L> {
+  return link.type === 'available'
+}
+
+/** Returns whether the link is a draft. */
+export function isDraft<L extends string>(link: TranslationLink<L>): link is DraftLink<L> {
+  return link.type === 'draft'
+}
+
+/** Returns whether the link is missing. */
+export function isMissing<L extends string>(link: TranslationLink<L>): link is MissingLink<L> {
+  return link.type === 'missing'
+}
+
+/**
+ * Resolves the default accessible translation link from a collection of links.
+ *
+ * Selection priority:
+ * 1. An `available` link matching `defaultLang`.
+ * 2. The first `available` link.
+ * 3. A `draft` link matching `defaultLang`.
+ * 4. The first `draft` link.
+ *
+ * @template L Type representing the supported locales.
+ * @param links Translation links to evaluate.
+ * @param defaultLang Preferred locale to prioritize during selection.
+ * @returns The selected accessible translation link.
+ *
+ * @throws {Error} If `links` is empty or if no accessible link exists.
+ */
+export function resolveDefaultAccessibleLink<L extends string>(
+  links: TranslationLink<L>[],
+  defaultLang: L
+): AccessibleTranslationLink<L> {
+  if (!links || links.length === 0) throw new Error('resolveDefaultAccessibleLink: unexpected empty links array')
+
+  const defaultAny = links.find(l => l.locale === defaultLang)
+  if (defaultAny && isAvailable(defaultAny)) return defaultAny
+
+  const firstAvailable = links.find(isAvailable)
+  if (firstAvailable) return firstAvailable
+
+  if (defaultAny && isDraft(defaultAny)) return defaultAny
+
+  const firstDraft = links.find(isDraft)
+  if (firstDraft) return firstDraft
+
+  throw new Error(
+    'resolveDefaultAccessibleLink: expected at least one accessible link'
+  )
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export * from './core'
+export * from './section'

package/src/section/detail-path.ts

@@ -0,0 +1,95 @@
+import { Locales } from '../core'
+import {
+  createTranslationIndex,
+  LocalizedEntry,
+  TranslationIndex,
+} from './translation-index'
+import {
+  adaptToLocalizedEntry,
+  GenericCollectionEntry,
+} from './entry-adapter'
+import { SectionRoutes } from './routes'
+
+export type DetailPath<
+  C extends string,
+  L extends string,
+  TEntry extends GenericCollectionEntry<C, object>,
+> = {
+  params: {
+    locale: L
+    section: string
+    id: string
+  }
+  props: {
+    entry: LocalizedEntry<TEntry, L>
+    section: C
+    siblings: TranslationIndex<L, TEntry>[string]
+  }
+}
+
+/**
+ * Generates the static path definitions required to build localized detail pages
+ * for all entries across all configured sections.
+ *
+ * For each section defined in `routes`, this function:
+ * 1. Fetches the collection entries.
+ * 2. Adapts them into localized entries.
+ * 3. Groups translations by translation key.
+ * 4. Produces one path per localized entry, including its translation siblings.
+ *
+ * The resulting paths can be consumed by static site generators to create
+ * localized detail pages with access to the current entry and all of its
+ * translations.
+ *
+ * @template TEntry Entry type returned by the collection loader.
+ * @template E Entry data type.
+ * @template C Section identifiers (for example: `'blog' | 'docs'`).
+ * @template L Locale identifiers (for example: `'en' | 'es'`).
+ *
+ * @param routes Localized section routes used to resolve URL segments.
+ * @param fetchCollection Function that retrieves all entries belonging
+ * to a given section.
+ * @param allowedLocales Supported locales
+ */
+export async function getStaticPathsEntries<
+  C extends string,
+  E extends object,
+  L extends string,
+  TEntry extends GenericCollectionEntry<C, E>,
+>(
+  routes: SectionRoutes<C, L>,
+  fetchCollection: (
+    collection: C,
+  ) => Promise<TEntry[]>,
+  allowedLocales: Locales<L>,
+): Promise<DetailPath<C, L, TEntry>[]> {
+
+  const allPaths: DetailPath<C, L, TEntry>[] = []
+
+  for (const sectionKey of routes.getSections()) {
+    const rawEntries = await fetchCollection(sectionKey)
+
+    const localizedEntries = rawEntries.map(entry =>
+      adaptToLocalizedEntry(entry, allowedLocales),
+    )
+
+    const index = createTranslationIndex(localizedEntries)
+
+    for (const localized of localizedEntries) {
+      allPaths.push({
+        params: {
+          locale: localized.locale,
+          section: routes.getSectionRoute(sectionKey, localized.locale),
+          id: localized.cleanId,
+        },
+        props: {
+          entry: localized,
+          section: sectionKey,
+          siblings: index[localized.translationKey],
+        },
+      })
+    }
+  }
+
+  return allPaths
+}

package/src/section/details-links.ts

@@ -0,0 +1,42 @@
+import { availableLink, draftLink, Locales, missingLink, TranslationLink } from "../core"
+import { GenericCollectionEntry } from "./entry-adapter"
+import { SectionRoutes } from "./routes"
+import { LocalizedEntry } from "./translation-index"
+
+/**
+ * Creates translation links for all supported locales.
+ *
+ * Existing translations are returned as `available` links. Missing
+ * translations are represented as `missing` links. The output preserves
+ * the order defined by `locales.all`.
+ *
+ * @param siblings Available translations indexed by locale.
+ * @param sectionRoutes Routes used to build localized URLs.
+ * @param locales Supported locales.
+ * @returns One translation link per supported locale.
+ */
+export function createDetailTranslationLinks<
+  C extends string,
+  L extends string,
+  TEntry extends GenericCollectionEntry<C, object>,
+>(
+  siblings: Partial<Record<L, LocalizedEntry<TEntry, L>>>,
+  sectionRoutes: SectionRoutes<C, L>,
+  locales: Locales<L>,
+): TranslationLink<L>[] {
+  return locales.all.map(locale => {
+    const sibling = siblings[locale]
+
+    if (!sibling) {
+      return missingLink(locale)
+    }
+
+    const href = sectionRoutes.getEntryURL(
+      sibling.original.collection,
+      locale,
+      sibling.cleanId,
+    )
+
+    return sibling.draft ? draftLink(href, locale) : availableLink(href, locale)
+  })
+}

package/src/section/entry-adapter.ts

@@ -0,0 +1,57 @@
+import { extractCleanId, Locales } from '../core'
+import { LocalizedEntry } from './translation-index'
+
+export interface GenericCollectionEntry<
+  C extends string,
+  TData
+> {
+  id: string
+  collection: C
+  data: TData
+}
+
+export function resolveTranslationKey<T extends object>(
+  data: T,
+  cleanId: string
+): string {
+  return 'translationKey' in data &&
+    typeof (data as Record<string, unknown>).translationKey === 'string'
+    ? (data as Record<string, unknown>).translationKey as string
+    : cleanId
+}
+
+/**
+ * Converts a collection entry into a localized entry.
+ *
+ * Extracts the locale and clean ID from the entry ID and resolves the
+ * translation key used to group translations of the same content.
+ *
+ * @param entry Collection entry to adapt.
+ * @param locales Supported locales used to parse the entry ID.
+ * @returns The corresponding localized entry.
+ */
+export function adaptToLocalizedEntry<
+  C extends string,
+  T extends object,
+  L extends string,
+  TEntry extends GenericCollectionEntry<C, T>
+>(
+  entry: TEntry,
+  locales: Locales<L>
+): LocalizedEntry<TEntry, L> {
+  const { locale, id: cleanId } =
+    extractCleanId(entry.id, locales)
+
+  const draft = 'draft' in entry.data && entry.data.draft === true
+
+  return {
+    cleanId,
+    locale,
+    translationKey: resolveTranslationKey(
+      entry.data,
+      cleanId
+    ),
+    draft,
+    original: entry,
+  }
+}

package/src/section/index.ts

@@ -0,0 +1,5 @@
+export * from './routes'
+export * from './translation-index'
+export * from './entry-adapter'
+export * from './detail-path'
+export * from './details-links'

package/src/section/routes.ts

@@ -0,0 +1,128 @@
+export type SectionDictionary<
+  Section extends string,
+  Language extends string,
+  TValue
+> = Record<
+  Section,
+  Record<Language, TValue>
+>
+
+/**
+ * Value object that encapsulates localized slugs per section and exposes
+ * a stable API for building localized URLs.
+ *
+ * Invariants:
+ * - Each (locale, slug) pair must be unique across all sections.
+ * - The object is constructed exclusively through `createSectionRoutes`.
+ *
+ * @template Section - Section keys (e.g., 'blog', 'talk').
+ * @template Language - Locale keys (e.g., 'es', 'en').
+ */
+export interface SectionRoutes<
+  Section extends string,
+  Language extends string
+> {
+  /**
+   * Raw dictionary of localized slugs per section.
+   * This structure is immutable once the value object is created.
+   */
+  readonly routes: Record<Section, Record<Language, string>>
+
+  /**
+   * Returns the configured section identifiers.
+   */
+  getSections(): Section[]
+
+  /**
+   * Returns the localized slug for a section.
+   *
+   * @param section Section identifier.
+   * @param locale Locale identifier.
+   * @returns Localized slug for the section.
+   */
+  getSectionRoute(section: Section, locale: Language): string
+
+  /**
+   * Returns the localized URL for a section, including locale prefix.
+   *
+   * @param section Section identifier.
+   * @param locale Locale identifier.
+   * @returns URL string for the section in the given locale.
+   */
+  getSectionURL(section: Section, locale: Language): string
+
+  /**
+   * Returns the localized URL for a content entry inside a section.
+   *
+   * @param section Section identifier.
+   * @param locale Locale identifier.
+   * @param slug Entry slug.
+   * @returns Full URL for the entry.
+   */
+  getEntryURL(section: Section, locale: Language, slug: string): string
+}
+
+/**
+ * Constructs a nominal SectionRoutes value from a raw SectionDictionary.
+ *
+ * This function enforces the domain invariants for localized section routes:
+ * - each (locale, slug) pair must be unique across all sections
+ * - the resulting value is branded as 'SectionRoutes'
+ *
+ * If any invariant is violated, an error is thrown and the SectionRoutes value
+ * is not constructed.
+ *
+ * @template Section - The section keys (e.g., 'blog', 'docs').
+ * @template Language - The language codes (e.g., 'es', 'en').
+ * @param routes Raw dictionary of localized slugs per section.
+ * @returns A branded SectionRoutes value.
+ */
+export function createSectionRoutes<
+  Section extends string,
+  Language extends string
+>(
+  routes: SectionDictionary<Section, Language, string>
+): SectionRoutes<Section, Language> {
+  const seen = new Map<string, Section>()
+
+  for (const section of Object.keys(routes) as Section[]) {
+    const localized = routes[section]
+
+    for (const locale of Object.keys(localized) as Language[]) {
+      const slug = localized[locale]
+      const key = `${locale}:${slug}`
+
+      if (seen.has(key)) {
+        const other = seen.get(key)!
+        throw new Error(
+          `Duplicated route for locale "${locale}" and slug "${slug}" between sections "${other}" and "${section}".`
+        )
+      }
+
+      seen.set(key, section)
+    }
+  }
+
+  const getSections = (): Section[] => Object.keys(routes) as Section[]
+
+  const getSectionRoute = (section: Section, locale: Language): string =>
+    routes[section][locale]
+
+  const getSectionURL = (section: Section, locale: Language): string =>
+    `/${locale}/${getSectionRoute(section, locale)}`
+
+  const getEntryURL = (
+    section: Section,
+    locale: Language,
+    slug: string
+  ): string =>
+    `${getSectionURL(section, locale)}/${slug}`
+
+  return {
+    routes,
+    getSections,
+    getSectionRoute,
+    getSectionURL,
+    getEntryURL
+  }
+}