@openbooknetwork/kitap 0.0.0-stage → 0.3.0

package/src/cli.mjs

@@ -0,0 +1,41 @@
+// The command line of kitap and of every engine: the book's commands with the options they take. An engine's binary
+// calls run with its engine and its own commands, which are tried first.
+import { parseArgs } from 'util';
+import { build, check, dev, i18n, image, rehash, upload, deploy } from './index.mjs';
+
+export const USAGE = (name = 'kitap', extra = '') => `usage: ${name} build [--strict] [--local-assets] [--only <story> ...] [--story <id>] [--out <dir>] | ${name} check <story> [page id ...] [--places] | ${name} dev [--story <id>] [--out <dir>] [--port <n>] | ${name} i18n <lang> [--story id] | ${name} image <file or url> <name> --caption <text> [--credit <text>] [--source <url>] [--story <id>] | ${name} rehash | ${name} upload [--story <id>] [--dry-run] | ${name} deploy [--dry-run]${extra}`;
+
+// argv are the arguments after the command name. engine is the engine module to build with, else site.yaml names it.
+// own(cmd, positionals, options) runs an engine's own command and returns true when it took it. options adds flags.
+export async function run(argv, { name = 'kitap', engine = null, enginePath = null, own = null, options = {}, usage = '' } = {}) {
+  let args;
+  try {
+    args = parseArgs({ args: argv, allowPositionals: true, options: { strict: { type: 'boolean' }, 'local-assets': { type: 'boolean' }, 'dry-run': { type: 'boolean' }, places: { type: 'boolean' }, story: { type: 'string' }, caption: { type: 'string' }, credit: { type: 'string' }, source: { type: 'string' }, only: { type: 'string', multiple: true }, out: { type: 'string' }, port: { type: 'string' }, engine: { type: 'string' }, ...options } });
+  } catch (err) { // an unknown or incomplete flag
+    console.error(`${err.message}\n${USAGE(name, usage)}`);
+    process.exit(2);
+  }
+  const { positionals: [cmd, lang, ...rest], values: opt } = args;
+  // --engine names the engine module's path, as kitap dev hands it to each build; an engine's binary hands its own
+  const e = engine ?? (opt.engine ? (await import('./engine.mjs')).loadEngine(process.cwd(), opt.engine) : null);
+  try {
+    if (own && await own(cmd, [lang, ...rest].filter(x => x !== undefined), opt)) return;
+    if (cmd === 'build') await build({ strict: opt.strict, localAssets: opt['local-assets'], only: opt.only, story: opt.story, out: opt.out, engine: e });
+    else if (cmd === 'check' && lang) {
+      const problems = check({ story: lang, pages: rest, places: opt.places, engine: e });
+      for (const m of problems) console.log(m);
+      console.log(problems.length ? `${problems.length} problem${problems.length === 1 ? '' : 's'}` : 'ok');
+      process.exitCode = problems.length ? 1 : 0;
+    }
+    else if (cmd === 'i18n' && lang) i18n({ lang, story: opt.story, engine: e });
+    else if (cmd === 'image' && lang) await image({ file: lang, name: rest[0], caption: opt.caption, credit: opt.credit, source: opt.source, story: opt.story });
+    else if (cmd === 'rehash') rehash();
+    else if (cmd === 'upload') await upload({ story: opt.story, dryRun: opt['dry-run'], engine: e });
+    else if (cmd === 'deploy') await deploy({ dryRun: opt['dry-run'] });
+    else if (cmd === 'dev') dev({ story: opt.story, out: opt.out, engine: enginePath ?? opt.engine ?? null, ...(opt.port ? { port: Number(opt.port) } : {}) });
+    else { console.error(USAGE(name, usage)); process.exit(2); }
+  } catch (err) { // content errors are expected, print them without a stack trace
+    console.error(`error: ${err.message}`);
+    process.exit(1);
+  }
+}

package/src/common.js

