djs-next 1.0.0-dev.1

package/src/plugins/dnxt.ts

@@ -0,0 +1,379 @@
+import { Message, EmbedBuilder } from 'discord.js';
+import { exec } from 'child_process';
+import util from 'util';
+import os from 'os';
+import { DJSNextClient } from '../client.js';
+import { loadEvents } from '../handlers/eventHandler.js';
+import { loadComponents } from '../handlers/componentHandler.js';
+import { loadAndDeployCommands } from '../handlers/commandHandler.js';
+import { loadTasks } from '../handlers/taskHandler.js';
+import { loadLocales } from '../utils/i18n.js';
+
+const execAsync = util.promisify(exec);
+
+export async function handleDNXT(message: Message, client: DJSNextClient, prefix: 'dnxt' | 'nxt' = 'dnxt') {
+  if (message.author.bot) return;
+  // Make sure only developers can use this
+  if (!client['_developers'].includes(message.author.id)) return;
+
+  if (!message.content.startsWith(prefix)) return;
+
+  const args = message.content.slice(prefix.length).trim().split(/ +/);
+  const command = args.shift()?.toLowerCase();
+
+  // Root dnxt command (Stats)
+  if (!command) {
+    const mem = process.memoryUsage();
+    const discordJsVersion = require('discord.js/package.json').version;
+    const botPing = client.ws.ping;
+    
+    const text = 
+      `Module was loaded <t:${Math.floor((Date.now() - client.uptime!) / 1000)}:R>.\n` +
+      `DNXT framework plugin, discord.js \`${discordJsVersion}\`, \`Node.js ${process.version}\` on \`${os.type()}\`.\n` +
+      `Latencies: \`${botPing}ms\` websocket ping.\n` +
+      `Memory: \`${(mem.rss / 1024 / 1024).toFixed(2)} MB\` physical, \`${(mem.heapUsed / 1024 / 1024).toFixed(2)} MB\` heap.\n` +
+      `System: \`${os.cpus().length}\` thread(s), \`${(os.uptime() / 60 / 60).toFixed(2)}\` hrs system uptime.`;
+
+    await message.reply(text);
+    return;
+  }
+
+  // Evaluation (js, eval, py)
+  if (command === 'js' || command === 'eval' || command === 'py') {
+    let code = args.join(' ');
+    if (code.startsWith('```js') || code.startsWith('```py')) code = code.replace(/^```[a-z]*|```$/g, '');
+    else if (code.startsWith('```')) code = code.replace(/^```|```$/g, '');
+
+    if (!code) return void await message.reply('❌ Please provide code to evaluate.');
+
+    try {
+      const start = process.hrtime.bigint();
+      const { commands, components, config } = client;
+      
+      // eslint-disable-next-line no-eval
+      let evaled = await eval(`(async () => { ${code} })()`);
+      const end = process.hrtime.bigint();
+      const timeMs = Number(end - start) / 1e6;
+
+      if (typeof evaled !== 'string') evaled = util.inspect(evaled, { depth: 1 });
+
+      await sendPaginatedText(message, `✅ **Evaluated in ${timeMs.toFixed(3)}ms**\n`, evaled, 'js');
+    } catch (err: any) {
+      await sendPaginatedText(message, `❌ **Evaluation Error**\n`, err.message, 'js');
+    }
+    return;
+  }
+
+  // Execute Shell (sh, shell, git)
+  if (command === 'sh' || command === 'shell' || command === 'git') {
+    const cmd = command === 'git' ? 'git ' + args.join(' ') : args.join(' ');
+    if (!cmd) return void await message.reply('❌ Please provide a command to execute.');
+
+    try {
+      const start = process.hrtime.bigint();
+      const { stdout, stderr } = await execAsync(cmd);
+      const end = process.hrtime.bigint();
+      const timeMs = Number(end - start) / 1e6;
+
+      const result = stdout || stderr || 'No output.';
+      await sendPaginatedText(message, `✅ **Executed in ${timeMs.toFixed(3)}ms**\n`, result, 'sh');
+    } catch (err: any) {
+      await sendPaginatedText(message, `❌ **Shell Error**\n`, err.message, 'sh');
+    }
+    return;
+  }
+
+  // Load / Unload / Reload
+  if (command === 'reload' || command === 'load') {
+    const target = args[0]?.toLowerCase();
+    try {
+      if (target === 'commands' && client['_commandsDir']) {
+        client.commands.clear();
+        client.commands = await loadAndDeployCommands(client['_commandsDir'], client.token!, client['_clientId']!, client['_guildId']);
+        await message.reply('✅ Reloaded commands.');
+      } else if (target === 'events' && client['_eventsDir']) {
+        client.removeAllListeners();
+        client['attachCoreListeners']();
+        await loadEvents(client, client['_eventsDir']);
+        await message.reply('✅ Reloaded events.');
+      } else if (target === 'components' && client['_componentsDir']) {
+        client.components.clear();
+        client.components = await loadComponents(client['_componentsDir']);
+        await message.reply('✅ Reloaded components.');
+      } else if (target === 'locales' && client['_localesDir']) {
+        loadLocales(client['_localesDir'], client.config.defaultLocale);
+        await message.reply('✅ Reloaded locales.');
+      } else if (target === 'all' || !target) {
+        client.removeAllListeners();
+        client['attachCoreListeners']();
+        client.commands.clear();
+        client.components.clear();
+        if (client['_eventsDir']) await loadEvents(client, client['_eventsDir']);
+        if (client['_componentsDir']) client.components = await loadComponents(client['_componentsDir']);
+        if (client['_localesDir']) loadLocales(client['_localesDir'], client.config.defaultLocale);
+        if (client['_commandsDir']) client.commands = await loadAndDeployCommands(client['_commandsDir'], client.token!, client['_clientId']!, client['_guildId']);
+        await message.reply('✅ Reloaded all framework modules.');
+      } else {
+        await message.reply('❌ Unknown target. Valid targets: `commands, events, components, locales, all`');
+      }
+    } catch (err: any) {
+      await message.reply(`❌ **Reload Error:** ${err.message}`);
+    }
+    return;
+  }
+
+  // Cat (Read File)
+  if (command === 'cat') {
+    const fs = await import('fs');
+    const path = await import('path');
+    const file = args.join(' ');
+    if (!file) return void await message.reply('❌ Please provide a file to read.');
+    
+    try {
+      const content = fs.readFileSync(path.resolve(process.cwd(), file), 'utf8');
+      await sendPaginatedText(message, `📄 **${file}**\n`, content, file.split('.').pop() || '');
+    } catch (e: any) {
+      await message.reply(`❌ **Error reading file:** ${e.message}`);
+    }
+    return;
+  }
+
+  // Sudo (Invoke command as another user)
+  if (command === 'su' || command === 'sudo') {
+    const targetUserId = args.shift();
+    const cmd = args.join(' ');
+    if (!targetUserId || !cmd) return void await message.reply(`❌ Usage: ${prefix} su <user_id> <command>`);
+    
+    try {
+      const targetUser = await client.users.fetch(targetUserId.replace(/<@!?|>/g, ''));
+      if (!targetUser) throw new Error('User not found.');
+      
+      // Create a mock message
+      const mockMessage = Object.assign(Object.create(Object.getPrototypeOf(message)), message);
+      mockMessage.author = targetUser;
+      if (message.guild) {
+        mockMessage.member = await message.guild.members.fetch(targetUser.id).catch(() => null);
+      }
+      mockMessage.content = cmd;
+      
+      client.emit('messageCreate', mockMessage as Message);
+      await message.reply(`✅ Invoked \`${cmd}\` as **${targetUser.tag}**.`);
+    } catch (e: any) {
+      await message.reply(`❌ **Sudo Error:** ${e.message}`);
+    }
+    return;
+  }
+
+  // Source Command (dnxt source <command>)
+  if (command === 'source' || command === 'src') {
+    const target = args.join(' ');
+    if (!target) return void await message.reply('❌ Please provide a command name.');
+    const cmdData = client.commands.get(target);
+    if (!cmdData || !cmdData.filepath) return void await message.reply('❌ Command not found or has no associated filepath.');
+    
+    try {
+      const fs = await import('fs');
+      const content = fs.readFileSync(cmdData.filepath, 'utf8');
+      await sendPaginatedText(message, `📄 **Source of \`${target}\`**\n`, content, cmdData.filepath.split('.').pop() || '');
+    } catch (e: any) {
+      await message.reply(`❌ **Error reading source:** ${e.message}`);
+    }
+    return;
+  }
+
+  // Curl (dnxt curl <url>)
+  if (command === 'curl') {
+    const url = args[0];
+    if (!url) return void await message.reply('❌ Please provide a URL.');
+    try {
+      const res = await fetch(url);
+      const text = await res.text();
+      await sendPaginatedText(message, `🌐 **Fetched from \`${url}\`**\n`, text, 'html');
+    } catch (e: any) {
+      await message.reply(`❌ **Curl Error:** ${e.message}`);
+    }
+    return;
+  }
+
+  // Debug Command (dnxt debug <command>)
+  // In discord.py DNXT debug measures execution of a command.
+  // In our case we will run a js eval and time it explicitly with heap usage.
+  if (command === 'debug') {
+    let code = args.join(' ');
+    if (code.startsWith('```js') || code.startsWith('```py')) code = code.replace(/^```[a-z]*|```$/g, '');
+    else if (code.startsWith('```')) code = code.replace(/^```|```$/g, '');
+    if (!code) return void await message.reply('❌ Please provide code to debug.');
+    
+    try {
+      const startMem = process.memoryUsage().heapUsed;
+      const start = process.hrtime.bigint();
+      const { commands, components, config } = client;
+      
+      // eslint-disable-next-line no-eval
+      let evaled = await eval(`(async () => { ${code} })()`);
+      
+      const end = process.hrtime.bigint();
+      const endMem = process.memoryUsage().heapUsed;
+      const timeMs = Number(end - start) / 1e6;
+      const memDiff = (endMem - startMem) / 1024 / 1024;
+      
+      if (typeof evaled !== 'string') evaled = util.inspect(evaled, { depth: 1 });
+      
+      await sendPaginatedText(message, `⏱️ **Debug Execution**\nTime: \`${timeMs.toFixed(3)}ms\` | Heap Delta: \`${memDiff.toFixed(3)}MB\`\n`, evaled, 'js');
+    } catch (err: any) {
+      await sendPaginatedText(message, `❌ **Debug Error**\n`, err.message, 'js');
+    }
+    return;
+  }
+
+  // In Command (dnxt in <channel_id> <command>)
+  if (command === 'in') {
+    const channelId = args.shift()?.replace(/<#|>/g, '');
+    const cmd = args.join(' ');
+    if (!channelId || !cmd) return void await message.reply(`❌ Usage: ${prefix} in <channel> <command>`);
+    try {
+      const targetChannel = await client.channels.fetch(channelId);
+      if (!targetChannel || !targetChannel.isTextBased()) throw new Error('Invalid Text Channel.');
+      
+      const mockMessage = Object.assign(Object.create(Object.getPrototypeOf(message)), message);
+      mockMessage.channel = targetChannel;
+      mockMessage.channelId = targetChannel.id;
+      mockMessage.content = cmd;
+      
+      client.emit('messageCreate', mockMessage as Message);
+      await message.reply(`✅ Redirected execution to <#${targetChannel.id}>.`);
+    } catch (e: any) {
+      await message.reply(`❌ **In Error:** ${e.message}`);
+    }
+    return;
+  }
+
+  // Tasks Command (dnxt tasks)
+  if (command === 'tasks') {
+    const tasks = (client as any)._activeTasks as Map<string, NodeJS.Timeout>;
+    if (!tasks || tasks.size === 0) return void await message.reply('No active background tasks running.');
+    
+    let text = `⚙️ **Active Background Tasks (${tasks.size})**\n`;
+    for (const [name] of tasks.entries()) {
+      text += `- \`${name.split('/').pop()}\`\n`;
+    }
+    await sendPaginatedText(message, '', text, '');
+    return;
+  }
+
+  // Cancel Command (dnxt cancel <task>)
+  if (command === 'cancel') {
+    const target = args.join(' ');
+    if (!target) return void await message.reply(`❌ Usage: ${prefix} cancel <task_name>`);
+    
+    const tasks = (client as any)._activeTasks as Map<string, NodeJS.Timeout>;
+    if (!tasks) return void await message.reply('No active tasks to cancel.');
+    
+    let found = false;
+    for (const [name, intervalId] of tasks.entries()) {
+      if (name.includes(target)) {
+        clearInterval(intervalId);
+        tasks.delete(name);
+        found = true;
+        await message.reply(`✅ Cancelled background task: \`${name.split('/').pop()}\``);
+        break;
+      }
+    }
+    if (!found) await message.reply('❌ Task not found.');
+    return;
+  }
+
+  // Sync Command (dnxt sync)
+  if (command === 'sync') {
+    try {
+      await message.reply('🔄 Force syncing slash commands...');
+      await loadAndDeployCommands((client as any)._commandsDir, client.token!, (client as any)._clientId, (client as any)._guildId);
+      await message.reply('✅ Slash commands synchronized globally/locally.');
+    } catch (e: any) {
+      await message.reply(`❌ **Sync Error:** ${e.message}`);
+    }
+    return;
+  }
+
+  // SQL Command (dnxt sql <query>)
+  if (command === 'sql') {
+    const query = args.join(' ');
+    if (!query) return void await message.reply(`❌ Usage: ${prefix} sql <query>`);
+    
+    try {
+      let res: any;
+      if (client.db && typeof client.db.$queryRawUnsafe === 'function') {
+        res = await client.db.$queryRawUnsafe(query); // Prisma fallback
+      } else if (client.db && typeof client.db.query === 'function') {
+        res = await client.db.query(query); // PG/MySQL fallback
+      } else {
+        return void await message.reply('❌ Your configured `client.db` does not expose a recognized raw SQL execution method (`$queryRawUnsafe` or `query`).');
+      }
+      const inspect = util.inspect(res, { depth: 2 });
+      await sendPaginatedText(message, `🗄️ **SQL Query**\n`, inspect, 'js');
+    } catch (e: any) {
+      await message.reply(`❌ **SQL Error:** ${e.message}`);
+    }
+    return;
+  }
+
+  // Voice Command (dnxt vc)
+  if (command === 'vc' || command === 'voice') {
+    if (!message.guild) return void await message.reply('❌ This command must be used in a server.');
+    const me = message.guild.members.me;
+    if (!me?.voice?.channel) return void await message.reply('❌ Bot is not currently in a voice channel.');
+    
+    const text = `🎙️ **Voice Debugger**\n` +
+      `Channel: <#${me.voice.channel.id}> (\`${me.voice.channel.id}\`)\n` +
+      `Muted: ${me.voice.mute} | Deafened: ${me.voice.deaf}\n` +
+      `Session ID: \`${me.voice.sessionId || 'None'}\``;
+    await message.reply(text);
+    return;
+  }
+
+  await message.reply(`❓ Unknown ${prefix} command. Available: \`js, sh, git, cat, curl, su, in, source, debug, reload, tasks, cancel, sync, sql, vc\``);
+}
+
+async function sendPaginatedText(message: Message, header: string, content: string, language: string = '') {
+  const maxLength = 1900;
+  if (content.length <= maxLength) {
+    await message.reply(`${header}\`\`\`${language}\n${content}\n\`\`\``);
+    return;
+  }
+
+  const chunks: string[] = [];
+  for (let i = 0; i < content.length; i += maxLength) {
+    chunks.push(content.substring(i, i + maxLength));
+  }
+
+  let index = 0;
+  const reply = await message.reply(`${header}\`\`\`${language}\n${chunks[index]}\n\`\`\`\n*Page 1 of ${chunks.length}*`);
+
+  await reply.react('◀️');
+  await reply.react('▶️');
+  await reply.react('⏹️');
+
+  const collector = reply.createReactionCollector({
+    filter: (reaction, user) => ['◀️', '▶️', '⏹️'].includes(reaction.emoji.name!) && user.id === message.author.id,
+    time: 120000
+  });
+
+  collector.on('collect', async (reaction, user) => {
+    await reaction.users.remove(user.id).catch(() => null);
+
+    if (reaction.emoji.name === '◀️') {
+      index = index > 0 ? index - 1 : index;
+    } else if (reaction.emoji.name === '▶️') {
+      index = index < chunks.length - 1 ? index + 1 : index;
+    } else if (reaction.emoji.name === '⏹️') {
+      collector.stop();
+      return;
+    }
+
+    await reply.edit(`${header}\`\`\`${language}\n${chunks[index]}\n\`\`\`\n*Page ${index + 1} of ${chunks.length}*`);
+  });
+
+  collector.on('end', () => {
+    reply.reactions.removeAll().catch(() => null);
+  });
+}

package/src/templates/cjs.ts

@@ -0,0 +1,49 @@
+export const cjsTemplates = {
+  index: `const { DJSNextClient, GatewayIntentBits } = require('djs-next');
+require('dotenv/config');
+
+const client = new DJSNextClient({
+  intents: [GatewayIntentBits.Guilds, GatewayIntentBits.GuildMessages],
+  commandsDir: './src/commands',
+  eventsDir: './src/events',
+  componentsDir: './src/components',
+  tasksDir: './src/tasks',
+  clientId: process.env.CLIENT_ID
+});
+
+client.start(process.env.DISCORD_TOKEN);
+`,
+
+  ping: `module.exports = {
+  command: {
+    description: 'Replies with Pong!',
+    execute: async (interaction) => {
+      await interaction.reply('Pong!');
+    }
+  }
+};
+`,
+
+  ready: `const { Events } = require('djs-next');
+
+module.exports = {
+  event: {
+    name: Events.ClientReady,
+    once: true,
+    execute: (client) => {
+      console.log('Ready! Logged in as ' + client.user?.tag);
+    }
+  }
+};
+`,
+
+  healthcheck: `module.exports = {
+  task: {
+    interval: 60000,
+    execute: async (client) => {
+      console.log('[Task] Healthcheck completed.');
+    }
+  }
+};
+`
+};

package/src/templates/esm.ts

@@ -0,0 +1,43 @@
+export const esmTemplates = {
+  index: `import { DJSNextClient, GatewayIntentBits } from 'djs-next';
+import 'dotenv/config';
+
+const client = new DJSNextClient({
+  intents: [GatewayIntentBits.Guilds, GatewayIntentBits.GuildMessages],
+  commandsDir: './src/commands',
+  eventsDir: './src/events',
+  componentsDir: './src/components',
+  tasksDir: './src/tasks',
+  clientId: process.env.CLIENT_ID
+});
+
+client.start(process.env.DISCORD_TOKEN);
+`,
+
+  ping: `export const command = {
+  description: 'Replies with Pong!',
+  execute: async (interaction) => {
+    await interaction.reply('Pong!');
+  }
+};
+`,
+
+  ready: `import { Events } from 'djs-next';
+
+export const event = {
+  name: Events.ClientReady,
+  once: true,
+  execute: (client) => {
+    console.log('Ready! Logged in as ' + client.user?.tag);
+  }
+};
+`,
+
+  healthcheck: `export const task = {
+  interval: 60000,
+  execute: async (client) => {
+    console.log('[Task] Healthcheck completed.');
+  }
+};
+`
+};

package/src/templates/ts.ts

@@ -0,0 +1,47 @@
+export const tsTemplates = {
+  index: `import { DJSNextClient, GatewayIntentBits } from 'djs-next';
+import 'dotenv/config';
+
+const client = new DJSNextClient({
+  intents: [GatewayIntentBits.Guilds, GatewayIntentBits.GuildMessages],
+  commandsDir: './src/commands',
+  eventsDir: './src/events',
+  componentsDir: './src/components',
+  tasksDir: './src/tasks',
+  clientId: process.env.CLIENT_ID
+});
+
+client.start(process.env.DISCORD_TOKEN!);
+`,
+
+  ping: `import { FileCommand } from 'djs-next';
+
+export const command: FileCommand = {
+  description: 'Replies with Pong!',
+  execute: async (interaction) => {
+    await interaction.reply('Pong!');
+  }
+};
+`,
+
+  ready: `import { DJSNextEvent, Events } from 'djs-next';
+
+export const event: DJSNextEvent<Events.ClientReady> = {
+  name: Events.ClientReady,
+  once: true,
+  execute: (client) => {
+    console.log('Ready! Logged in as ' + client.user?.tag);
+  }
+};
+`,
+
+  healthcheck: `import { FileTask } from 'djs-next';
+
+export const task: FileTask = {
+  interval: 60000,
+  execute: async (client) => {
+    console.log('[Task] Healthcheck completed.');
+  }
+};
+`
+};

package/src/test/client.test.ts

@@ -0,0 +1,8 @@
+import { DJSNextClient } from '../client.js';
+
+describe('DJSNextClient', () => {
+  it('should instantiate without throwing', () => {
+    const client = new DJSNextClient({ intents: [] });
+    expect(client).toBeDefined();
+  });
+});

package/src/types.ts

@@ -0,0 +1,69 @@
+import {
+  ClientOptions,
+  ClientEvents,
+  ChatInputCommandInteraction,
+  Client,
+  ApplicationCommandOptionData,
+  PermissionResolvable,
+  AutocompleteInteraction,
+  MessageComponentInteraction,
+  ModalSubmitInteraction,
+  Interaction
+} from 'discord.js';
+
+export interface DJSNextConfig {
+  devGuildId?: string;
+  locales?: string[];
+  defaultLocale?: string;
+  directories?: {
+    commands?: string;
+    events?: string;
+    components?: string;
+    tasks?: string;
+    locales?: string;
+  };
+}
+
+export interface DJSNextClientOptions extends ClientOptions {
+  commandsDir?: string;
+  eventsDir?: string;
+  componentsDir?: string;
+  tasksDir?: string;
+  clientId?: string;
+  guildId?: string;
+  developers?: string[];
+  middleware?: (interaction: Interaction, client: Client) => Promise<boolean> | boolean;
+  config?: DJSNextConfig;
+}
+
+export interface FileTask<DB = any> {
+  filepath?: string;
+  interval: number;
+  execute: (client: Client & { db: DB; t: Function; config: DJSNextConfig }) => Promise<void> | void;
+}
+
+export interface FileCommand<DB = any> {
+  filepath?: string;
+  description: string;
+  options?: ApplicationCommandOptionData[];
+  cooldown?: number;
+  userPermissions?: PermissionResolvable[];
+  botPermissions?: PermissionResolvable[];
+  developerOnly?: boolean;
+  guildOnly?: boolean;
+  execute?: (interaction: ChatInputCommandInteraction, client: Client & { db: DB; t: Function; config: DJSNextConfig }) => Promise<void> | void;
+  autocomplete?: (interaction: AutocompleteInteraction, client: Client & { db: DB; t: Function; config: DJSNextConfig }) => Promise<void> | void;
+}
+
+export interface FileComponent<DB = any> {
+  filepath?: string;
+  customId?: string;
+  execute: (interaction: MessageComponentInteraction | ModalSubmitInteraction, client: Client & { db: DB; t: Function; config: DJSNextConfig }, params?: Record<string, string>) => Promise<void> | void;
+}
+
+export interface Event<K extends keyof ClientEvents = keyof ClientEvents, DB = any> {
+  filepath?: string;
+  name: K;
+  once?: boolean;
+  execute: (client: Client & { db: DB; t: Function; config: DJSNextConfig }, ...args: ClientEvents[K]) => Promise<void> | void;
+}

package/src/utils/configLoader.ts

@@ -0,0 +1,27 @@
+import path from 'path';
+import fs from 'fs';
+import { pathToFileURL } from 'url';
+import { DJSNextConfig } from '../types.js';
+
+export async function loadConfig(): Promise<DJSNextConfig> {
+  const exts = ['.js', '.mjs', '.cjs', '.ts', '.mts', '.cts'];
+  const cwd = process.cwd();
+  
+  for (const ext of exts) {
+    const configPath = path.join(cwd, `djs-next.config${ext}`);
+    if (fs.existsSync(configPath)) {
+      try {
+        const configModule = await import(pathToFileURL(configPath).href);
+        return configModule.default || configModule;
+      } catch (err) {
+        console.error(`[djs-next] Error loading config file ${configPath}:`, err);
+        return {};
+      }
+    }
+  }
+  return {};
+}
+
+export function defineConfig(config: DJSNextConfig): DJSNextConfig {
+  return config;
+}

package/src/utils/i18n.ts

@@ -0,0 +1,57 @@
+import fs from 'fs';
+import path from 'path';
+
+let localesCache: Record<string, Record<string, any>> = {};
+let defaultLoc = 'en';
+
+export function loadLocales(localesDir: string, defaultLocale?: string) {
+  if (defaultLocale) defaultLoc = defaultLocale;
+  
+  if (!fs.existsSync(localesDir)) return;
+
+  const files = fs.readdirSync(localesDir);
+  for (const file of files) {
+    if (file.endsWith('.json')) {
+      const lang = file.replace('.json', '');
+      const content = fs.readFileSync(path.join(localesDir, file), 'utf8');
+      try {
+        localesCache[lang] = JSON.parse(content);
+      } catch (e) {
+        console.error(`[djs-next] Failed to parse locale file: ${file}`, e);
+      }
+    }
+  }
+}
+
+export function translate(key: string, locale: string = defaultLoc, variables?: Record<string, string | number>): string {
+  // Fallback to default locale if the requested one is not found
+  const dict = localesCache[locale] || localesCache[defaultLoc] || {};
+  
+  const keys = key.split('.');
+  let value: any = dict;
+
+  for (const k of keys) {
+    if (value && typeof value === 'object') {
+      value = value[k];
+    } else {
+      value = undefined;
+      break;
+    }
+  }
+
+  if (typeof value !== 'string') {
+    return key; // return the key itself if string not found
+  }
+
+  if (variables) {
+    for (const [varKey, varValue] of Object.entries(variables)) {
+      value = value.replace(new RegExp(`{{s*${varKey}s*}}`, 'g'), String(varValue));
+    }
+  }
+
+  return value;
+}
+
+export function getLocalesCache() {
+  return localesCache;
+}