@intlayer/docs 9.1.3 → 9.3.0

package/blog/zh/intlayer_with_vue-i18n.md

@@ -55,11 +55,62 @@ author: aymericzip
 
 ---
 
-### 第2步：实现 Intlayer 插件以封装 JSON
+## Vue-i18n 与 Intlayer 的分步设置指南
 
-创建一个 Intlayer 配置文件以定义您支持的语言环境：
+<Steps>
 
-**如果您还想导出用于 vue-i18n 的 JSON 字典**，请添加 `syncJSON` 插件：
+<Step number={1} title="安装依赖项">
+
+使用您首选的包管理器安装必要的包：
+
+```bash packageManager="npm"
+npx intlayer init --interactive
+```
+
+```bash packageManager="pnpm"
+pnpm dlx intlayer@canary init --interactive
+```
+
+```bash packageManager="yarn"
+yarn dlx intlayer@canary init --interactive
+```
+
+```bash packageManager="bun"
+bunx intlayer@canary init --interactive
+```
+
+> `--interactive` 标志是可选的。如果您是 AI 代理，请使用 `intlayer-cli init`。
+
+> 此命令将检测您的环境并安装所需的包。例如：
+
+```bash packageManager="npm"
+npm install intlayer @intlayer/sync-json-plugin --save-dev
+```
+
+```bash packageManager="pnpm"
+pnpm add intlayer @intlayer/sync-json-plugin --save-dev
+```
+
+```bash packageManager="yarn"
+yarn add intlayer @intlayer/sync-json-plugin --dev
+```
+
+```bash packageManager="bun"
+bun add intlayer @intlayer/sync-json-plugin --dev
+```
+
+**包说明：**
+
+- **intlayer**：用于内容声明和管理的核心库
+- **@intlayer/sync-json-plugin**：将 Intlayer 内容声明同步到 vue-i18n JSON 格式的插件
+
+</Step>
+
+<Step number={2} title="实现 Intlayer 插件来包装 JSON">
+
+创建一个 Intlayer 配置文件来定义您支持的语言环境：
+
+**如果您还想为 vue-i18n 导出 JSON 字典**，请添加 `syncJSON` 插件：
 
 ```typescript fileName="intlayer.config.ts"
 import { Locales, type IntlayerConfig } from "intlayer";
@@ -81,16 +132,74 @@ const config: IntlayerConfig = {
 export default config;
 ```
 
-`syncJSON` 插件会自动包装 JSON。它会读取和写入 JSON 文件，而不会改变内容结构。
+`syncJSON` 插件将自动包装 JSON。它将读取和写入 JSON 文件，而不改变内容架构。
 
-如果你想让 JSON 与 intlayer 内容声明文件（`.content` 文件）共存，Intlayer 会按以下方式处理：
+如果您想让 JSON 与 intlayer 内容声明文件（`.content` 文件）共存，Intlayer 将按照以下方式处理：
 
 1. 加载 JSON 和内容声明文件，并将它们转换为 intlayer 字典。