@@ -0,0 +1,62 @@
+// Helpers shared by the story page and the site index. The build inlines this file into both.
+const $ = id => document.getElementById(id);
+const esc = s => String(s ?? '').replace(/[&<>"']/g, c => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]));
+
+// Per browser preferences. Storage can be missing or blocked, so every access is guarded.
+const pref = (key, allowed, fallback) => { try { const v = localStorage.getItem(key); return allowed.includes(v) ? v : fallback; } catch { return fallback; } };
+const savePref = (key, value) => { try { localStorage.setItem(key, value); } catch {} };
+// the saved language, else the first browser language on offer, matched whole or by its base such as pt for pt-BR
+const preferredLang = (langs, fallback) => {
+  const saved = pref('lang', langs, null); if (saved) return saved;
+  for (const l of navigator.languages ?? []) { const hit = langs.find(x => x.toLowerCase() === l.toLowerCase()) ?? langs.find(x => x === l.split('-')[0]); if (hit) return hit; }
+  return fallback;
+};
+
+// A translatable field for the current language, falling back to the default language.
+const pick = (field, lang, defaultLang, fallback = '') => field?.[lang] ?? field?.[defaultLang] ?? fallback;
+
+function fillSelect(sel, items, current, label) {
+  sel.setAttribute('aria-label', label); sel.innerHTML = '';
+  for (const { value, text } of items) { const o = document.createElement('option'); o.value = value; o.textContent = text; o.selected = value === current; sel.appendChild(o); }
+}
+
+// a web server resolves a folder to its index.html, a file:// URL shows a listing instead
+const isFile = location.protocol === 'file:';
+const folder = (...parts) => parts.join('/') + '/' + (isFile ? 'index.html' : '');
+// links from the site root, where a main page's <base> points, and from a story folder, where a story page's points
+const storyLink = (id, lang) => folder(id, lang);
+const siteLink = lang => folder('..', lang);
+// The route is the path under the folder the page's <base> names, such as en/cannae on a story page. pushState
+// refuses another path on file://, so there the address stays on the page first opened.
+const pathParts = () => {
+  const base = new URL(document.baseURI).pathname, p = decodeURIComponent(location.pathname);
+  return p.startsWith(base) ? p.slice(base.length).split('/').filter(s => s && s !== 'index.html') : [];
+};
+function setRoute(parts, push) {
+  if (isFile) return;
+  const url = new URL(parts.map(encodeURIComponent).join('/') + '/', document.baseURI).href;
+  if (url !== location.href) (push ? history.pushState : history.replaceState).call(history, null, '', url);
+}
+
+// The footer note on every page; the build fills in the repository URL from package.json
+const REPO = '/*__REPO__*/';
+const credit = ui => ui.generated_by.replace('{kitap}', `<a href="${REPO}" target="_blank" rel="noopener">kitap</a>`);
+
+const applyPalette = id => { document.documentElement.dataset.palette = id; savePref('palette', id); };
+
+// The story page layouts on wide screens: the picture in the middle, or the contents and the text together at one side.
+// Every page offers the choice in its settings, and story pages apply it.
+const LAYOUTS = ['center', 'left', 'right'];
+// a small drawing of a layout: the map filled, the chronology and the text as outlines, in their order on the screen
+function layoutIcon(l) {
+  const cols = { center: ['nav', 'map', 'text'], left: ['nav', 'text', 'map'], right: ['map', 'text', 'nav'] }[l], w = { nav: 12, text: 16, map: 28 };
+  let x = 1;
+  const parts = cols.map(c => { const r = c === 'map' ? `<rect x="${x}" y="1" width="${w[c]}" height="30" rx="1.5" fill="currentColor" opacity=".55"/>` : `<rect x="${x + .5}" y="1.5" width="${w[c] - 1}" height="29" rx="1.5" fill="none" stroke="currentColor"/>`; x += w[c] + 2; return r; });
+  return `<svg viewBox="0 0 61 32" aria-hidden="true">${parts.join('')}</svg>`;
+}
+const layoutButtons = (ui, current) => LAYOUTS.map(l => `<button type="button" role="radio" data-layout="${l}" aria-checked="${l === current}">${layoutIcon(l)}<span>${esc(ui['layout_' + l])}</span></button>`).join('');
+function saveLayout(l) {
+  savePref('layout', l); document.documentElement.dataset.layout = l;
+  $('layouts').querySelectorAll('button').forEach(b => b.setAttribute('aria-checked', b.dataset.layout === l));
+}
+const toggleLabel = (ui, allOpen) => allOpen ? ui.collapse_all : ui.expand_all;

package/src/deploy.mjs

@@ -0,0 +1,52 @@
+// kitap deploy: puts dist/ in the pages bucket the Worker serves, see worker.mjs. The files the bucket lacks or holds
+// in another version go up, scripts and stylesheets first, and the keys dist/ no longer holds go.
+import fs from 'fs';
+import path from 'path';
+import crypto from 'crypto';
+import yaml from 'js-yaml';
+import { check, Site } from './schema.mjs';
+import { storeWriter, pool } from './store.mjs';
+import { typeOf } from './routes.mjs';
+import { mb, plural, progressLine } from './util.mjs';
+
+const CACHE = 'public, max-age=600';
+
+// Puts root/dist in site.yaml's pages.bucket, in the account of assets.endpoint, and deletes the keys
+// dist/ lacks. dryRun lists what would go and change and writes nothing. Returns the keys uploaded and deleted, and
+// how many were in the bucket as they are.
+export async function deploy({ root = process.cwd(), dryRun = false, log = console.log, progress = progressLine, wait } = {}) {
+  const siteFile = path.join(root, 'site.yaml');
+  const site = fs.existsSync(siteFile) ? check(Site, yaml.load(fs.readFileSync(siteFile, 'utf8')), 'site.yaml') : {};
+  if (!site.pages) throw new Error('site.yaml: add a pages block with the bucket that holds the site, kitap deploy writes dist/ there');
+  if (!site.assets) throw new Error('site.yaml: pages needs the assets block, whose endpoint is the account that holds the pages bucket');
+  const dist = path.join(root, 'dist');
+  if (!fs.existsSync(path.join(dist, 'index.html'))) throw new Error('dist/index.html is missing, kitap build writes the site to deploy');
+  const writer = storeWriter({ endpoint: site.assets.endpoint, bucket: site.pages.bucket }, { command: 'kitap deploy', wait });
+  // a dot starts the folder a build writes a story to before it swaps it in, and the files editors and Finder leave
+  const files = fs.readdirSync(dist, { recursive: true }).map(f => f.split(path.sep).join('/'))
+    .filter(f => !f.split('/').some(s => s.startsWith('.')) && fs.statSync(path.join(dist, f)).isFile()).sort();
+  const held = new Map((await writer.list()).map(o => [o.key, o.etag]));
+  const md5 = f => crypto.createHash('md5').update(fs.readFileSync(path.join(dist, f))).digest('hex');
+  const changed = files.filter(f => held.get(f) !== md5(f)), gone = [...held.keys()].filter(k => !files.includes(k)).sort();
+  const kept = files.length - changed.length, bytes = changed.reduce((n, f) => n + fs.statSync(path.join(dist, f)).size, 0);
+  if (dryRun) {
+    for (const f of changed) log(`upload ${f}`);
+    for (const k of gone) log(`delete ${k}`);
+    log(`would upload ${plural(changed.length, 'file')} (${mb(bytes)}), delete ${gone.length.toLocaleString('en')}, ${kept.toLocaleString('en')} are in the bucket`);
+    return { uploaded: changed, deleted: gone, kept };
+  }
+  // a page links its scripts, fonts and glyphs by version, so they go first and a new page finds them in the bucket
+  const script = f => /\.(js|css)$/.test(f) || f.startsWith('vendor/');
+  const cur = { what: 'dist', n: 0, total: changed.length, bytes: 0 };
+  const put = async f => {
+    const body = fs.readFileSync(path.join(dist, f));
+    await writer.put(f, body, typeOf(f), CACHE);
+    cur.n++; cur.bytes += body.length;
+    progress({ ...cur, done: false });
+  };
+  for (const batch of [changed.filter(script), changed.filter(f => !script(f))]) await pool(batch, 8, put);
+  progress({ ...cur, done: true });
+  await pool(gone, 8, k => writer.delete(k));
+  log(`uploaded ${plural(changed.length, 'file')} (${mb(bytes)}), deleted ${gone.length.toLocaleString('en')}, ${kept.toLocaleString('en')} were in the bucket`);
+  return { uploaded: changed, deleted: gone, kept };
+}

package/src/dev.mjs

@@ -0,0 +1,88 @@
+// Watch content and src; rebuild on change; serve dist/ with a reload hook for open tabs.
+import fs from 'fs';
+import path from 'path';
+import http from 'http';
+import { spawn } from 'child_process';
+import { fileURLToPath } from 'url';
+import { resolve, typeOf } from './routes.mjs';
+
+const PKG = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const RELOAD = `<script>(()=>{let v=null;setInterval(async()=>{try{const r=await fetch('/__version');const t=await r.text();if(v===null)v=t;else if(t!==v)location.reload();}catch{}},1000)})()</script>`;
+
+// Serve root/dist on the port and rebuild on changes: a change in one story's folder rebuilds that story and the main
+// page, any other change every story. Returns the http server. Builds run in a child process, so package edits apply,
+// and with --local-assets, so the images on this machine show before they are uploaded.
+// story serves that one story as a site of its own. Every build writes into out, by default dist/, which the server serves.
+export function dev({ root = process.cwd(), port = Number(process.env.PORT) || 8080, log = console.log, story = null, out = null, engine = null } = {}) {
+  const DIST = out ? path.resolve(root, out) : path.join(root, 'dist'), CONTENT = path.join(root, 'content');
+  // engine is the engine module's path, handed to each build and watched beside kitap's own source
+  const WATCH = [CONTENT, path.join(root, 'i18n'), path.join(root, 'plugins'), path.join(PKG, 'src'), ...(engine ? [path.join(path.dirname(engine), '..', 'src')] : [])].filter(fs.existsSync);
+
+  // what the next build covers: every story, or the story folders changed since the last build
+  let version = 0, building = false, queued = false, all = true, changed = new Set();
+  function build() {
+    if (building) { queued = true; return; }
+    building = true;
+    const t0 = Date.now(), wasAll = all, stories = [...changed];
+    all = false; changed = new Set();
+    const scope = [...(story ? ['--story', story] : wasAll ? [] : stories.flatMap(s => ['--only', s])), ...(out ? ['--out', out] : [])];
+    const p = spawn(process.execPath, [path.join(PKG, 'bin', 'kitap.mjs'), 'build', '--local-assets', ...(engine ? ['--engine', engine] : []), ...scope], { stdio: 'inherit', cwd: root });
+    p.on('exit', code => {
+      building = false;
+      if (code === 0) { version = Date.now(); log(`build ok in ${Date.now() - t0} ms, tabs reload`); }
+      else {
+        // the next build retries what this one covered, so a story saved alongside the broken one is not left behind
+        all ||= wasAll; for (const s of stories) changed.add(s);
+        log('build failed, fix the error above and save again');
+      }
+      if (queued) { queued = false; build(); }
+    });
+  }
+
+  // the story folder a file in content/ sits in, below any groups, named by the folder as the build names it
+  const storyOf = file => {
+    const parts = file.split(path.sep);
+    for (let i = 1; i < parts.length; i++) if (fs.existsSync(path.join(CONTENT, ...parts.slice(0, i), 'story.yaml'))) return parts[i - 1];
+    return null;
+  };
+  let timer = null;
+  const onChange = (dir, file) => {
+    if (file && /(^|\/)\./.test(file)) return; // editor swap files and the like
+    const story = dir === CONTENT && file ? storyOf(file) : null;
+    if (story) changed.add(story); else all = true;
+    clearTimeout(timer); timer = setTimeout(build, 150);
+  };
+  const watchers = WATCH.map(dir => fs.watch(dir, { recursive: true }, (_, file) => onChange(dir, file)));
+  // site.yaml sits beside dist/ and node_modules/, so the project folder is watched on its own level, for that file
+  watchers.push(fs.watch(root, (_, file) => { if (file === 'site.yaml') onChange(root, file); }));
+
+  const server = http.createServer(async (req, res) => {
+    const query = req.url.includes('?') ? req.url.slice(req.url.indexOf('?')) : '';
+    let url = req.url.slice(0, req.url.length - query.length);
+    try { url = decodeURIComponent(url); } catch {}
+    if (url === '/__version') { res.writeHead(200, { 'content-type': 'text/plain', 'cache-control': 'no-store' }); return res.end(String(version)); }
+    if (url === '/' && !fs.existsSync(path.join(DIST, 'index.html'))) {
+      const stories = fs.existsSync(DIST) ? fs.readdirSync(DIST).filter(d => fs.existsSync(path.join(DIST, d, 'index.html'))) : [];
+      res.writeHead(200, { 'content-type': 'text/html; charset=utf-8' });
+      return res.end(`<!doctype html><meta charset="utf-8"><title>Stories</title><h1>Stories</h1><ul>${stories.map(s => `<li><a href="/${s}/">${s}</a></li>`).join('')}</ul>${RELOAD}`);
+    }
+    // the same answers as the Worker on the site: index pages, the slash redirect, redirects.json and 404.html
+    const fileOf = key => path.join(DIST, key);
+    const exists = key => { const f = fileOf(key); return f.startsWith(DIST + path.sep) && fs.existsSync(f) && fs.statSync(f).isFile(); };
+    const redirect = p => { const f = fileOf('redirects.json'); return fs.existsSync(f) ? JSON.parse(fs.readFileSync(f, 'utf8'))[p] ?? null : null; };
+    const r = await resolve(url, exists, { redirect, query });
+    if (r.location) { res.writeHead(301, { location: r.location }); return res.end(); }
+    const file = fileOf(r.key), status = r.status;
+    if (!fs.existsSync(file)) { res.writeHead(404); return res.end('not found'); }
+    const ext = path.extname(file);
+    res.writeHead(status, { 'content-type': typeOf(file), 'cache-control': 'no-store' });
+    if (ext === '.html') return res.end(fs.readFileSync(file, 'utf8').replace('</body>', RELOAD + '</body>'));
+    fs.createReadStream(file).pipe(res);
+  });
+  server.listen(port, () => {
+    log(`serving ${path.relative(root, DIST)}/ at http://localhost:${server.address().port}/ and watching ${[...WATCH.map(d => path.basename(d)), 'site.yaml'].join(', ')}`);
+    build();
+  });
+  server.on('close', () => { for (const w of watchers) w.close(); clearTimeout(timer); });
+  return server;
+}

package/src/engine.mjs

@@ -0,0 +1,33 @@
+// The engine that fills the viewport: a package or a plugin that exports the engine module as its default. site.yaml
+// names it, a build may hand one in, and a command of the engine's own hands in its own. Node 22.12+ loads an ES
+// module through require synchronously, which keeps the build synchronous.
+import fs from 'fs';
+import path from 'path';
+import { createRequire } from 'module';
+
+// Resolves an engine to its module: a path to a module file, else an id looked up in the project's packages, under
+// the organisation's scope or bare, then in plugins/engines/<id>.mjs of the project. Fails naming both places.
+export function loadEngine(root, id) {
+  const require = createRequire(path.join(root, 'package.json'));
+  if (id.endsWith('.mjs') || id.endsWith('.js')) return checkEngine(require(path.resolve(root, id)).default, id);
+  for (const name of [`@openbooknetwork/${id}`, `@openhistoryatlas/${id}`, id]) {
+    let mod;
+    try { mod = require(name); } catch (err) { if (err.code === 'MODULE_NOT_FOUND' && String(err.message).includes(name)) continue; throw err; }
+    return checkEngine(mod.default ?? mod.engine, name);
+  }
+  const plugin = path.join(root, 'plugins', 'engines', `${id}.mjs`);
+  if (fs.existsSync(plugin)) return checkEngine(require(plugin).default, plugin);
+  throw new Error(`site.yaml: engine "${id}" is not installed: npm install @openbooknetwork/${id}, or add plugins/engines/${id}.mjs`);
+}
+
+// An engine module has an id and the hooks the build calls; what it leaves out is filled with no-ops.
+export function checkEngine(e, from) {
+  if (!e || typeof e !== 'object' || !e.id) throw new Error(`${from}: an engine module exports an object with an id and its hooks`);
+  if (e.checked) return e;
+  const read = e.read ?? {};
+  return {
+    checked: true, id: e.id, schemas: e.schemas ?? {}, ui: e.ui ?? null, client: e.client ?? {}, vendor: e.vendor ?? null, dir: e.dir ?? null,
+    read: { story: read.story ?? (() => ({})), folder: read.folder ?? (() => {}), include: read.include ?? null, prepare: read.prepare ?? null, page: read.page ?? (() => ({ data: {} })), finish: read.finish ?? (() => ({})) },
+    bundle: e.bundle ?? (() => ({ data: {} })), objects: e.objects ?? (() => ({ groups: {} })), site: e.site ?? (() => {}), make: e.make ?? null, describeObjects: e.describeObjects ?? null,
+  };
+}

package/src/folders.mjs

@@ -0,0 +1,30 @@
+// Libraries of folders: stories in content/, and battles, images and zones in content/shared/ for every story or in a
+// story's shared/. A folder that holds its own file is an item, named by the folder. Any other folder is a group that
+// only orders the library.
+import fs from 'fs';
+import path from 'path';
+
+export const isStory = d => fs.existsSync(path.join(d, 'story.yaml'));
+export const isImage = d => fs.readdirSync(d).some(f => /^image\.\w+$/.test(f)); // image.yaml or the image itself
+export const isBattle = d => fs.existsSync(path.join(d, 'battle.yaml')) || fs.existsSync(path.join(d, 'pages'));
+export const isZone = d => fs.existsSync(path.join(d, 'zone.geojson'));
+
+// The items below dir at any depth, by folder name. rel names the folders in the error for one name in two groups.
+// skip leaves out a folder and everything below it.
+export function libraryItems(dir, isItem, rel = p => p, skip = () => false) {
+  const items = new Map();
+  const walk = d => {
+    for (const name of fs.readdirSync(d).sort()) {
+      const full = path.join(d, name);
+      if (name.startsWith('.') || !fs.statSync(full).isDirectory() || skip(full)) continue;
+      if (!isItem(full)) { walk(full); continue; }
+      if (items.has(name)) throw new Error(`${rel(items.get(name))} and ${rel(full)} have one name, rename one`);
+      items.set(name, full);
+    }
+  };
+  if (fs.existsSync(dir)) walk(dir);
+  return items;
+}
+
+// The story folders below content/ at any depth, by folder name. content/shared/ holds what the stories share.
+export const storyFolders = (content, rel) => libraryItems(content, isStory, rel, d => d === path.join(content, 'shared'));

package/src/i18n/en.yaml

@@ -0,0 +1,47 @@
+# Interface strings for en, the book's. An engine ships its own over them. Content strings live in the content project.
+name: English
+prev: Prev
+next: Next
+close: Close
+sources: Sources
+chronology: Contents
+language: Language
+hint: Step through with the arrows.
+pages: pages
+open: Open
+theme: Theme
+expand_all: Expand all
+source: Source
+legend: Legend
+collapse_all: Collapse all
+read_more: Read more
+hide: Hide
+tab_map: View
+tab_text: Text
+contents: Contents
+contribute: Contribute
+story_source: Source on GitHub
+generated_by: Generated by {kitap}
+previous_image: Previous image
+next_image: Next image
+search_stories: Search stories
+no_match: "No story matches “{q}”."
+map_data: Data
+other_sources: Other sources
+ask: Ask AI
+ask_title: Ask about this page
+ask_prompt: "I am reading “{title}” at {url}. Answer my questions about it from this text and the page's sources, and say when you are unsure."
+ask_note: Opens in a new tab with the page's text as the question.
+start: Start
+not_found: There is no page at this address.
+settings: Settings
+layout: Layout
+layout_center: Picture in the middle
+layout_left: Text on the left
+layout_right: Text on the right
+themes:
+  cool: Cool
+  mono: Mono
+  navy: Navy
+  parchment: Parchment
+  sepia: Sepia

package/src/i18n/tr.yaml

@@ -0,0 +1,47 @@
+# Interface strings for tr, the book's. An engine ships its own over them.
+name: Türkçe
+prev: Önceki
+next: Sonraki
+close: Kapat
+sources: Kaynaklar
+chronology: İçindekiler
+language: Dil
+hint: Oklarla adım adım ilerleyin.
+pages: sayfa
+open: Aç
+theme: Tema
+expand_all: Tümünü aç
+source: Kaynak
+collapse_all: Tümünü kapat
+read_more: Devamını oku
+hide: Gizle
+legend: Lejant
+tab_map: Görünüm
+tab_text: Metin
+contents: İçindekiler
+contribute: Katkıda bulun
+story_source: GitHub’da kaynağı
+generated_by: '{kitap} ile oluşturuldu'
+previous_image: Önceki görsel
+next_image: Sonraki görsel
+search_stories: Hikâye ara
+no_match: "“{q}” ile eşleşen hikâye yok."
+map_data: Veri
+other_sources: Diğer kaynaklar
+ask: Yapay zekâya sor
+ask_title: Bu sayfayı sor
+ask_prompt: "“{title}” sayfasını okuyorum: {url}. Sorularımı bu metne ve sayfanın kaynaklarına dayanarak yanıtla, emin olmadığında söyle."
+ask_note: Yeni sekmede, sayfanın metni soru olarak açılır.
+start: Başla
+not_found: Bu adreste bir sayfa yok.
+settings: Ayarlar
+layout: Yerleşim
+layout_center: Resim ortada
+layout_left: Metin solda
+layout_right: Metin sağda
+themes:
+  cool: Soğuk
+  mono: Tek renk
+  navy: Lacivert
+  parchment: Parşömen
+  sepia: Sepya

package/src/i18n.mjs

@@ -0,0 +1,67 @@
+// Translatable strings. The default language is written inline as a plain string; other languages come from
+// catalogues, content/<story>/i18n/<lang>.yaml for a story and i18n/<lang>.yaml for the site, keyed by the
+// stable ids every piece of content already has, for example pages.occupation.title. An inline object with
+// one entry per language keeps working and takes precedence for the languages it names.
+import fs from 'fs';
+import path from 'path';
+
+// { a: { b: 'x' } } -> { 'a.b': 'x' }, so a catalogue may nest or stay flat
+export function flatten(obj, prefix = '', out = {}) {
+  for (const [k, v] of Object.entries(obj ?? {})) {
+    const key = prefix ? `${prefix}.${k}` : k;
+    if (v && typeof v === 'object' && !Array.isArray(v)) flatten(v, key, out); else if (v != null && v !== '') out[key] = String(v);
+  }
+  return out;
+}
+
+// { 'a.b': 'x' } -> { a: { b: 'x' } }
+export function unflatten(flat) {
+  const out = {};
+  for (const [k, v] of Object.entries(flat)) { const parts = k.split('.'); let o = out; parts.slice(0, -1).forEach(p => { o = o[p] = typeof o[p] === 'object' ? o[p] : {}; }); o[parts.at(-1)] = v; }
+  return out;
+}
+
+// Reads <dir>/<lang>.yaml for every language that has one.
+export function loadCatalogues(dir, langs, loadYaml) {
+  const cats = {};
+  for (const lang of langs) { const f = path.join(dir, lang + '.yaml'); if (fs.existsSync(f)) cats[lang] = flatten(loadYaml(f)); }
+  return cats;
+}
+
+// One translator per story or site. tr(value, key) expands a field to one string per language and records
+// the key with its source text, so catalogues can be written and gaps reported. A shared field, a name, citation
+// or photo credit, may be translated but is not counted as missing when it is not.
+export function translator({ langs, defaultLang, catalogues, where, fail }) {
+  const entries = new Map();
+  const missing = Object.fromEntries(langs.map(l => [l, []]));
+  function tr(value, key, { shared = false } = {}) {
+    const inline = typeof value === 'object' && value !== null ? value : null;
+    const source = inline ? inline[defaultLang] : value;
+    if (source == null) fail(where, `${key}: no "${defaultLang}" text, write it in ${defaultLang} or set default_language to the language it is in`);
+    const out = {};
+    for (const lang of langs) {
+      const text = inline?.[lang] ?? catalogues[lang]?.[key] ?? (lang === defaultLang ? source : null);
+      if (text == null) { if (!shared) missing[lang].push(key); out[lang] = source; } else out[lang] = String(text);
+    }
+    if (!entries.has(key)) entries.set(key, { key, source: String(source), values: out, shared, inline: inline ? Object.fromEntries(Object.entries(inline).filter(([l]) => l !== defaultLang)) : null });
+    return out;
+  }
+  const report = () => Object.fromEntries(langs.filter(l => l !== defaultLang).map(l => [l, { total: [...entries.values()].filter(e => !e.shared).length, missing: [...new Set(missing[l])] }]));
+  return { tr, entries, report };
+}
+
+// Text of a catalogue: every key with its English source as the comment above, existing or inline
+// translations kept, keys that no longer exist moved to a commented block at the end.
+export function catalogueText(lang, entries, existing, heading) {
+  const q = s => JSON.stringify(s ?? '');
+  const lines = [`# ${heading}`, `# Keys are stable ids, the comment above each one is the source text. Empty values fall back to the`, `# default language, and kitap build --strict reports them. Regenerate with: kitap i18n ${lang}`, ''];
+  let filled = 0, total = 0;
+  const emit = e => { const value = existing[e.key] ?? e.inline?.[lang] ?? ''; if (value && !e.shared) filled++; if (!e.shared) total++; lines.push(`# ${e.source.replace(/\n/g, ' ')}`, `${e.key}: ${q(value)}`, ''); };
+  entries.filter(e => !e.shared).forEach(emit);
+  // a name, citation or credit is listed only with its own form in the language, the rest show as in the source
+  const shared = entries.filter(e => e.shared && (existing[e.key] || e.inline?.[lang]));
+  if (shared.length) { lines.push('# Names, citations and credits with their own form in this language. Any other shows as written in the source.', ''); shared.forEach(emit); }
+  const stale = Object.keys(existing).filter(k => !entries.some(e => e.key === k));
+  if (stale.length) { lines.push('# No longer used by the content:'); for (const k of stale) lines.push(`# ${k}: ${q(existing[k])}`); lines.push(''); }
+  return { text: lines.join('\n'), filled, total };
+}