lightnet 4.0.7 → 4.1.0

package/src/content/get-categories.ts

@@ -1,34 +1,34 @@
 import { AstroError } from "astro/errors"
 import { getCollection } from "astro:content"
 
-import type { TranslateMapFn } from "../i18n/translate-map"
+import type { TranslateContentFieldFn } from "../i18n/translate-map"
 import { lazy } from "../utils/lazy"
 import { verifySchemaAsync } from "../utils/verify-schema"
-import { categoryEntrySchema } from "./content-schema"
 import { getMediaItems } from "./get-media-items"
+import { categoryEntrySchema } from "./schema/category"
 
 const categoriesById = lazy(async () =>
   Object.fromEntries(
-    (await loadCategories()).map(({ id, data }) => [id, data]),
+    (await loadCategories()).map((category) => [category.id, category]),
   ),
 )
 
-const contentCategories = lazy(async () => {
+const contentCategoryIds = lazy(async () => {
   const categories = await categoriesById.get()
-  return Object.fromEntries(
+  return new Set<string>(
     (await getMediaItems())
       .flatMap((item) => item.data.categories ?? [])
-      .map((c) => {
-        const category = categories[c.id]
+      .map(({ id }) => {
+        const category = categories[id]
         if (!category) {
           throw new AstroError(
             "Missing Category",
-            `A media item references a non-existent category: "${c.id}".\n` +
+            `A media item references a non-existent category: "${id}".\n` +
               `To fix this, create a category file at:\n` +
-              `src/content/categories/${c.id}.json`,
+              `src/content/categories/${id}.json`,
           )
         }
-        return [c.id, category]
+        return id
       }),
   )
 })
@@ -42,18 +42,13 @@ const contentCategories = lazy(async () => {
  */
 export async function getUsedCategories(
   currentLocale: string,
-  tMap: TranslateMapFn,
+  tContentField: TranslateContentFieldFn,
 ) {
-  const categories = await contentCategories.get()
-  return [...Object.entries(categories)]
-    .map(([id, data]) => ({
-      id,
-      ...data,
-      labelText: tMap(data.label, {
-        path: ["categories", id, "label"],
-      }),
-    }))
-    .sort((a, b) => a.labelText.localeCompare(b.labelText, currentLocale))
+  const usedIds = await contentCategoryIds.get()
+  // we intentionally translate all categories because we want
+  // to record translations also for unreferenced categories
+  const categories = await getCategories(currentLocale, tContentField)
+  return categories.filter(({ id }) => usedIds.has(id))
 }
 
 /**
@@ -66,21 +61,22 @@ export async function getUsedCategories(
  */
 export async function getCategories(
   currentLocale: string,
-  tMap: TranslateMapFn,
+  tContentField: TranslateContentFieldFn,
 ) {
   const categories = await categoriesById.get()
   return [...Object.entries(categories)]
-    .map(([id, data]) => ({
+    .map(([id, category]) => ({
       id,
-      ...data,
-      labelText: tMap(data.label, {
-        path: ["categories", id, "label"],
-      }),
+      ...category.data,
+      labelText: tContentField(category.data.label, category),
     }))
     .sort((a, b) => a.labelText.localeCompare(b.labelText, currentLocale))
 }
 
-export async function getCategory(id: string) {
+export async function getCategory(
+  id: string,
+  tContentField: TranslateContentFieldFn,
+) {
   const category = (await categoriesById.get())[id]
   if (!category) {
     throw new AstroError(
@@ -90,7 +86,8 @@ export async function getCategory(id: string) {
   }
   return {
     id,
-    ...category,
+    ...category.data,
+    labelText: tContentField(category.data.label, category),
   }
 }
 

package/src/content/get-languages.ts

@@ -1,35 +1,22 @@
-import { resolveLanguage } from "../i18n/resolve-language"
-import type { TranslateMapFn } from "../i18n/translate-map"
+import { getTranslatedLanguages } from "../i18n/resolve-language"
+import type { TranslateConfigFieldFn } from "../i18n/translate-map"
 import { lazy } from "../utils/lazy"
 import { getMediaItems } from "./get-media-items"
 
-type ResolvedLanguage = Awaited<ReturnType<typeof resolveLanguage>>
-
 /**
- * Array of distinct content languages.
+ * Distinct language codes referenced by media items.
  */
-const contentLanguages = lazy(async () => {
-  const languagesByCode = Object.fromEntries(
-    await Promise.all(
-      (await getMediaItems()).map(async ({ data: { language } }) => [
-        language,
-        resolveLanguage(language),
-      ]),
-    ),
-  )
-  return Object.values(languagesByCode) as ResolvedLanguage[]
-})
+const contentLanguagesLoader = lazy(
+  async () =>
+    new Set((await getMediaItems()).map(({ data: { language } }) => language)),
+)
 
-export const getUsedLanguages = async (
+export const getContentLanguages = async (
   currentLocale: string,
-  tMap: TranslateMapFn,
+  tConfigField: TranslateConfigFieldFn,
 ) => {
-  return (await contentLanguages.get())
-    .map((language) => ({
-      ...language,
-      labelText: tMap(language.label, {
-        path: ["languages", language.code, "label"],
-      }),
-    }))
-    .sort((a, b) => a.labelText.localeCompare(b.labelText, currentLocale))
+  const contentLanguages = await contentLanguagesLoader.get()
+  return (await getTranslatedLanguages(currentLocale, tConfigField)).filter(
+    ({ code }) => contentLanguages.has(code),
+  )
 }

package/src/content/get-media-collections.ts

@@ -2,7 +2,7 @@ import { getCollection } from "astro:content"
 
 import { lazy } from "../utils/lazy"
 import { verifySchemaAsync } from "../utils/verify-schema"
-import { mediaCollectionEntrySchema } from "./content-schema"
+import { mediaCollectionEntrySchema } from "./schema/media-collection"
 
 const collectionsByMediaItemIds = lazy(async () =>
   (await loadMediaCollections())

package/src/content/get-media-items.ts

@@ -1,7 +1,7 @@
 import { getCollection, getEntry } from "astro:content"
 
 import { verifySchemaAsync } from "../utils/verify-schema"
-import { mediaItemEntrySchema } from "./content-schema"
+import { mediaItemEntrySchema } from "./schema/media-item"
 
 /**
  * Internal API to get media items. Since this package is a Astro integration

package/src/content/get-media-types.ts

@@ -1,17 +1,17 @@
 import { AstroError } from "astro/errors"
 import { getCollection } from "astro:content"
 
-import type { TranslateMapFn } from "../i18n/translate-map"
+import type { TranslateContentFieldFn } from "../i18n/translate-map"
 import { lazy } from "../utils/lazy"
 import { verifySchema } from "../utils/verify-schema"
-import { mediaTypeEntrySchema } from "./content-schema"
 import { getMediaItems } from "./get-media-items"
+import { mediaTypeEntrySchema } from "./schema/media-type"
 
 const typesById = lazy(async () =>
   Object.fromEntries((await loadTypes()).map((type) => [type.id, type])),
 )
 
-const contentTypes = lazy(
+const contentTypesLoader = lazy(
   async () => new Set((await getMediaItems()).map((item) => item.data.type.id)),
 )
 
@@ -26,18 +26,25 @@ export const getMediaType = async (id: string) => {
   return type
 }
 
-export const getUsedMediaTypes = async (
+export async function getUsedMediaTypes(
   currentLocale: string,
-  tMap: TranslateMapFn,
-) => {
-  const byId = await typesById.get()
-  return Array.from(await contentTypes.get(), (typeId) => byId[typeId])
-    .map(({ id, data }) => ({
-      id,
-      ...data,
-      labelText: tMap(data.label, {
-        path: ["media-types", id, "label"],
-      }),
+  tContentField: TranslateContentFieldFn,
+) {
+  const contentTypes = await contentTypesLoader.get()
+  const mediaTypes = await getTranslatedMediaTypes(currentLocale, tContentField)
+  return mediaTypes.filter(({ id }) => contentTypes.has(id))
+}
+
+export async function getTranslatedMediaTypes(
+  currentLocale: string,
+  tContentField: TranslateContentFieldFn,
+) {
+  const mediaTypes = Object.values(await typesById.get())
+  return mediaTypes
+    .map((mediaType) => ({
+      id: mediaType.id,
+      ...mediaType.data,
+      labelText: tContentField(mediaType.data.label, mediaType),
     }))
     .sort((a, b) => a.labelText.localeCompare(b.labelText, currentLocale))
 }

package/src/content/query-media-items.ts

@@ -1,4 +1,5 @@
-import type { MediaCollectionEntry, MediaItemEntry } from "./content-schema"
+import type { MediaCollectionEntry } from "./schema/media-collection"
+import type { MediaItemEntry } from "./schema/media-item"
 
 export type MediaItemQuery<TMediaItem extends MediaItemEntry> = {
   /**

package/src/content/schema/category.ts

@@ -0,0 +1,40 @@
+import { z } from "astro/zod"
+import type { SchemaContext } from "astro:content"
+
+import { translationMapSchema } from "../../i18n/translation-map-schema"
+import { imageSchema } from "../astro-image"
+
+/**
+ * Category Schema
+ */
+export const categorySchema = z.object({
+  /**
+   * Name of the category.
+   *
+   * Label translated for the default locale. Other configured site locales are optional.
+   */
+  label: translationMapSchema,
+
+  /* Relative path to the thumbnail image of this category.
+   *
+   * The image is expected to be inside the `images` folder next to category definition json.
+   * It can have one of these file types: png, jpg, tiff, webp, gif, svg, avif.
+   * We suggest to give it a size of at least 1000px for it's longer side.
+   *
+   * @example "./images/devotionals.jpg"
+   */
+  image: imageSchema.optional(),
+})
+
+export const createCategorySchema = ({ image }: SchemaContext) =>
+  categorySchema.extend({
+    image: image().optional(),
+  })
+
+export const categoryEntrySchema = z.object({
+  id: z.string(),
+  collection: z.literal("categories"),
+  data: categorySchema,
+})
+
+export type CategoryEntry = z.infer<typeof categoryEntrySchema>

package/src/content/schema/media-collection.ts

@@ -0,0 +1,31 @@
+import { z } from "astro/zod"
+import { reference } from "astro:content"
+
+import { translationMapSchema } from "../../i18n/translation-map-schema"
+
+/**
+ * Media Collection Schema
+ */
+export const mediaCollectionSchema = z.object({
+  /**
+   * Name of the collection.
+   *
+   * Label translated for the default locale. Other configured site locales are optional.
+   */
+  label: translationMapSchema,
+  /**
+   * Ordered list of media items included in this collection.
+   * The array order defines how items are shown when querying by collection.
+   *
+   * @example ["my-book--en", "my-video--en"]
+   */
+  mediaItems: z.array(reference("media")),
+})
+
+export const mediaCollectionEntrySchema = z.object({
+  id: z.string(),
+  collection: z.literal("media-collections"),
+  data: mediaCollectionSchema,
+})
+
+export type MediaCollectionEntry = z.infer<typeof mediaCollectionEntrySchema>

package/src/content/schema/media-item.ts

@@ -0,0 +1,137 @@
+import { z } from "astro/zod"
+import type { SchemaContext } from "astro:content"
+import { reference } from "astro:content"
+
+import { translationMapSchema } from "../../i18n/translation-map-schema"
+import { imageSchema } from "../astro-image"
+
+/**
+ * Media Item Schema
+ */
+export const mediaItemSchema = z.object({
+  /**
+   * Optional identifier used to link translated variants of a media item.
+   * If other media items share the same commonId they will show up as translations.
+   * If omitted, the media item is treated as standalone and has no translations.
+   * The common id will show up in the media item's url combined with it's language.
+   *
+   * We suggest you use the english name of the media item, all lower case, words separated with hyphens.
+   *
+   * @example "a-book-about-love"
+   */
+  commonId: z.string().optional(),
+  /**
+   * Title of this media item.
+   * This is expected to be in the language that is defined by the 'language' property.
+   *
+   * @example "A book about love"
+   */
+  title: z.string(),
+  /**
+   * References one media-type by its filename without .json suffix.
+   *
+   * @example "book"
+   */
+  type: reference("media-types"),
+  /**
+   *Describes this media item. You can use markdown syntax to add formatting.
+   * This is expected to be in the language that is defined by the 'language' property.
+   *
+   * @example "This is a book about **love**..."
+   */
+  description: z.string().optional(),
+  /**
+   * List of authors of this media item.
+   *
+   * @example ["George Miller", "Timothy Meier"]
+   */
+  authors: z.array(z.string()).nullish(),
+  /**
+   * Date this media item has been created on this lightnet instance.
+   * Format is YYYY-MM-DD
+   *
+   * @example 2024-09-10
+   */
+  dateCreated: z.iso.date(),
+  /**
+   * List of categories of this media item.
+   *
+   * @example ["family"]
+   */
+  categories: z.array(reference("categories")).nullish(),
+  /**
+   * BCP-47 language code of this media item.
+   *
+   * @example "en"
+   */
+  language: z.string().nonempty(),
+  /**
+   * Relative path to the image of this media item. Eg. a book cover or video thumbnail.
+   *
+   * The image is expected to be inside the `images` folder next to the media item definition json.
+   * This image will be used for previews and on the media item detail page.
+   * It can have one of these file types: png, jpg, tiff, webp, gif, svg, avif.
+   * We suggest to give it a size of at least 1000px for it's longer side.
+   *
+   * @example "./images/a-book-about-love--en.jpg"
+   */
+  image: imageSchema,
+  /**
+   * List of objects defining the content of this media item.
+   */
+  content: z
+    .array(
+      z.object({
+        /**
+         * Storage kind for this content item.
+         *
+         * - `"upload"`: a file managed by this LightNet site (typically a relative path like `/files/...`)
+         * - `"link"`: an external URL (typically `https://...`)
+         *
+         * @example "upload"
+         */
+        type: z.enum(["upload", "link"]),
+        /**
+         * Urls might be:
+         * - links to youtube videos
+         * - links to vimeo videos
+         * - links to .mp4 video files
+         * - links to .mp3 audio files
+         * - links to external websites
+         * - links to pdfs (might be hosted inside the public/files/ folder)
+         * - links to epubs (might be hosted inside the public/files/ folder)
+         *
+         * @example "/files/a-book-about-love.pdf"
+         */
+        url: z.string(),
+        /**
+         * The name of the content translated for the default locale.
+         * Other configured site locales are optional.
+         * If this is not set, the file name from URL will be used.
+         */
+        label: translationMapSchema.optional(),
+      }),
+    )
+    .min(1),
+})
+
+/**
+ * MediaItemSchema above defines the shape of a media item.
+ * We need this function to accept the astro content's image function that
+ * is available inside defineCollection.
+ *
+ * @param schemaContext that is passed by astro's defineCollection schema.
+ * @returns schema with image mixed in.
+ */
+export const createMediaItemSchema = ({ image }: SchemaContext) =>
+  mediaItemSchema.extend({
+    image: image(),
+  })
+
+export const mediaItemEntrySchema = z.object({
+  id: z.string(),
+  collection: z.literal("media"),
+  data: mediaItemSchema,
+})
+
+export type MediaItemEntry = z.infer<typeof mediaItemEntrySchema>

package/src/content/schema/media-type.ts

@@ -0,0 +1,90 @@
+import { z } from "astro/zod"
+
+import { translationMapSchema } from "../../i18n/translation-map-schema"
+
+/**
+ * Media Type Schema
+ */
+export const mediaTypeSchema = z.object({
+  /**
+   * Name of this media type that will be shown on the pages.
+   *
+   * Label translated for the default locale. Other configured site locales are optional.
+   */
+  label: translationMapSchema,
+  /**
+   * Defines how the cover image for a media item of this type is rendered.
+   *
+   * Options:
+   * - `"default"` — Renders the media item image with no modifications.
+   * - `"book"` — Adds a book fold effect and sharper edges, styled like a book cover.
+   * - `"video"` — Constrains the image to a 16:9 aspect ratio with a black background.
+   *
+   * @default "default"
+   */
+  coverImageStyle: z.enum(["default", "book", "video"]).default("default"),
+  /**
+   * What media item details page to use for media items with this type.
+   *
+   */
+  detailsPage: z
+    .discriminatedUnion("layout", [
+      z.object({
+        /**
+         * Details page for all media types.
+         */
+        layout: z.literal("default"),
+        /**
+         * Label for the open action button. Use this if you want to change the text
+         * of the "Open" button to be more matching to your media item.
+         * For example you could change the text to be "Read" for a book media type.
+         *
+         * Label translated for the default locale. Other configured site locales are optional.
+         */
+        openActionLabel: translationMapSchema.optional(),
+      }),
+      z.object({
+        /**
+         * Custom details page.
+         */
+        layout: z.literal("custom"),
+        /**
+         * This references a custom component name to be used for the
+         * details page. The custom component has be located at src/details-pages/
+         *
+         * @example "MyArticleDetails.astro"
+         */
+        customComponent: z.string(),
+      }),
+      z.object({
+        /**
+         * Detail page for videos.
+         */
+        layout: z.literal("video"),
+      }),
+      z.object({
+        /**
+         * Detail page for audio files.
+         *
+         * This only supports mp3 files.
+         */
+        layout: z.literal("audio"),
+      }),
+    ])
+    .optional(),
+  /**
+   * Pick the media type's icon from https://lucide.dev/icons/
+   * Prefix it's name with "lucide--"
+   *
+   * @example "lucide--book-open"
+   */
+  icon: z.string(),
+})
+
+export const mediaTypeEntrySchema = z.object({
+  id: z.string(),
+  collection: z.literal("media-types"),
+  data: mediaTypeSchema,
+})
+
+export type MediaTypeEntry = z.infer<typeof mediaTypeEntrySchema>

package/src/i18n/locals.d.ts

@@ -33,6 +33,28 @@ type I18n = {
    */
   tMap: import("./translate-map").TranslateMapFn
 
+  /**
+   * Resolve an inline translation map that belongs to LightNet config.
+   *
+   * Use this for translated values read from the resolved runtime config,
+   * such as the site title or configured language labels.
+   *
+   * @param translationMap Localized values keyed by locale code.
+   * @param config The resolved LightNet config object that owns the field.
+   */
+  tConfigField: import("./translate-map").TranslateConfigFieldFn
+
+  /**
+   * Resolve an inline translation map that belongs to a content entry.
+   *
+   * Use this for translated values stored inside content collections,
+   * such as category labels, media type labels, or content item labels.
+   *
+   * @param translationMap Localized values keyed by locale code.
+   * @param contentEntry The content entry that owns the translated field.
+   */
+  tContentField: import("./translate-map").TranslateContentFieldFn
+
   /**
    *  The current locale resolved by LightNet from the URL pathname.
    *

package/src/i18n/locals.ts

@@ -20,11 +20,13 @@ export const onRequest: MiddlewareHandler = async ({ locals, url }, next) => {
       useTranslate(currentLocale),
       getTranslationKeys(),
     ])
-    const tMap = useTranslateMap(currentLocale)
+    const { tMap, tConfigField, tContentField } = useTranslateMap(currentLocale)
     const { direction } = resolveLanguage(currentLocale)
     locals.i18n = {
       t,
       tMap,
+      tConfigField,
+      tContentField,
       currentLocale,
       defaultLocale,
       direction,

package/src/i18n/record-translation.ts

@@ -0,0 +1,74 @@
+import { createWriteStream } from "node:fs"
+import { mkdir, unlink, writeFile } from "node:fs/promises"
+import { resolve } from "node:path"
+import process from "node:process"
+
+import { root } from "astro:config/server"
+import config from "virtual:lightnet/config"
+
+import { lazy } from "../utils/lazy"
+
+type Translation = {
+  type: "map" | "user" | "lightnet"
+  key: string
+  values: Record<string, string | undefined>
+}
+
+const lightnetCachePath = resolve(
+  root.pathname,
+  "node_modules",
+  ".cache",
+  "lightnet",
+)
+
+const recordedTranslations = new Set<string>()
+
+const translationStore = lazy(() => createTranslationStore())
+
+const writeLanguagesManifest = async () => {
+  const manifestPath = resolve(lightnetCachePath, "languages.json")
+  const { defaultLocale, locales } = config
+  const manifest = {
+    defaultLocale,
+    locales,
+  }
+  await writeFile(manifestPath, JSON.stringify(manifest), "utf-8")
+}
+
+const createTranslationStore = async () => {
+  const translationStorePath = resolve(lightnetCachePath, "translations.jsonl")
+
+  await mkdir(lightnetCachePath, { recursive: true })
+  try {
+    await unlink(translationStorePath)
+  } catch {
+    // catch error if file has not been existing
+  }
+
+  const store = createWriteStream(translationStorePath, {
+    flags: "a",
+    encoding: "utf8",
+  })
+
+  await writeLanguagesManifest()
+
+  process.on("exit", () => store?.end())
+  process.on("SIGINT", () => store?.end())
+  return store
+}
+
+export async function recordTranslation(translation: Translation) {
+  if (!import.meta.env.PROD) {
+    // only record during build
+    return
+  }
+
+  const key = translation.type + translation.key
+  if (recordedTranslations.has(key)) {
+    return
+  }
+  recordedTranslations.add(key)
+
+  const store = await translationStore.get()
+  store.write(JSON.stringify(translation) + "\n")
+}