-2. 如果 JSON 和内容声明文件之间存在冲突，Intlayer 会合并所有字典。具体合并方式取决于插件的优先级以及内容声明文件的优先级（所有优先级均可配置）。
+2. 如果 JSON 和内容声明文件之间存在冲突，Intlayer 将合并所有字典。根据插件的优先级和内容声明文件的优先级（都是可配置的）。
+
+如果使用 CLI 或 CMS 对 JSON 进行更改以翻译内容，Intlayer 将使用新的翻译更新 JSON 文件。
+
+有关 `syncJSON` 插件的更多详细信息，请参阅 [syncJSON 插件文档](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/plugins/sync-json.md)。
+
+</Step>
+
+<Step number={3} title="设置 AI 提供商">
+
+Intlayer 为您的 i18next 工作流解锁了一系列高级自动化和开发者友好的功能。
+
+- **自动检测和填充缺失的翻译**：Intlayer 扫描您的 JSON 字典，找到未翻译或缺失的键，仅翻译这些部分，因此您的 JSON 的 99% 保持不变。
+- **大型 JSON 文件的分块翻译**：当您的翻译文件非常大时，Intlayer 自动将处理分成可管理的块，独立翻译它们以避免 API 限制和内存问题。
+- **命名空间并行化**：如果您有数百个命名空间（或文件），Intlayer 将并行化翻译任务，有效加快 CI/CD 或批量翻译操作的速度。
+- **灵活的 AI 提供商支持**：选择您首选的 AI 提供商（例如 OpenAI、Claude、Gemini），只需配置凭据即可。使用您自己的 API 密钥，并根据需要切换提供商。
+- **强大的 AI 响应处理**：Intlayer 可以处理您的 AI 提供商将文本作为字符串或对象返回的边界情况，甚至在格式不一致时自动重试。
+- **CLI 和 CI/CD 就绪**：直接在您的测试或管道中运行 Intlayer 的检查和自动填充，使您的本地化过程强大且自动化。
+- **集成到您现有的设置之上**：您不需要改变您的 i18next 或 Next.js 基础。Intlayer 作为您当前设置的附加插件，为您提供所有这些好处，同时最小化迁移。
+
+以下是如何设置 AI 提供商的示例：
+
+```ts fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+import { loadJSON, syncJSON } from "@intlayer/sync-json-plugin";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    defaultLocale: Locales.ENGLISH,
+  },
+  ai: {
+    provider: "openai",
+    model: "gpt-5-mini",
+    apiKey: process.env.OPENAI_API_KEY,
+  },
+  plugins: [
+    syncJSON({
+      format: "vue-i18n",
+      source: ({ key, locale }) => `./src/locales/${locale}/${key}.json`,
+    }),
+  ],
+};
+
+export default config;
+```
+
+然后您可以执行以下命令来填充您的翻译：
+
+```bash
+npx intlayer fill
+```
+
+这将使用您配置的 AI 提供商填充您的翻译。
+
+> 在 [Intlayer AI 配置文档](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/configuration.md#ai-configuration) 中查看所有可用的 AI 提供商。
+> 在 [Intlayer CLI 文档](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/cli/index.md) 中查看所有可用的命令。
+
+---
 
-如果通过 CLI 翻译 JSON 或使用 CMS 进行更改，Intlayer 会使用新的翻译更新 JSON 文件。
+</Step>
 
-要查看更多关于 `syncJSON` 插件的详细信息，请参阅 [syncJSON 插件文档](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/plugins/sync-json.md)。
+</Steps>
 
 ## Git 配置
 

package/blog/zh/rag_powered_documentation_assistant.md

@@ -79,6 +79,12 @@ author: aymericzip
 
 每个向量都是文本的数学指纹，支持相似度搜索。
 
+## 使用 Sanity 跳过复杂性
+
+Sanity 值得在此提及，作为本文指向的 CMS 选项。Markdown 文件需要任意的 token 拆分——具有文章所描述的分块大小和重叠权衡——而 Sanity 的 Content Lake 将文档存储为类型化的、架构定义的 JSON 文档。每个字段、标题和内容块已经是一个语义单元，这意味着 RAG 检索在有意义的边界上操作，而不是近似的 token 计数。
+
+Sanity 的 GROQ 查询语言让你能够检索与用户查询相关的确切文档字段——标题、正文、相关部分——而无需获取整个文档。MCP 服务器将 Content Lake 直接连接到 AI 代理，因此为文档网站提供支持的相同结构化内容也会馈送到你的 RAG 管道中，无需单独的摄入步骤。
+
 ## 结论
 
 RAG 是使大型语言模型（LLM）实用的最简单且最强大的方法之一。通过结合**检索 + 生成**，您可以将静态文档转变为**智能助手**，同时获得持续的产品洞察流。

package/dist/cjs/common.cjs

@@ -48,12 +48,35 @@ const getFileMetadata = async (files, docKey, locale = defaultLocale) => {
 	const file = await getFile(files, docKey, locale);
 	return formatMetadata(docKey, file, locale);
 };
-const getFileMetadataRecord = async (files, locale = defaultLocale) => {
+/**
+* Per-locale metadata records, keyed by the entry map they were built from.
+*
+* Building a record parses the frontmatter of every document of a category, and
+* callers such as {@link getFileMetadataBySlug} need the whole record just to
+* resolve a single slug — which a static site generator repeats for every page
+* it renders. Documents are read once per process anyway (each entry caches its
+* own read), so the derived metadata is equally safe to keep.
+*/
+const fileMetadataRecordCache = /* @__PURE__ */ new WeakMap();
+const buildFileMetadataRecord = async (files, locale) => {
 	const filesEntries = (await Promise.allSettled(Object.entries(files).map(async ([key]) => {
 		return [key, await getFileMetadata(files, key, locale)];
 	}))).filter((r) => r.status === "fulfilled").map((r) => r.value);
 	return Object.fromEntries(filesEntries);
 };
+const getFileMetadataRecord = async (files, locale = defaultLocale) => {
+	let localeCache = fileMetadataRecordCache.get(files);
+	if (!localeCache) {
+		localeCache = /* @__PURE__ */ new Map();
+		fileMetadataRecordCache.set(files, localeCache);
+	}
+	let record = localeCache.get(locale);
+	if (!record) {
+		record = buildFileMetadataRecord(files, locale);
+		localeCache.set(locale, record);
+	}
+	return await record;
+};
 const getFileMetadataBySlug = async (files, slugs, locale = defaultLocale, strict = false) => {
 	const slugsArray = Array.isArray(slugs) ? slugs : [slugs];
 	const filesMetadata = await getFileMetadataRecord(files, defaultLocale);

package/dist/cjs/common.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"common.cjs","names":["Locales"],"sources":["../../src/common.ts"],"sourcesContent":["import { join } from 'node:path';\nimport { getLocalizedUrl } from '@intlayer/core/localization';\nimport { getMarkdownMetadata } from '@intlayer/core/transpiler';\nimport * as Locales from '@intlayer/types/locales';\nimport type { LocalesValues } from '@intlayer/types/module_augmentation';\n\nexport const defaultLocale = Locales.ENGLISH;\n\nexport const GITHUB_URL_PREFIX =\n  'https://github.com/aymericzip/intlayer/blob/main/docs';\nexport const URL_PREFIX = 'https://intlayer.org/';\n\nexport const getKeys = <T extends Record<string, any>>(obj: T): (keyof T)[] =>\n  Object.keys(obj) as (keyof T)[];\n\nexport const getFiles = async <\n  F extends Record<`./${string}`, Record<LocalesValues, Promise<string>>>,\n>(\n  files: F,\n  lang: LocalesValues = defaultLocale as LocalesValues\n): Promise<Record<string, string>> => {\n  const filesEntries = await Promise.all(\n    Object.entries(files)\n      .map(([key, value]) => [key, value[lang as LocalesValues]])\n      .map(async ([key, value]) => [key, await value])\n  );\n  const filesResult = Object.fromEntries(filesEntries);\n  return filesResult;\n};\n\nexport const getFile = async <\n  F extends Record<string, Record<LocalesValues, Promise<string>>>,\n>(\n  files: F,\n  docKey: keyof F,\n  locale: LocalesValues = defaultLocale as LocalesValues\n): Promise<string> => {\n  const fileRecord = files[docKey];\n\n  if (!fileRecord) {\n    throw new Error(`File ${docKey as string} not found`);\n  }\n\n  const file = await files[docKey]?.[locale];\n\n  if (!file) {\n    const englishFile = await files[docKey]?.[defaultLocale as LocalesValues];\n\n    if (!englishFile) {\n      throw new Error(`File ${docKey as string} not found`);\n    }\n\n    return englishFile;\n  }\n\n  return file;\n};\n\nexport type FileMetadata = {\n  docKey: string;\n  url: string;\n  relativeUrl: string;\n  githubUrl: string;\n  title: string;\n  slugs: string[];\n  description: string;\n  keywords: string[];\n  updatedAt: string;\n  createdAt: string;\n  author?: string;\n  youtubeVideo?: string;\n  applicationTemplate?: string;\n  applicationShowcase?: string;\n  history?: {\n    version: string;\n    date: string;\n    changes: string;\n  }[];\n};\n\nexport const formatMetadata = (\n  docKey: string,\n  file: string,\n  locale: LocalesValues = defaultLocale as LocalesValues\n): FileMetadata => {\n  const metadata = getMarkdownMetadata(file);\n\n  const slugs = (metadata.slugs ?? []).map(String);\n  const keywords = (metadata.keywords ?? []).map(String);\n\n  const relativeUrl = join('/', ...slugs);\n\n  const slicedDocKey = docKey.slice(1);\n\n  // Normalise author: accept both a plain string handle (new format)\n  // and a legacy object `{ github: '...' }` — always reduce to a plain string.\n  const rawAuthor = metadata.author as\n    | string\n    | { name?: string; github?: string }\n    | undefined;\n  const author: string | undefined =\n    typeof rawAuthor === 'string'\n      ? rawAuthor || undefined\n      : rawAuthor?.github || undefined;\n\n  return {\n    ...metadata,\n    docKey,\n    slugs,\n    keywords,\n    author,\n    githubUrl: `${GITHUB_URL_PREFIX}${slicedDocKey}`.replace(\n      '/en/',\n      `/${locale}/`\n    ),\n    relativeUrl: getLocalizedUrl(relativeUrl, locale),\n    url: getLocalizedUrl(join(URL_PREFIX, relativeUrl), locale),\n  } as FileMetadata;\n};\n\nexport const getFileMetadata = async <\n  F extends Record<string, Record<LocalesValues, Promise<string>>>,\n  R extends FileMetadata,\n>(\n  files: F,\n  docKey: keyof F,\n  locale: LocalesValues = defaultLocale as LocalesValues\n): Promise<R> => {\n  const file = await getFile(files, docKey, locale);\n\n  return formatMetadata(docKey as string, file, locale) as R;\n};\n\nexport const getFileMetadataRecord = async <\n  F extends Record<string, Record<LocalesValues, Promise<string>>>,\n>(\n  files: F,\n  locale: LocalesValues = defaultLocale as LocalesValues\n): Promise<Record<keyof F, FileMetadata>> => {\n  const results = await Promise.allSettled(\n    Object.entries(files).map(async ([key]) => {\n      const metadata = await getFileMetadata(files, key as keyof F, locale);\n      return [key, metadata] as [string, FileMetadata];\n    })\n  );\n  const filesEntries = results\n    .filter(\n      (r): r is PromiseFulfilledResult<[string, FileMetadata]> =>\n        r.status === 'fulfilled'\n    )\n    .map((r) => r.value);\n  const filesResult = Object.fromEntries(filesEntries);\n  return filesResult as Record<keyof F, FileMetadata>;\n};\n\nexport const getFileMetadataBySlug = async <\n  F extends Record<string, Record<LocalesValues, Promise<string>>>,\n>(\n  files: F,\n  slugs: string | string[],\n  locale: LocalesValues = defaultLocale as LocalesValues,\n  strict = false\n) => {\n  const slugsArray = Array.isArray(slugs) ? slugs : [slugs];\n  const filesMetadata = await getFileMetadataRecord(\n    files,\n    defaultLocale as LocalesValues\n  );\n\n  let fileMetadataArray: FileMetadata[] = Object.values(filesMetadata).filter(\n    (fileMetadata) =>\n      slugsArray.every((slug) => fileMetadata.slugs?.includes(slug))\n  );\n\n  if (strict) {\n    fileMetadataArray = fileMetadataArray.filter(\n      (fileMetadata) => fileMetadata.slugs.length === slugsArray.length\n    );\n  }\n\n  if (locale !== defaultLocale) {\n    const localizedFileMetadata = await Promise.all(\n      fileMetadataArray.map(\n        async (fileMetadata) =>\n          await getFileMetadata(files, fileMetadata.docKey, locale)\n      )\n    );\n\n    return localizedFileMetadata;\n  }\n\n  return fileMetadataArray;\n};\n\nexport const getFileBySlug = async <\n  F extends Record<string, Record<LocalesValues, Promise<string>>>,\n>(\n  files: F,\n  slugs: string | string[],\n  locale: LocalesValues = defaultLocale as LocalesValues,\n  strict = false\n) => {\n  const slugsArray = Array.isArray(slugs) ? slugs : [slugs];\n  const filesMetadata = await getFileMetadataRecord(\n    files,\n    defaultLocale as LocalesValues\n  );\n\n  let fileMetadataArray = Object.values(filesMetadata).filter((fileMetadata) =>\n    slugsArray.every((slug) => fileMetadata.slugs?.includes(slug))\n  );\n\n  if (strict) {\n    fileMetadataArray = fileMetadataArray.filter(\n      (fileMetadata) => fileMetadata.slugs.length === slugsArray.length\n    );\n  }\n\n  const fileList = await Promise.all(\n    fileMetadataArray.map(async (fileMetadata) => {\n      const file = await getFile(files, fileMetadata.docKey, locale);\n      return file;\n    })\n  );\n\n  return fileList;\n};\n"],"mappings":";;;;;;;;;AAMA,MAAa,gBAAgBA,wBAAQ;AAErC,MAAa,oBACX;AACF,MAAa,aAAa;AAE1B,MAAa,WAA0C,QACrD,OAAO,KAAK,GAAG;AAEjB,MAAa,WAAW,OAGtB,OACA,OAAsB,kBACc;CACpC,MAAM,eAAe,MAAM,QAAQ,IACjC,OAAO,QAAQ,KAAK,CAAC,CAClB,KAAK,CAAC,KAAK,WAAW,CAAC,KAAK,MAAM,KAAsB,CAAC,CAAC,CAC1D,IAAI,OAAO,CAAC,KAAK,WAAW,CAAC,KAAK,MAAM,KAAK,CAAC,CACnD;CAEA,OADoB,OAAO,YAAY,YACtB;AACnB;AAEA,MAAa,UAAU,OAGrB,OACA,QACA,SAAwB,kBACJ;CAGpB,IAAI,CAFe,MAAM,SAGvB,MAAM,IAAI,MAAM,QAAQ,OAAiB,WAAW;CAGtD,MAAM,OAAO,MAAM,MAAM,OAAO,GAAG;CAEnC,IAAI,CAAC,MAAM;EACT,MAAM,cAAc,MAAM,MAAM,OAAO,GAAG;EAE1C,IAAI,CAAC,aACH,MAAM,IAAI,MAAM,QAAQ,OAAiB,WAAW;EAGtD,OAAO;CACT;CAEA,OAAO;AACT;AAwBA,MAAa,kBACX,QACA,MACA,SAAwB,kBACP;CACjB,MAAM,8DAA+B,IAAI;CAEzC,MAAM,SAAS,SAAS,SAAS,CAAC,EAAC,CAAE,IAAI,MAAM;CAC/C,MAAM,YAAY,SAAS,YAAY,CAAC,EAAC,CAAE,IAAI,MAAM;CAErD,MAAM,kCAAmB,KAAK,GAAG,KAAK;CAEtC,MAAM,eAAe,OAAO,MAAM,CAAC;CAInC,MAAM,YAAY,SAAS;CAI3B,MAAM,SACJ,OAAO,cAAc,WACjB,aAAa,SACb,WAAW,UAAU;CAE3B,OAAO;EACL,GAAG;EACH;EACA;EACA;EACA;EACA,WAAW,GAAG,oBAAoB,eAAe,QAC/C,QACA,IAAI,OAAO,EACb;EACA,8DAA6B,aAAa,MAAM;EAChD,0EAA0B,YAAY,WAAW,GAAG,MAAM;CAC5D;AACF;AAEA,MAAa,kBAAkB,OAI7B,OACA,QACA,SAAwB,kBACT;CACf,MAAM,OAAO,MAAM,QAAQ,OAAO,QAAQ,MAAM;CAEhD,OAAO,eAAe,QAAkB,MAAM,MAAM;AACtD;AAEA,MAAa,wBAAwB,OAGnC,OACA,SAAwB,kBACmB;CAO3C,MAAM,gBAAe,MANC,QAAQ,WAC5B,OAAO,QAAQ,KAAK,CAAC,CAAC,IAAI,OAAO,CAAC,SAAS;EAEzC,OAAO,CAAC,KAAK,MADU,gBAAgB,OAAO,KAAgB,MAAM,CAC/C;CACvB,CAAC,CACH,EAC4B,CACzB,QACE,MACC,EAAE,WAAW,WACjB,CAAC,CACA,KAAK,MAAM,EAAE,KAAK;CAErB,OADoB,OAAO,YAAY,YACtB;AACnB;AAEA,MAAa,wBAAwB,OAGnC,OACA,OACA,SAAwB,eACxB,SAAS,UACN;CACH,MAAM,aAAa,MAAM,QAAQ,KAAK,IAAI,QAAQ,CAAC,KAAK;CACxD,MAAM,gBAAgB,MAAM,sBAC1B,OACA,aACF;CAEA,IAAI,oBAAoC,OAAO,OAAO,aAAa,CAAC,CAAC,QAClE,iBACC,WAAW,OAAO,SAAS,aAAa,OAAO,SAAS,IAAI,CAAC,CACjE;CAEA,IAAI,QACF,oBAAoB,kBAAkB,QACnC,iBAAiB,aAAa,MAAM,WAAW,WAAW,MAC7D;CAGF,IAAI,WAAW,eAQb,OAAO,MAP6B,QAAQ,IAC1C,kBAAkB,IAChB,OAAO,iBACL,MAAM,gBAAgB,OAAO,aAAa,QAAQ,MAAM,CAC5D,CACF;CAKF,OAAO;AACT;AAEA,MAAa,gBAAgB,OAG3B,OACA,OACA,SAAwB,eACxB,SAAS,UACN;CACH,MAAM,aAAa,MAAM,QAAQ,KAAK,IAAI,QAAQ,CAAC,KAAK;CACxD,MAAM,gBAAgB,MAAM,sBAC1B,OACA,aACF;CAEA,IAAI,oBAAoB,OAAO,OAAO,aAAa,CAAC,CAAC,QAAQ,iBAC3D,WAAW,OAAO,SAAS,aAAa,OAAO,SAAS,IAAI,CAAC,CAC/D;CAEA,IAAI,QACF,oBAAoB,kBAAkB,QACnC,iBAAiB,aAAa,MAAM,WAAW,WAAW,MAC7D;CAUF,OAAO,MAPgB,QAAQ,IAC7B,kBAAkB,IAAI,OAAO,iBAAiB;EAE5C,OAAO,MADY,QAAQ,OAAO,aAAa,QAAQ,MAAM;CAE/D,CAAC,CACH;AAGF"}
+{"version":3,"file":"common.cjs","names":["Locales"],"sources":["../../src/common.ts"],"sourcesContent":["import { join } from 'node:path';\nimport { getLocalizedUrl } from '@intlayer/core/localization';\nimport { getMarkdownMetadata } from '@intlayer/core/transpiler';\nimport * as Locales from '@intlayer/types/locales';\nimport type { LocalesValues } from '@intlayer/types/module_augmentation';\n\nexport const defaultLocale = Locales.ENGLISH;\n\nexport const GITHUB_URL_PREFIX =\n  'https://github.com/aymericzip/intlayer/blob/main/docs';\nexport const URL_PREFIX = 'https://intlayer.org/';\n\nexport const getKeys = <T extends Record<string, any>>(obj: T): (keyof T)[] =>\n  Object.keys(obj) as (keyof T)[];\n\nexport const getFiles = async <\n  F extends Record<`./${string}`, Record<LocalesValues, Promise<string>>>,\n>(\n  files: F,\n  lang: LocalesValues = defaultLocale as LocalesValues\n): Promise<Record<string, string>> => {\n  const filesEntries = await Promise.all(\n    Object.entries(files)\n      .map(([key, value]) => [key, value[lang as LocalesValues]])\n      .map(async ([key, value]) => [key, await value])\n  );\n  const filesResult = Object.fromEntries(filesEntries);\n  return filesResult;\n};\n\nexport const getFile = async <\n  F extends Record<string, Record<LocalesValues, Promise<string>>>,\n>(\n  files: F,\n  docKey: keyof F,\n  locale: LocalesValues = defaultLocale as LocalesValues\n): Promise<string> => {\n  const fileRecord = files[docKey];\n\n  if (!fileRecord) {\n    throw new Error(`File ${docKey as string} not found`);\n  }\n\n  const file = await files[docKey]?.[locale];\n\n  if (!file) {\n    const englishFile = await files[docKey]?.[defaultLocale as LocalesValues];\n\n    if (!englishFile) {\n      throw new Error(`File ${docKey as string} not found`);\n    }\n\n    return englishFile;\n  }\n\n  return file;\n};\n\nexport type FileMetadata = {\n  docKey: string;\n  url: string;\n  relativeUrl: string;\n  githubUrl: string;\n  title: string;\n  slugs: string[];\n  description: string;\n  keywords: string[];\n  updatedAt: string;\n  createdAt: string;\n  author?: string;\n  youtubeVideo?: string;\n  applicationTemplate?: string;\n  applicationShowcase?: string;\n  history?: {\n    version: string;\n    date: string;\n    changes: string;\n  }[];\n};\n\nexport const formatMetadata = (\n  docKey: string,\n  file: string,\n  locale: LocalesValues = defaultLocale as LocalesValues\n): FileMetadata => {\n  const metadata = getMarkdownMetadata(file);\n\n  const slugs = (metadata.slugs ?? []).map(String);\n  const keywords = (metadata.keywords ?? []).map(String);\n\n  const relativeUrl = join('/', ...slugs);\n\n  const slicedDocKey = docKey.slice(1);\n\n  // Normalise author: accept both a plain string handle (new format)\n  // and a legacy object `{ github: '...' }` — always reduce to a plain string.\n  const rawAuthor = metadata.author as\n    | string\n    | { name?: string; github?: string }\n    | undefined;\n  const author: string | undefined =\n    typeof rawAuthor === 'string'\n      ? rawAuthor || undefined\n      : rawAuthor?.github || undefined;\n\n  return {\n    ...metadata,\n    docKey,\n    slugs,\n    keywords,\n    author,\n    githubUrl: `${GITHUB_URL_PREFIX}${slicedDocKey}`.replace(\n      '/en/',\n      `/${locale}/`\n    ),\n    relativeUrl: getLocalizedUrl(relativeUrl, locale),\n    url: getLocalizedUrl(join(URL_PREFIX, relativeUrl), locale),\n  } as FileMetadata;\n};\n\nexport const getFileMetadata = async <\n  F extends Record<string, Record<LocalesValues, Promise<string>>>,\n  R extends FileMetadata,\n>(\n  files: F,\n  docKey: keyof F,\n  locale: LocalesValues = defaultLocale as LocalesValues\n): Promise<R> => {\n  const file = await getFile(files, docKey, locale);\n\n  return formatMetadata(docKey as string, file, locale) as R;\n};\n\n/**\n * Per-locale metadata records, keyed by the entry map they were built from.\n *\n * Building a record parses the frontmatter of every document of a category, and\n * callers such as {@link getFileMetadataBySlug} need the whole record just to\n * resolve a single slug — which a static site generator repeats for every page\n * it renders. Documents are read once per process anyway (each entry caches its\n * own read), so the derived metadata is equally safe to keep.\n */\nconst fileMetadataRecordCache = new WeakMap<\n  Record<string, unknown>,\n  Map<LocalesValues, Promise<Record<string, FileMetadata>>>\n>();\n\nconst buildFileMetadataRecord = async <\n  F extends Record<string, Record<LocalesValues, Promise<string>>>,\n>(\n  files: F,\n  locale: LocalesValues\n): Promise<Record<keyof F, FileMetadata>> => {\n  const results = await Promise.allSettled(\n    Object.entries(files).map(async ([key]) => {\n      const metadata = await getFileMetadata(files, key as keyof F, locale);\n      return [key, metadata] as [string, FileMetadata];\n    })\n  );\n  const filesEntries = results\n    .filter(\n      (r): r is PromiseFulfilledResult<[string, FileMetadata]> =>\n        r.status === 'fulfilled'\n    )\n    .map((r) => r.value);\n  const filesResult = Object.fromEntries(filesEntries);\n  return filesResult as Record<keyof F, FileMetadata>;\n};\n\nexport const getFileMetadataRecord = async <\n  F extends Record<string, Record<LocalesValues, Promise<string>>>,\n>(\n  files: F,\n  locale: LocalesValues = defaultLocale as LocalesValues\n): Promise<Record<keyof F, FileMetadata>> => {\n  let localeCache = fileMetadataRecordCache.get(files);\n\n  if (!localeCache) {\n    localeCache = new Map();\n    fileMetadataRecordCache.set(files, localeCache);\n  }\n\n  let record = localeCache.get(locale);\n\n  if (!record) {\n    record = buildFileMetadataRecord(files, locale);\n    localeCache.set(locale, record);\n  }\n\n  return (await record) as Record<keyof F, FileMetadata>;\n};\n\nexport const getFileMetadataBySlug = async <\n  F extends Record<string, Record<LocalesValues, Promise<string>>>,\n>(\n  files: F,\n  slugs: string | string[],\n  locale: LocalesValues = defaultLocale as LocalesValues,\n  strict = false\n) => {\n  const slugsArray = Array.isArray(slugs) ? slugs : [slugs];\n  const filesMetadata = await getFileMetadataRecord(\n    files,\n    defaultLocale as LocalesValues\n  );\n\n  let fileMetadataArray: FileMetadata[] = Object.values(filesMetadata).filter(\n    (fileMetadata) =>\n      slugsArray.every((slug) => fileMetadata.slugs?.includes(slug))\n  );\n\n  if (strict) {\n    fileMetadataArray = fileMetadataArray.filter(\n      (fileMetadata) => fileMetadata.slugs.length === slugsArray.length\n    );\n  }\n\n  if (locale !== defaultLocale) {\n    const localizedFileMetadata = await Promise.all(\n      fileMetadataArray.map(\n        async (fileMetadata) =>\n          await getFileMetadata(files, fileMetadata.docKey, locale)\n      )\n    );\n\n    return localizedFileMetadata;\n  }\n\n  return fileMetadataArray;\n};\n\nexport const getFileBySlug = async <\n  F extends Record<string, Record<LocalesValues, Promise<string>>>,\n>(\n  files: F,\n  slugs: string | string[],\n  locale: LocalesValues = defaultLocale as LocalesValues,\n  strict = false\n) => {\n  const slugsArray = Array.isArray(slugs) ? slugs : [slugs];\n  const filesMetadata = await getFileMetadataRecord(\n    files,\n    defaultLocale as LocalesValues\n  );\n\n  let fileMetadataArray = Object.values(filesMetadata).filter((fileMetadata) =>\n    slugsArray.every((slug) => fileMetadata.slugs?.includes(slug))\n  );\n\n  if (strict) {\n    fileMetadataArray = fileMetadataArray.filter(\n      (fileMetadata) => fileMetadata.slugs.length === slugsArray.length\n    );\n  }\n\n  const fileList = await Promise.all(\n    fileMetadataArray.map(async (fileMetadata) => {\n      const file = await getFile(files, fileMetadata.docKey, locale);\n      return file;\n    })\n  );\n\n  return fileList;\n};\n"],"mappings":"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"}