@adriangalilea/utils 0.8.0 → 0.9.0

package/README.md

@@ -248,6 +248,34 @@ newMessages = [{ id: '2', from: 'bob', text: 'hey' }]
 
 Saves state to: `$XDG_STATE_HOME/unseen/{name}.json`
 
+### Polyglot strings (`say`)
+
+A typed multi-language string is just an object literal `{ en, es, … }` — the keys are the source of truth, the TS compiler enforces completeness, there's no JSON file / extraction tool / registry.
+
+```typescript
+import { say, type Polyglot } from '@adriangalilea/utils/say'
+
+say({ en: 'Hello', es: 'Hola' }, 'es')       // → 'Hola'
+say({ en: 'Hello', es: 'Hola' }, 'fr')       // TS error: '"fr"' not in '"en" | "es"'
+
+// parametric — closures, no wrapper:
+const greeting = (name: string) => ({ en: `Hi ${name}`, es: `Hola ${name}` })
+say(greeting('Adrian'), 'es')                 // → 'Hola Adrian'
+
+// type your own adapter:
+const notify = (msg: Polyglot<'en' | 'es'>, lang: 'en' | 'es') =>
+  transport.send(say(msg, lang))
+```
+
+In a bot, `bot/language` adds `ctx.say` — a callable namespace bound to `ctx.lang`:
+
+```typescript
+ctx.say({ en: 'Continue', es: 'Continuar' })       // → string
+await ctx.say.send({ en: 'Hi', es: 'Hola' })       // → ctx.send(resolved)
+await ctx.say.edit({ en: 'Done', es: 'Listo' })    // → ctx.editText (callback only)
+await ctx.say.answer({ en: 'OK', es: 'OK' })       // → ctx.answer (callback only)
+```
+
 ### Telegram bot plugins (GramIO)
 
 Plugins for personal Telegram bots built on [GramIO](https://gramio.dev). Each plugin lives at its own subpath; peer deps (`gramio`, `@gramio/storage`, `@gramio/session`, `@gramio/format`, `marked`) are **all optional** — install only what you import.

package/dist/bot/access-control.d.ts

@@ -11,7 +11,7 @@
  *      │     no  → drop + notify admin (rate-limited)    │
  *      └─────────────────────────────────────────────────┘
  *                       │
- *           admin gets DM with [✅ Aprobar] [❌ Denegar]
+ *           admin gets DM with [✅ Approve] [❌ Deny]
  *                       │
  *                  admin taps
  *                       │
@@ -33,12 +33,19 @@
  *
  *     storage['ac:index'] = { pending: [...ids], approved: [...], denied: [...] }
  *
- * **Cross-user mutations.** When the admin taps `[✅ Aprobar]` on
+ * **Cross-user mutations.** When the admin taps `[✅ Approve]` on
  * Pepe's notification, `ctx` is the admin's, so `ctx.session` is the
  * admin's record — useless for mutating Pepe. We reach for Pepe's
  * record directly via `storage.get(String(pepeId))`, preserve other
  * plugins' fields in it (read-modify-write), and put it back.
  *
+ * **i18n.** Every user-facing string is an inline `{ en, es }`
+ * polyglot literal resolved via `say(value, lang)` at the call site
+ * — no message bundle, no override registry. The recipient's stored
+ * `language` field (set by `bot/language`) picks the variant; falls
+ * back to `'en'`. Want a different default? Set `language` on the
+ * relevant session record before this plugin fires.
+ *
  * **Composes with**:
  *   - `adminContext` (kit.ts) — required, gives us `ctx.adminId` /
  *     `ctx.isAdmin`. Declared as a runtime dependency.
@@ -120,9 +127,13 @@ export type AccessInfo = {
     allowed: false;
     reason: 'denied' | 'pending' | 'unknown' | 'no-sender';
 };
-/** Loose session shape — this plugin only touches the `access` field. */
+/**
+ * Loose session shape — this plugin writes `access`; it READS `language`
+ * to localize messages it sends to the subject. Both are optional.
+ */
 type SessionLike = {
     access?: AccessRecord;
+    language?: string;
 };
 /** @internal — kept unexported so it doesn't clash with peers' refs. */
 type AcSessionPluginRef = ReturnType<typeof session<SessionLike, 'session'>>;
@@ -141,8 +152,8 @@ export type AccessControlOptions = {
     storage: Storage;
     /** Always-allowed user ids, hardcoded. Bypass the entire flow. */
     defaults?: ReadonlyArray<number>;
-    /** Reply sent to denied users on first attempt. `false` to silence. */
-    denyMessage?: string | false;
+    /** Pass `false` to silence the first-attempt reply to denied users. */
+    silentDeny?: boolean;
     /** Min ms between repeat admin notifications for the same user. Default 6h. */
     notifyThrottleMs?: number;
     /** Callbacks for your own logging / metrics. */
@@ -362,7 +373,7 @@ export declare const accessControl: (opts: AccessControlOptions) => Plugin<{}, D
  * easily spin up a second Telegram account. Writes a `pending` record
  * to storage at the same key the plugin's session would, updates the
  * index, then DMs the admin with the real
- * `[✅ Aprobar][❌ Denegar]` keyboard. Tapping those buttons exercises
+ * `[✅ Approve][❌ Deny]` keyboard. Tapping those buttons exercises
  * the real callback handlers end-to-end.
  *
  * Pass the SAME `storage` instance you passed to `accessControl({ storage })`.

package/dist/bot/access-control.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"access-control.d.ts","sourceRoot":"","sources":["../../src/bot/access-control.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"access-control.d.ts","sourceRoot":"","sources":["../../src/bot/access-control.ts"],"names":[],"mappings":"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"}

package/dist/bot/access-control.js

@@ -11,7 +11,7 @@
  *      │     no  → drop + notify admin (rate-limited)    │
  *      └─────────────────────────────────────────────────┘
  *                       │
- *           admin gets DM with [✅ Aprobar] [❌ Denegar]
+ *           admin gets DM with [✅ Approve] [❌ Deny]
  *                       │
  *                  admin taps
  *                       │
@@ -33,12 +33,19 @@
  *
  *     storage['ac:index'] = { pending: [...ids], approved: [...], denied: [...] }
  *
- * **Cross-user mutations.** When the admin taps `[✅ Aprobar]` on
+ * **Cross-user mutations.** When the admin taps `[✅ Approve]` on
  * Pepe's notification, `ctx` is the admin's, so `ctx.session` is the
  * admin's record — useless for mutating Pepe. We reach for Pepe's
  * record directly via `storage.get(String(pepeId))`, preserve other
  * plugins' fields in it (read-modify-write), and put it back.
  *
+ * **i18n.** Every user-facing string is an inline `{ en, es }`
+ * polyglot literal resolved via `say(value, lang)` at the call site
+ * — no message bundle, no override registry. The recipient's stored
+ * `language` field (set by `bot/language`) picks the variant; falls
+ * back to `'en'`. Want a different default? Set `language` on the
+ * relevant session record before this plugin fires.
+ *
  * **Composes with**:
  *   - `adminContext` (kit.ts) — required, gives us `ctx.adminId` /
  *     `ctx.isAdmin`. Declared as a runtime dependency.
@@ -68,14 +75,11 @@
  * await gracefulStart(bot)
  */
 import { CallbackData, InlineKeyboard, Plugin, } from 'gramio';
-// Cross-user mutations (admin approves Pepe → write to Pepe's session)
-// hit `storage` directly using the same key format `@gramio/session`
-// uses by default: `String(userId)`. We preserve other plugins' fields
-// in the same session record by read-modify-write.
+import { say } from '../say/index.js';
 const INDEX_KEY = 'ac:index';
 const FIRST_MSG_LIMIT = 200;
-const DEFAULT_DENY_MSG = 'Este bot es privado. Tu solicitud se ha enviado al admin.';
 const DEFAULT_THROTTLE_MS = 6 * 60 * 60 * 1000;
+const FALLBACK_LANG = 'en';
 /** gramio's `@gramio/session` default `getSessionKey` is `String(senderId)`. */
 const sessionKey = (userId) => String(userId);
 // ─── callback schemas ──────────────────────────────────────────────
@@ -109,25 +113,27 @@ const fmtAge = (ms) => {
         return `${h}h`;
     return `${Math.floor(h / 24)}d`;
 };
-const requestNotificationText = (uid, r, repeat) => {
+const requestNotificationText = (uid, r, repeat, lang) => {
     const parts = [
-        repeat ? '🔁 Acceso re-solicitado' : '🔔 Acceso solicitado',
+        say(repeat
+            ? { en: '🔁 Access re-requested', es: '🔁 Acceso re-solicitado' }
+            : { en: '🔔 Access requested', es: '🔔 Acceso solicitado' }, lang),
         '',
         `👤 ${formatUser(r.user, uid)}`,
         `🆔 ${uid}`,
-        `⏰ hace ${fmtAge(Date.now() - (r.requestedAt ?? Date.now()))}`,
+        `⏰ ${say({ en: 'ago', es: 'hace' }, lang)} ${fmtAge(Date.now() - (r.requestedAt ?? Date.now()))}`,
     ];
-    if (repeat)
-        parts.push(`🔁 intentos: ${(r.rejectedAttempts ?? 0) + 1}`);
+    if (repeat) {
+        parts.push(`🔁 ${say({ en: 'attempts', es: 'intentos' }, lang)}: ${(r.rejectedAttempts ?? 0) + 1}`);
+    }
     if (r.firstMessage)
         parts.push('', `💬 "${r.firstMessage}"`);
     return parts.join('\n');
 };
-const requestKeyboard = (uid) => new InlineKeyboard()
-    .text('✅ Aprobar', acApprove.pack({ uid }))
-    .text('❌ Denegar', acDeny.pack({ uid }));
+const requestKeyboard = (uid, lang) => new InlineKeyboard()
+    .text(say({ en: '✅ Approve', es: '✅ Aprobar' }, lang), acApprove.pack({ uid }))
+    .text(say({ en: '❌ Deny', es: '❌ Denegar' }, lang), acDeny.pack({ uid }));
 // ─── index helpers ─────────────────────────────────────────────────
-const emptyIndex = () => ({ pending: [], approved: [], denied: [] });
 const loadIndex = async (storage) => {
     const raw = (await storage.get(INDEX_KEY));
     return {
@@ -172,11 +178,18 @@ const loadAccess = async (storage, userId) => {
     const full = await loadFullRecord(storage, userId);
     return full.access;
 };
+/** Read recipient's stored language (set by bot/language); fallback to en. */
+const langOfUser = async (storage, userId) => {
+    const full = await loadFullRecord(storage, userId);
+    return full.language ?? FALLBACK_LANG;
+};
+/** Read current ctx's lang. */
+const ctxLang = (ctx) => ctx.session.language ?? FALLBACK_LANG;
 // ─── plugin ────────────────────────────────────────────────────────
 export const accessControl = (opts) => {
     const { session: sessionPlugin, storage } = opts;
     const defaults = new Set(opts.defaults ?? []);
-    const denyMessage = opts.denyMessage === false ? null : (opts.denyMessage ?? DEFAULT_DENY_MSG);
+    const silentDeny = opts.silentDeny === true;
     const throttleMs = opts.notifyThrottleMs ?? DEFAULT_THROTTLE_MS;
     return (
     // Generic declares dependency on adminContext's derives so
@@ -231,7 +244,10 @@ export const accessControl = (opts) => {
         }
         // Acknowledge unauthorized callback queries so the spinner clears.
         if (ctx.is('callback_query')) {
-            await ctx.answer({ text: 'Sin acceso.', show_alert: false });
+            await ctx.answer({
+                text: say({ en: 'No access.', es: 'Sin acceso.' }, ctxLang(ctx)),
+                show_alert: false,
+            });
             return;
         }
         // Only message-shaped events have .text/.chat for our notification.
@@ -267,10 +283,11 @@ export const accessControl = (opts) => {
         if (shouldNotify) {
             rec.lastNotifiedAt = now;
             try {
+                const adminLang = await langOfUser(storage, ctx.adminId);
                 await ctx.bot.api.sendMessage({
                     chat_id: ctx.adminId,
-                    text: requestNotificationText(userId, rec, !isFirstRequest),
-                    reply_markup: requestKeyboard(userId),
+                    text: requestNotificationText(userId, rec, !isFirstRequest, adminLang),
+                    reply_markup: requestKeyboard(userId, adminLang),
                 });
             }
             catch (e) {
@@ -280,9 +297,12 @@ export const accessControl = (opts) => {
         }
         // Persist the updated record to the user's session.
         ctx.session.access = rec;
-        if (denyMessage && isFirstRequest) {
+        if (!silentDeny && isFirstRequest) {
             try {
-                await ctx.send(denyMessage);
+                await ctx.send(say({
+                    en: 'This bot is private. Your request has been sent to the admin.',
+                    es: 'Este bot es privado. Tu solicitud se ha enviado al admin.',
+                }, ctxLang(ctx)));
             }
             catch {
                 // user blocked the bot — irrelevant
@@ -292,12 +312,18 @@ export const accessControl = (opts) => {
     })
         // ─── admin actions ────────────────────────────────────────
         .callbackQuery(acApprove, async (ctx) => {
+        const aLang = ctxLang(ctx);
         if (!ctx.isAdmin)
-            return ctx.answer({ text: 'Solo admin.', show_alert: true });
+            return ctx.answer({
+                text: say({ en: 'Admin only.', es: 'Solo admin.' }, aLang),
+                show_alert: true,
+            });
         const uid = ctx.queryData.uid;
         const rec = await loadAccess(storage, uid);
         if (!rec)
-            return ctx.answer({ text: 'No encontrado.' });
+            return ctx.answer({
+                text: say({ en: 'Not found.', es: 'No encontrado.' }, aLang),
+            });
         const wasDenied = rec.status === 'denied';
         const wasPending = rec.status === 'pending';
         rec.status = 'approved';
@@ -309,24 +335,33 @@ export const accessControl = (opts) => {
         await indexMove(storage, uid, wasPending ? 'pending' : wasDenied ? 'denied' : 'any', 'approved');
         if (rec.chatId !== undefined) {
             try {
+                const sLang = await langOfUser(storage, uid);
                 await ctx.bot.api.sendMessage({
                     chat_id: rec.chatId,
-                    text: wasDenied
-                        ? '✅ El admin reconsideró: ya tienes acceso.'
-                        : '✅ Acceso concedido. Ya puedes usar el bot.',
+                    text: say(wasDenied
+                        ? {
+                            en: '✅ The admin reconsidered: you have access.',
+                            es: '✅ El admin reconsideró: ya tienes acceso.',
+                        }
+                        : {
+                            en: '✅ Access granted. You can use the bot now.',
+                            es: '✅ Acceso concedido. Ya puedes usar el bot.',
+                        }, sLang),
                 });
             }
             catch {
                 // user blocked / chat gone
             }
         }
-        await ctx.answer({ text: '✅ Aprobado' });
+        await ctx.answer({
+            text: say({ en: '✅ Approved', es: '✅ Aprobado' }, aLang),
+        });
         if (ctx.queryData.v) {
-            await renderView(ctx, storage, defaults, ctx.queryData.v);
+            await renderView(ctx, storage, defaults, ctx.queryData.v, aLang);
         }
         else {
             try {
-                await ctx.editText(`✅ Aprobado · ${formatUser(rec.user, uid)}`);
+                await ctx.editText(`${say({ en: '✅ Approved', es: '✅ Aprobado' }, aLang)} · ${formatUser(rec.user, uid)}`);
             }
             catch {
                 // not always editable
@@ -335,12 +370,18 @@ export const accessControl = (opts) => {
         opts.onApprove?.({ userId: uid, approvedBy: ctx.adminId });
     })
         .callbackQuery(acDeny, async (ctx) => {
+        const aLang = ctxLang(ctx);
         if (!ctx.isAdmin)
-            return ctx.answer({ text: 'Solo admin.', show_alert: true });
+            return ctx.answer({
+                text: say({ en: 'Admin only.', es: 'Solo admin.' }, aLang),
+                show_alert: true,
+            });
         const uid = ctx.queryData.uid;
         const rec = await loadAccess(storage, uid);
         if (!rec)
-            return ctx.answer({ text: 'No encontrado.' });
+            return ctx.answer({
+                text: say({ en: 'Not found.', es: 'No encontrado.' }, aLang),
+            });
         const wasPending = rec.status === 'pending';
         rec.status = 'denied';
         rec.deniedAt = Date.now();
@@ -349,22 +390,25 @@ export const accessControl = (opts) => {
         await indexMove(storage, uid, wasPending ? 'pending' : 'any', 'denied');
         if (rec.chatId !== undefined) {
             try {
+                const sLang = await langOfUser(storage, uid);
                 await ctx.bot.api.sendMessage({
                     chat_id: rec.chatId,
-                    text: '❌ Acceso denegado.',
+                    text: say({ en: '❌ Access denied.', es: '❌ Acceso denegado.' }, sLang),
                 });
             }
             catch {
                 // ignore
             }
         }
-        await ctx.answer({ text: '❌ Denegado' });
+        await ctx.answer({
+            text: say({ en: '❌ Denied', es: '❌ Denegado' }, aLang),
+        });
         if (ctx.queryData.v) {
-            await renderView(ctx, storage, defaults, ctx.queryData.v);
+            await renderView(ctx, storage, defaults, ctx.queryData.v, aLang);
         }
         else {
             try {
-                await ctx.editText(`❌ Denegado · ${formatUser(rec.user, uid)}`);
+                await ctx.editText(`${say({ en: '❌ Denied', es: '❌ Denegado' }, aLang)} · ${formatUser(rec.user, uid)}`);
             }
             catch {
                 // ignore
@@ -373,12 +417,18 @@ export const accessControl = (opts) => {
         opts.onDeny?.({ userId: uid, deniedBy: ctx.adminId });
     })
         .callbackQuery(acRevoke, async (ctx) => {
+        const aLang = ctxLang(ctx);
         if (!ctx.isAdmin)
-            return ctx.answer({ text: 'Solo admin.', show_alert: true });
+            return ctx.answer({
+                text: say({ en: 'Admin only.', es: 'Solo admin.' }, aLang),
+                show_alert: true,
+            });
         const uid = ctx.queryData.uid;
         const rec = await loadAccess(storage, uid);
         if (!rec)
-            return ctx.answer({ text: 'No encontrado.' });
+            return ctx.answer({
+                text: say({ en: 'Not found.', es: 'No encontrado.' }, aLang),
+            });
         rec.status = 'denied';
         rec.deniedAt = Date.now();
         rec.deniedBy = ctx.adminId;
@@ -386,27 +436,41 @@ export const accessControl = (opts) => {
         await indexMove(storage, uid, 'approved', 'denied');
         if (rec.chatId !== undefined) {
             try {
+                const sLang = await langOfUser(storage, uid);
                 await ctx.bot.api.sendMessage({
                     chat_id: rec.chatId,
-                    text: '↩️ Tu acceso al bot ha sido revocado.',
+                    text: say({
+                        en: '↩️ Your bot access has been revoked.',
+                        es: '↩️ Tu acceso al bot ha sido revocado.',
+                    }, sLang),
                 });
             }
             catch {
                 // ignore
             }
         }
-        await ctx.answer({ text: '↩️ Revocado' });
-        await renderView(ctx, storage, defaults, 'approved');
+        await ctx.answer({
+            text: say({ en: '↩️ Revoked', es: '↩️ Revocado' }, aLang),
+        });
+        await renderView(ctx, storage, defaults, 'approved', aLang);
     })
         .callbackQuery(acView, async (ctx) => {
+        const aLang = ctxLang(ctx);
         if (!ctx.isAdmin)
-            return ctx.answer({ text: 'Solo admin.', show_alert: true });
+            return ctx.answer({
+                text: say({ en: 'Admin only.', es: 'Solo admin.' }, aLang),
+                show_alert: true,
+            });
         await ctx.answer({});
-        await renderView(ctx, storage, defaults, ctx.queryData.v);
+        await renderView(ctx, storage, defaults, ctx.queryData.v, aLang);
     })
         .callbackQuery(acClose, async (ctx) => {
+        const aLang = ctxLang(ctx);
         if (!ctx.isAdmin)
-            return ctx.answer({ text: 'Solo admin.', show_alert: true });
+            return ctx.answer({
+                text: say({ en: 'Admin only.', es: 'Solo admin.' }, aLang),
+                show_alert: true,
+            });
         await ctx.answer({});
         try {
             await ctx.message?.delete();
@@ -419,23 +483,28 @@ export const accessControl = (opts) => {
         // Admin-only; hidden from Telegram's `/` menu so it doesn't
         // tempt other users to type it. Admin still invokes via /access.
         // See https://gramio.dev/triggers/command.html#commandmeta-fields
+        //
+        // Note: gramio's setMyCommands publishes ONE description per
+        // bot, not per language. English form used as the canonical.
         description: 'Admin: access control menu',
         hide: true,
     }, async (ctx) => {
         if (!ctx.isAdmin)
             return;
-        const v = await mainView(storage, defaults);
+        const aLang = ctxLang(ctx);
+        const v = mainView(await loadIndex(storage), defaults, aLang);
         await ctx.send(v.text, { reply_markup: v.keyboard });
     }));
 };
-const renderView = async (ctx, storage, defaults, view) => {
+const renderView = async (ctx, storage, defaults, view, lang) => {
+    const idx = await loadIndex(storage);
     const v = view === 'approved'
-        ? await listView(storage, 'approved', defaults)
+        ? await listView(storage, idx, 'approved', defaults, lang)
         : view === 'pending'
-            ? await listView(storage, 'pending', defaults)
+            ? await listView(storage, idx, 'pending', defaults, lang)
             : view === 'denied'
-                ? await listView(storage, 'denied', defaults)
-                : await mainView(storage, defaults);
+                ? await listView(storage, idx, 'denied', defaults, lang)
+                : mainView(idx, defaults, lang);
     try {
         await ctx.editText(v.text, { reply_markup: v.keyboard });
     }
@@ -443,37 +512,44 @@ const renderView = async (ctx, storage, defaults, view) => {
         // editText only works while message is recent enough; ignore
     }
 };
-const mainView = async (storage, defaults) => {
-    const idx = await loadIndex(storage);
+const mainView = (idx, defaults, lang) => {
+    const approved = say({ en: 'Approved', es: 'Aprobados' }, lang);
+    const pending = say({ en: 'Pending', es: 'Pendientes' }, lang);
+    const denied = say({ en: 'Denied', es: 'Denegados' }, lang);
     const text = [
-        '🔐 Access Control',
+        say({ en: '🔐 Access Control', es: '🔐 Access Control' }, lang),
         '',
-        `✅ Aprobados: ${idx.approved.length}`,
-        `⏳ Pendientes: ${idx.pending.length}`,
-        `❌ Denegados: ${idx.denied.length}`,
-        `👑 Defaults: ${defaults.size} (hardcoded)`,
+        `✅ ${approved}: ${idx.approved.length}`,
+        `⏳ ${pending}: ${idx.pending.length}`,
+        `❌ ${denied}: ${idx.denied.length}`,
+        `👑 ${say({ en: 'Defaults', es: 'Defaults' }, lang)}: ${defaults.size} (hardcoded)`,
     ].join('\n');
     const keyboard = new InlineKeyboard()
-        .text(`✅ Aprobados (${idx.approved.length})`, acView.pack({ v: 'approved' }))
-        .text(`⏳ Pendientes (${idx.pending.length})`, acView.pack({ v: 'pending' }))
+        .text(`✅ ${approved} (${idx.approved.length})`, acView.pack({ v: 'approved' }))
+        .text(`⏳ ${pending} (${idx.pending.length})`, acView.pack({ v: 'pending' }))
         .row()
-        .text(`❌ Denegados (${idx.denied.length})`, acView.pack({ v: 'denied' }))
-        .text('🔄 Refresh', acView.pack({ v: 'main' }))
+        .text(`❌ ${denied} (${idx.denied.length})`, acView.pack({ v: 'denied' }))
+        .text(say({ en: '🔄 Refresh', es: '🔄 Refresh' }, lang), acView.pack({ v: 'main' }))
         .row()
-        .text('✖️ Cerrar', acClose.pack({}));
+        .text(say({ en: '✖️ Close', es: '✖️ Cerrar' }, lang), acClose.pack({}));
     return { text, keyboard };
 };
-const listView = async (storage, filter, defaults) => {
-    const idx = await loadIndex(storage);
+const listView = async (storage, idx, filter, defaults, lang) => {
     const ids = idx[filter];
     // Cap at 20 to keep callback_data + rendering sane.
     const shownIds = ids.slice(0, 20);
     const records = await Promise.all(shownIds.map(async (id) => ({ id, rec: await loadAccess(storage, id) })));
     const headerEmoji = filter === 'approved' ? '✅' : filter === 'pending' ? '⏳' : '❌';
-    const headerLabel = filter === 'approved' ? 'Aprobados' : filter === 'pending' ? 'Pendientes' : 'Denegados';
+    const headerLabel = filter === 'approved'
+        ? say({ en: 'Approved', es: 'Aprobados' }, lang)
+        : filter === 'pending'
+            ? say({ en: 'Pending', es: 'Pendientes' }, lang)
+            : say({ en: 'Denied', es: 'Denegados' }, lang);
+    const back = say({ en: '⬅️ Back', es: '⬅️ Volver' }, lang);
     if (ids.length === 0) {
-        const text = `${headerEmoji} ${headerLabel} (0)\n\n(vacío)`;
-        const keyboard = new InlineKeyboard().text('⬅️ Volver', acView.pack({ v: 'main' }));
+        const text = `${headerEmoji} ${headerLabel} (0)\n\n` +
+            say({ en: '(empty)', es: '(vacío)' }, lang);
+        const keyboard = new InlineKeyboard().text(back, acView.pack({ v: 'main' }));
         return { text, keyboard };
     }
     const lines = [`${headerEmoji} ${headerLabel} (${ids.length})`, ''];
@@ -482,11 +558,11 @@ const listView = async (storage, filter, defaults) => {
         const { id, rec } = records[i];
         if (!rec) {
             // index referenced a missing record — show as placeholder
-            lines.push(`${i + 1}. id ${id} (datos perdidos)`);
+            lines.push(`${i + 1}. id ${id} ${say({ en: '(data lost)', es: '(datos perdidos)' }, lang)}`);
             continue;
         }
         const ageRef = rec.approvedAt ?? rec.deniedAt ?? rec.requestedAt ?? Date.now();
-        lines.push(`${i + 1}. ${formatUser(rec.user, id)} · hace ${fmtAge(Date.now() - ageRef)}` +
+        lines.push(`${i + 1}. ${formatUser(rec.user, id)} · ${say({ en: 'ago', es: 'hace' }, lang)} ${fmtAge(Date.now() - ageRef)}` +
             (rec.messageCount ? ` · ${rec.messageCount} msgs` : ''));
         if (filter === 'pending') {
             keyboard
@@ -495,21 +571,23 @@ const listView = async (storage, filter, defaults) => {
                 .row();
         }
         else if (filter === 'approved') {
-            keyboard.text(`↩️ Revocar #${i + 1}`, acRevoke.pack({ uid: id })).row();
+            keyboard
+                .text(`${say({ en: '↩️ Revoke', es: '↩️ Revocar' }, lang)} #${i + 1}`, acRevoke.pack({ uid: id }))
+                .row();
         }
         else if (filter === 'denied') {
             keyboard
-                .text(`✅ Reaprobar #${i + 1}`, acApprove.pack({ uid: id, v: 'denied' }))
+                .text(`${say({ en: '✅ Reapprove', es: '✅ Reaprobar' }, lang)} #${i + 1}`, acApprove.pack({ uid: id, v: 'denied' }))
                 .row();
         }
     }
     if (ids.length > shownIds.length) {
-        lines.push('', `(+${ids.length - shownIds.length} más, no mostrados)`);
+        lines.push('', `(+${ids.length - shownIds.length} ${say({ en: 'more, not shown', es: 'más, no mostrados' }, lang)})`);
     }
     if (filter === 'approved' && defaults.size > 0) {
         lines.push('', `+ ${defaults.size} hardcoded defaults`);
     }
-    keyboard.text('⬅️ Volver', acView.pack({ v: 'main' }));
+    keyboard.text(back, acView.pack({ v: 'main' }));
     return { text: lines.join('\n'), keyboard };
 };
 // ─── test helper ───────────────────────────────────────────────────
@@ -518,7 +596,7 @@ const listView = async (storage, filter, defaults) => {
  * easily spin up a second Telegram account. Writes a `pending` record
  * to storage at the same key the plugin's session would, updates the
  * index, then DMs the admin with the real
- * `[✅ Aprobar][❌ Denegar]` keyboard. Tapping those buttons exercises
+ * `[✅ Approve][❌ Deny]` keyboard. Tapping those buttons exercises
  * the real callback handlers end-to-end.
  *
  * Pass the SAME `storage` instance you passed to `accessControl({ storage })`.
@@ -537,10 +615,11 @@ export const simulateAccessRequest = async (bot, storage, adminId, fakeUser, mes
     };
     await saveAccess(storage, fakeUser.id, rec);
     await indexAdd(storage, 'pending', fakeUser.id);
+    const adminLang = await langOfUser(storage, adminId);
     await bot.api.sendMessage({
         chat_id: adminId,
-        text: requestNotificationText(fakeUser.id, rec, false),
-        reply_markup: requestKeyboard(fakeUser.id),
+        text: requestNotificationText(fakeUser.id, rec, false, adminLang),
+        reply_markup: requestKeyboard(fakeUser.id, adminLang),
     });
 };
 //# sourceMappingURL=access-control.js.map