create-forgeon 0.1.26 → 0.1.29

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-forgeon",
-  "version": "0.1.26",
+  "version": "0.1.29",
   "description": "Forgeon project generator CLI",
   "license": "MIT",
   "author": "Forgeon",

package/src/modules/executor.test.mjs

@@ -140,7 +140,7 @@ describe('addModule', () => {
       const appTsx = fs.readFileSync(path.join(projectRoot, 'apps', 'web', 'src', 'App.tsx'), 'utf8');
       assert.match(appTsx, /@forgeon\/i18n-web/);
       assert.match(appTsx, /react-i18next/);
-      assert.match(appTsx, /checkApiHealth/);
+      assert.match(appTsx, /ui:labels\.language/);
 
       const i18nWebPackage = fs.readFileSync(
         path.join(projectRoot, 'packages', 'i18n-web', 'package.json'),
@@ -184,13 +184,14 @@ describe('addModule', () => {
       const enCommon = JSON.parse(
         fs.readFileSync(path.join(projectRoot, 'resources', 'i18n', 'en', 'common.json'), 'utf8'),
       );
-      assert.equal(enCommon.checkApiHealth, 'Check API health');
-      assert.equal(enCommon.languages.english, 'English');
+      assert.equal(enCommon.actions.ok, 'OK');
+      assert.equal(enCommon.nav.next, 'Next');
 
       const enErrors = JSON.parse(
         fs.readFileSync(path.join(projectRoot, 'resources', 'i18n', 'en', 'errors.json'), 'utf8'),
       );
-      assert.equal(enErrors.notFound, 'Resource not found');
+      assert.equal(enErrors.http.NOT_FOUND, 'Resource not found');
+      assert.equal(enErrors.validation.VALIDATION_ERROR, 'Validation error');
 
       const webPackage = fs.readFileSync(path.join(projectRoot, 'apps', 'web', 'package.json'), 'utf8');
       assert.match(webPackage, /"i18next":/);
@@ -202,12 +203,17 @@ describe('addModule', () => {
       const i18nTs = fs.readFileSync(path.join(projectRoot, 'apps', 'web', 'src', 'i18n.ts'), 'utf8');
       assert.match(i18nTs, /initReactI18next/);
       assert.match(i18nTs, /\.\.\/\.\.\/\.\.\/resources\/i18n\/en\/common\.json/);
+      assert.match(i18nTs, /\.\.\/\.\.\/\.\.\/resources\/i18n\/en\/ui\.json/);
       assert.doesNotMatch(i18nTs, /I18N_DEFAULT_LANG/);
 
       const rootPackage = fs.readFileSync(path.join(projectRoot, 'package.json'), 'utf8');
       assert.match(rootPackage, /"i18n:sync"/);
       assert.match(rootPackage, /"i18n:check"/);
       assert.match(rootPackage, /"i18n:types"/);
+      assert.match(rootPackage, /"i18n:add"/);
+
+      const i18nAddScriptPath = path.join(projectRoot, 'scripts', 'i18n-add.mjs');
+      assert.equal(fs.existsSync(i18nAddScriptPath), true);
 
       const caddyDockerfile = fs.readFileSync(
         path.join(projectRoot, 'infra', 'docker', 'caddy.Dockerfile'),

package/src/modules/i18n.mjs

@@ -311,10 +311,12 @@ function patchRootPackage(targetRoot) {
     'i18n:types',
     'pnpm --filter @forgeon/i18n-contracts i18n:types',
   );
+  ensureScript(packageJson, 'i18n:add', 'node scripts/i18n-add.mjs');
   writeJson(packagePath, packageJson);
 }
 
 export function applyI18nModule({ packageRoot, targetRoot }) {
+  copyFromBase(packageRoot, targetRoot, path.join('scripts', 'i18n-add.mjs'));
   copyFromBase(packageRoot, targetRoot, path.join('packages', 'db-prisma'));
   copyFromBase(packageRoot, targetRoot, path.join('packages', 'i18n'));
   copyFromBase(packageRoot, targetRoot, path.join('resources', 'i18n'));

package/src/presets/i18n.mjs

@@ -102,6 +102,7 @@ export function applyI18nDisabled(targetRoot) {
       delete rootPackage.scripts['i18n:sync'];
       delete rootPackage.scripts['i18n:check'];
       delete rootPackage.scripts['i18n:types'];
+      delete rootPackage.scripts['i18n:add'];
     }
     writeJson(rootPackagePath, rootPackage);
   }
@@ -144,21 +145,19 @@ export class AppModule {}
   );
   fs.writeFileSync(
     healthControllerPath,
-    `import { ConflictException, Controller, Get, Post, Query } from '@nestjs/common';
+    `import { BadRequestException, ConflictException, Controller, Get, Post, Query } from '@nestjs/common';
 import { PrismaService } from '@forgeon/db-prisma';
-import { EchoQueryDto } from '../common/dto/echo-query.dto';
 
 @Controller('health')
 export class HealthController {
   constructor(private readonly prisma: PrismaService) {}
 
   @Get()
-  getHealth(@Query('lang') lang?: string) {
-    const locale = this.resolveLocale(lang);
+  getHealth(@Query('lang') _lang?: string) {
     return {
       status: 'ok',
       message: 'OK',
-      i18n: locale === 'uk' ? 'Ukrainian' : 'English',
+      i18n: 'English',
     };
   }
 
@@ -168,17 +167,25 @@ export class HealthController {
       message: 'Email already exists',
       details: {
         feature: 'core-errors',
-        probe: 'health.error',
+        probeId: 'health.error',
+        probe: 'Error envelope probe',
       },
     });
   }
 
   @Get('validation')
-  getValidationProbe(@Query() query: EchoQueryDto) {
+  getValidationProbe(@Query('value') value?: string) {
+    if (!value || value.trim().length === 0) {
+      throw new BadRequestException({
+        message: 'Field is required',
+        details: [{ field: 'value', message: 'Field is required' }],
+      });
+    }
+
     return {
       status: 'ok',
       validated: true,
-      value: query.value,
+      value,
     };
   }
 
@@ -197,11 +204,6 @@ export class HealthController {
       user,
     };
   }
-
-  private resolveLocale(lang?: string): 'en' | 'uk' {
-    const normalized = (lang ?? '').toLowerCase();
-    return normalized.startsWith('uk') ? 'uk' : 'en';
-  }
 }
 `,
     'utf8',

package/templates/base/apps/api/src/common/dto/echo-query.dto.ts

@@ -1,6 +1,6 @@
 import { IsNotEmpty } from 'class-validator';
 
-export class EchoQueryDto {
-  @IsNotEmpty({ message: 'validation.required' })
-  value!: string;
-}
+export class EchoQueryDto {
+  @IsNotEmpty({ message: 'validation.generic.required' })
+  value!: string;
+}

package/templates/base/apps/api/src/health/health.controller.ts

@@ -1,42 +1,49 @@
-import { ConflictException, Controller, Get, Optional, Post, Query } from '@nestjs/common';
+import { BadRequestException, ConflictException, Controller, Get, Post, Query } from '@nestjs/common';
 import { PrismaService } from '@forgeon/db-prisma';
 import { I18nService } from 'nestjs-i18n';
-import { EchoQueryDto } from '../common/dto/echo-query.dto';
 
 @Controller('health')
 export class HealthController {
   constructor(
     private readonly prisma: PrismaService,
-    @Optional() private readonly i18n?: I18nService,
+    private readonly i18n: I18nService,
   ) {}
 
   @Get()
   getHealth(@Query('lang') lang?: string) {
-    const locale = this.resolveLocale(lang);
     return {
       status: 'ok',
-      message: this.translate('common.ok', lang),
-      i18n: this.translate(this.localeNameKey(locale), lang),
+      message: this.translate('common.actions.ok', lang),
+      i18n: 'en',
     };
   }
 
   @Get('error')
-  getErrorProbe() {
+  getErrorProbe(@Query('lang') lang?: string) {
     throw new ConflictException({
-      message: 'Email already exists',
+      message: this.translate('errors.http.CONFLICT', lang),
       details: {
         feature: 'core-errors',
-        probe: 'health.error',
+        probeId: 'health.error',
+        probe: 'Error envelope probe',
       },
     });
   }
 
   @Get('validation')
-  getValidationProbe(@Query() query: EchoQueryDto) {
+  getValidationProbe(@Query('value') value?: string, @Query('lang') lang?: string) {
+    if (!value || value.trim().length === 0) {
+      const translatedMessage = this.translate('validation.generic.required', lang);
+      throw new BadRequestException({
+        message: translatedMessage,
+        details: [{ field: 'value', message: translatedMessage }],
+      });
+    }
+
     return {
       status: 'ok',
       validated: true,
-      value: query.value,
+      value,
     };
   }
 
@@ -57,26 +64,7 @@ export class HealthController {
   }
 
   private translate(key: string, lang?: string): string {
-    if (!this.i18n) {
-      if (key === 'common.ok') return 'OK';
-      if (key === 'common.languages.english') return 'English';
-      if (key === 'common.languages.ukrainian') return 'Ukrainian';
-      return key;
-    }
-
     const value = this.i18n.t(key, { lang, defaultValue: key });
     return typeof value === 'string' ? value : key;
   }
-
-  private resolveLocale(lang?: string): 'en' | 'uk' {
-    const normalized = (lang ?? '').toLowerCase();
-    if (normalized.startsWith('uk')) {
-      return 'uk';
-    }
-    return 'en';
-  }
-
-  private localeNameKey(locale: 'en' | 'uk'): string {
-    return locale === 'uk' ? 'common.languages.ukrainian' : 'common.languages.english';
-  }
 }

package/templates/base/docs/AI/MODULE_SPEC.md

@@ -64,3 +64,5 @@ Must contain:
 - Contracts package exports are stable from `dist/index` entrypoint.
 - Module has docs under `docs/AI/MODULES/<module-id>.md`.
 - If module behavior can be runtime-checked, it also includes API+Web probe hooks (see `docs/AI/MODULE_CHECKS.md`).
+- If i18n is enabled, module-specific namespaces must be created and wired for both API and web.
+- If module is added before i18n, namespace templates must still be prepared and applied when i18n is installed later.

package/templates/base/docs/AI/ROADMAP.md

@@ -0,0 +1,171 @@
+# ROADMAP
+
+This is a living plan. Scope and priorities may change.
+
+## Current Foundation (Implemented)
+
+- [x] Canonical scaffold: NestJS API + React web + Prisma/Postgres + Docker
+- [x] Proxy preset selection: `caddy | nginx | none`
+- [x] `@forgeon/core`:
+  - [x] `core-config` (typed env config + validation)
+  - [x] `core-errors` (global envelope + exception filter)
+  - [x] `core-validation` (global validation pipe)
+- [x] `@forgeon/db-prisma` as default-applied DB module
+- [x] i18n add-module baseline:
+  - [x] `@forgeon/i18n`, `@forgeon/i18n-contracts`, `@forgeon/i18n-web`
+  - [x] shared dictionaries in `resources/i18n/*`
+  - [x] tooling: `i18n:sync`, `i18n:check`, `i18n:types`, `i18n:add`
+- [x] module diagnostics probes pattern (`/api/health/*` + web test buttons)
+
+## Standards (Accepted)
+
+- [x] `*-contracts` and `*-web` packages are ESM-first
+- [x] API runtime modules use Node-oriented TS config
+- [x] no cross-package imports via `/src/*`; only package entrypoints
+
+## Updated Priority Backlog
+
+### P0 (Immediate Must-Have)
+
+- [ ] `logger`
+  - [ ] canonical logger module
+  - [ ] requestId / correlationId propagation
+  - [ ] structured log conventions
+
+- [ ] `openapi / swagger`
+  - [ ] env toggle: `SWAGGER_ENABLED`
+  - [ ] standard setup
+  - [ ] bearer integration hook for jwt-auth
+  - [ ] `/docs` route
+
+- [ ] `jwt-auth`
+  - [ ] module split: contracts/api/web
+  - [ ] access + refresh baseline
+  - [ ] guards/strategy integration
+
+- [ ] `rbac / permissions`
+  - [ ] decorators: `@Roles()`, `@Permissions()`
+  - [ ] guard + policy helper
+  - [ ] contracts: `Role`, `Permission`
+  - [ ] integration with jwt-auth claims
+
+- [ ] `redis/queue foundation`
+  - [ ] base Redis config/service
+  - [ ] queue baseline (BullMQ or equivalent)
+  - [ ] retry and dead-letter conventions
+
+- [ ] `rate-limit`
+  - [ ] Nest Throttler add-module
+  - [ ] policies: route / user / ip
+  - [ ] error code: `TOO_MANY_REQUESTS`
+  - [ ] reverse-proxy-aware mode (`trust proxy`)
+
+- [ ] `files` (upload + storage)
+  - [ ] upload endpoints + DTO + guards
+  - [ ] storage presets: local + S3-compatible (MinIO/R2)
+  - [ ] MIME/size validation
+  - [ ] optional image processing subpackage (`sharp`)
+  - [ ] error codes: `UPLOAD_INVALID_TYPE`, `UPLOAD_TOO_LARGE`, `UPLOAD_QUOTA`
+
+### P1 (Strongly Recommended)
+
+- [ ] `testing baseline`
+  - [ ] unit + e2e presets
+  - [ ] test helpers for add-modules
+  - [ ] smoke test template for generated project
+
+- [ ] `CI quality gates`
+  - [ ] `typecheck`, `lint`, `test`, docker build smoke
+  - [ ] release gate checklist
+
+- [ ] `cache` (Redis)
+  - [ ] CacheModule preset
+  - [ ] key naming conventions
+  - [ ] shared wrapper/service
+
+- [ ] `scheduler`
+  - [ ] `@nestjs/schedule` integration
+  - [ ] task template
+  - [ ] optional distributed lock (Redis)
+
+- [ ] `mail`
+  - [ ] at least one provider preset (SMTP/Resend/SendGrid)
+  - [ ] templates: verify email, reset password
+  - [ ] optional outbox with queue
+
+- [ ] workspace `eslint/prettier` config package
+
+### P2 (Later)
+
+- [ ] frontend `http-client` module
+- [ ] frontend UI kit package
+  - [ ] migrate reusable parts from `eso-dt` (when available)
+  - [ ] extend missing primitives
+- [ ] `realtime` (ws)
+  - [ ] gateway baseline
+  - [ ] jwt auth for ws
+  - [ ] rooms + basic events
+- [ ] `webhooks` module (subject to scope validation)
+  - [ ] signed inbound verify (HMAC)
+  - [ ] signed outbound sender
+  - [ ] replay protection (timestamp/nonce)
+
+## Execution Plan (3 Sprints)
+
+### Sprint 1: Platform Baseline and Security Start
+
+Scope:
+- `logger`
+- `openapi/swagger`
+- `jwt-auth`
+- `testing baseline`
+- `CI quality gates`
+
+Definition of Done:
+- add-modules install cleanly via `create-forgeon add <module>`
+- local dev (`pnpm dev`) and docker build both pass on fresh generated project
+- each module has probe endpoint and web probe UI hook when applicable
+- docs updated in both root and template docs
+
+### Sprint 2: Authorization and Traffic Control
+
+Scope:
+- `rbac/permissions`
+- `redis/queue foundation`
+- `rate-limit`
+- `files`
+- `cache`
+
+Definition of Done:
+- claims/roles/permissions flow validated end-to-end (api + web contracts)
+- rate-limit and files include standardized error codes and envelope mapping
+- Redis-backed modules run in docker profile with documented env keys
+- at least one e2e happy-path per module
+
+### Sprint 3: Async Integrations and Frontend Foundation
+
+Scope:
+- `scheduler`
+- `mail`
+- workspace `eslint/prettier` config package
+- frontend `http-client`
+
+Definition of Done:
+- queue/scheduler/mail basic scenarios work in local + docker
+- frontend http-client consumes api contracts with typed errors
+- lint/typecheck/test/build pass through CI gate preset
+- docs include migration notes and extension points
+
+## Explicit Dependencies and Order Constraints
+
+- `rbac` depends on `jwt-auth`
+- `rate-limit` should follow Redis/queue foundation for scalable mode
+- `mail` should reuse queue foundation where possible
+- `openapi` is most useful before/with `jwt-auth` and `http-client`
+- `realtime` and `webhooks` stay post-MVP unless a concrete use-case appears
+
+## i18n Policy For Add-Modules
+
+- [ ] each add-module that introduces user-facing text defines its own namespace templates
+- [ ] if i18n is already enabled, namespace files are added during module installation
+- [ ] if module is installed first and i18n later, namespaces are merged during i18n installation

package/templates/base/docs/AI/TASKS.md

@@ -53,6 +53,7 @@ Requirements:
 - split module into contracts/api/web packages
 - contracts is source of truth for routes, DTOs, errors
 - if feasible, add module probe hooks in API (`/api/health/*`) and web diagnostics UI
+- if i18n is enabled, add module namespace files and wire them for both API and web
 - add docs note under docs/AI/MODULES/<module-id>.md
 - keep backward compatibility
 ```

package/templates/base/docs/README.md

@@ -2,7 +2,17 @@
 
 - `AI/PROJECT.md` - project overview and run modes
 - `AI/ARCHITECTURE.md` - monorepo design and extension model
+- `AI/ROADMAP.md` - implementation roadmap and feature priorities
 - `AI/MODULE_SPEC.md` - fullstack module contract (`contracts/api/web`)
 - `AI/MODULE_CHECKS.md` - required runtime probe hooks for modules
 - `AI/VALIDATION.md` - DTO/env validation standards
 - `AI/TASKS.md` - ready-to-use Codex prompts
+
+## i18n Language Workflow
+
+Add a new language from existing namespaces:
+- `pnpm i18n:add uk`
+
+Useful follow-up commands:
+- `pnpm i18n:sync`
+- `pnpm i18n:check`

package/templates/base/packages/core/src/errors/core-exception.filter.ts

@@ -51,17 +51,29 @@ export class CoreExceptionFilter implements ExceptionFilter {
   private resolveCode(status: number): string {
     switch (status) {
       case HttpStatus.BAD_REQUEST:
-        return 'validation_error';
+        return 'BAD_REQUEST';
       case HttpStatus.UNAUTHORIZED:
-        return 'unauthorized';
+        return 'UNAUTHORIZED';
       case HttpStatus.FORBIDDEN:
-        return 'forbidden';
+        return 'FORBIDDEN';
       case HttpStatus.NOT_FOUND:
-        return 'not_found';
+        return 'NOT_FOUND';
       case HttpStatus.CONFLICT:
-        return 'conflict';
+        return 'CONFLICT';
+      case HttpStatus.TOO_MANY_REQUESTS:
+        return 'TOO_MANY_REQUESTS';
+      case HttpStatus.METHOD_NOT_ALLOWED:
+        return 'METHOD_NOT_ALLOWED';
+      case HttpStatus.UNPROCESSABLE_ENTITY:
+        return 'UNPROCESSABLE_ENTITY';
+      case HttpStatus.SERVICE_UNAVAILABLE:
+        return 'SERVICE_UNAVAILABLE';
+      case HttpStatus.BAD_GATEWAY:
+        return 'BAD_GATEWAY';
+      case HttpStatus.GATEWAY_TIMEOUT:
+        return 'GATEWAY_TIMEOUT';
       default:
-        return 'internal_error';
+        return 'INTERNAL_ERROR';
     }
   }
 

package/templates/base/resources/i18n/en/common.json

@@ -1,12 +1,42 @@
 {
-  "ok": "OK",
-  "checkApiHealth": "Check API health",
-  "checkErrorEnvelope": "Check error envelope",
-  "checkValidation": "Check validation (expect 400)",
-  "checkDatabase": "Check database (create user)",
-  "language": "Language",
-  "languages": {
-    "english": "English",
-    "ukrainian": "Ukrainian"
+  "actions": {
+    "ok": "OK",
+    "cancel": "Cancel",
+    "save": "Save",
+    "delete": "Delete",
+    "edit": "Edit",
+    "create": "Create",
+    "update": "Update",
+    "confirm": "Confirm",
+    "retry": "Retry"
+  },
+  "nav": {
+    "back": "Back",
+    "next": "Next",
+    "close": "Close"
+  },
+  "state": {
+    "loading": "Loading...",
+    "empty": "No data",
+    "selected": "Selected"
+  },
+  "status": {
+    "active": "Active",
+    "inactive": "Inactive",
+    "pending": "Pending",
+    "disabled": "Disabled",
+    "archived": "Archived"
+  },
+  "time": {
+    "today": "Today",
+    "yesterday": "Yesterday",
+    "tomorrow": "Tomorrow",
+    "now": "Now"
+  },
+  "misc": {
+    "yes": "Yes",
+    "no": "No",
+    "on": "On",
+    "off": "Off"
   }
 }

package/templates/base/resources/i18n/en/errors.json

@@ -1,4 +1,33 @@
 {
-  "accessDenied": "Access denied",
-  "notFound": "Resource not found"
+  "http": {
+    "BAD_REQUEST": "Bad request",
+    "NOT_FOUND": "Resource not found",
+    "UNAUTHORIZED": "Unauthorized",
+    "FORBIDDEN": "Access denied",
+    "CONFLICT": "Conflict",
+    "TOO_MANY_REQUESTS": "Too many requests",
+    "METHOD_NOT_ALLOWED": "Method not allowed",
+    "UNPROCESSABLE_ENTITY": "Unprocessable entity",
+    "INTERNAL_ERROR": "Internal server error",
+    "SERVICE_UNAVAILABLE": "Service unavailable",
+    "BAD_GATEWAY": "Bad gateway",
+    "GATEWAY_TIMEOUT": "Gateway timeout"
+  },
+  "network": {
+    "NETWORK_ERROR": "Network error",
+    "TIMEOUT": "Request timeout",
+    "OFFLINE": "You appear to be offline"
+  },
+  "auth": {
+    "AUTH_INVALID_CREDENTIALS": "Invalid credentials",
+    "AUTH_TOKEN_EXPIRED": "Session expired"
+  },
+  "validation": {
+    "VALIDATION_ERROR": "Validation error"
+  },
+  "files": {
+    "UPLOAD_FILE_TOO_LARGE": "File is too large",
+    "UPLOAD_INVALID_TYPE": "Invalid file type",
+    "UPLOAD_QUOTA_EXCEEDED": "Upload quota exceeded"
+  }
 }

package/templates/base/resources/i18n/en/meta.json

@@ -0,0 +1,8 @@
+{
+  "pages": {
+    "home": {
+      "title": "Forgeon Fullstack Scaffold",
+      "description": "Canonical fullstack starter with NestJS, React, and Prisma."
+    }
+  }
+}

package/templates/base/resources/i18n/en/notifications.json

@@ -0,0 +1,21 @@
+{
+  "success": {
+    "saved": "Saved successfully",
+    "updated": "Updated successfully",
+    "deleted": "Deleted successfully",
+    "copied": "Copied successfully"
+  },
+  "error": {
+    "saveFailed": "Failed to save",
+    "updateFailed": "Failed to update",
+    "deleteFailed": "Failed to delete"
+  },
+  "info": {
+    "changesDiscarded": "Changes were discarded",
+    "sessionExpired": "Your session has expired"
+  },
+  "progress": {
+    "uploading": "Uploading...",
+    "processing": "Processing..."
+  }
+}

package/templates/base/resources/i18n/en/ui.json

@@ -0,0 +1,31 @@
+{
+  "labels": {
+    "name": "Name",
+    "email": "Email",
+    "password": "Password",
+    "search": "Search",
+    "language": "Language"
+  },
+  "placeholders": {
+    "email": "Enter email",
+    "search": "Search...",
+    "password": "Enter password"
+  },
+  "titles": {
+    "home": "Home",
+    "dashboard": "Dashboard",
+    "settings": "Settings"
+  },
+  "messages": {
+    "emptyState": "Nothing to display yet",
+    "noResults": "No results found"
+  },
+  "table": {
+    "rowsPerPage": "Rows per page",
+    "noData": "No data"
+  },
+  "modal": {
+    "confirmTitle": "Please confirm",
+    "confirmText": "Are you sure you want to continue?"
+  }
+}

package/templates/base/resources/i18n/en/validation.json

@@ -1,3 +1,32 @@
 {
-  "required": "Field is required"
+  "generic": {
+    "required": "Field is required",
+    "invalid": "Invalid value",
+    "outOfRange": "Value is out of range"
+  },
+  "string": {
+    "minLength": "Value is too short",
+    "maxLength": "Value is too long",
+    "pattern": "Value does not match required format"
+  },
+  "number": {
+    "min": "Value is too small",
+    "max": "Value is too large",
+    "int": "Value must be an integer"
+  },
+  "format": {
+    "email": "Invalid email format",
+    "phone": "Invalid phone format",
+    "url": "Invalid URL format",
+    "uuid": "Invalid UUID format"
+  },
+  "date": {
+    "minDate": "Date is too early",
+    "maxDate": "Date is too late",
+    "invalidDate": "Invalid date"
+  },
+  "file": {
+    "fileTooLarge": "File is too large",
+    "invalidType": "Invalid file type"
+  }
 }

package/templates/base/scripts/i18n-add.mjs

@@ -0,0 +1,191 @@
+import { spawn } from 'node:child_process';
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+
+const LOCALE_REGEX = /^[a-z]{2}(-[A-Z]{2})?$/;
+
+function printUsage() {
+  console.log('Usage: pnpm i18n:add <locale> [--copy-from=en] [--force] [--empty] [--no-sync]');
+}
+
+function parseArgs(argv) {
+  const options = {
+    locale: '',
+    copyFrom: 'en',
+    force: false,
+    empty: false,
+    noSync: false,
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === '--force') {
+      options.force = true;
+      continue;
+    }
+    if (arg === '--empty') {
+      options.empty = true;
+      continue;
+    }
+    if (arg === '--no-sync') {
+      options.noSync = true;
+      continue;
+    }
+    if (arg.startsWith('--copy-from=')) {
+      options.copyFrom = arg.slice('--copy-from='.length).trim();
+      continue;
+    }
+    if (arg === '--copy-from') {
+      const next = argv[index + 1];
+      if (!next || next.startsWith('-')) {
+        throw new Error('Missing value for --copy-from.');
+      }
+      options.copyFrom = next.trim();
+      index += 1;
+      continue;
+    }
+    if (arg === '--help' || arg === '-h') {
+      options.help = true;
+      continue;
+    }
+    if (arg.startsWith('-')) {
+      throw new Error(`Unknown option: ${arg}`);
+    }
+    if (options.locale) {
+      throw new Error(`Unexpected positional argument: ${arg}`);
+    }
+    options.locale = arg.trim();
+  }
+
+  return options;
+}
+
+function validateLocaleOrThrow(value, label) {
+  if (!LOCALE_REGEX.test(value)) {
+    throw new Error(`${label} must match ${LOCALE_REGEX}. Received: "${value}"`);
+  }
+}
+
+async function pathExists(targetPath) {
+  try {
+    await fs.access(targetPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function listJsonFiles(folderPath) {
+  const entries = await fs.readdir(folderPath, { withFileTypes: true });
+  return entries
+    .filter((entry) => entry.isFile() && entry.name.endsWith('.json'))
+    .map((entry) => entry.name)
+    .sort((left, right) => left.localeCompare(right));
+}
+
+function runSyncCommand(cwd) {
+  const command = 'pnpm i18n:sync';
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, {
+      cwd,
+      stdio: 'inherit',
+      shell: true,
+    });
+    child.on('error', (error) => reject(error));
+    child.on('exit', (code) => {
+      if (code === 0) {
+        resolve();
+        return;
+      }
+      reject(new Error(`"pnpm i18n:sync" failed with exit code ${code ?? 'unknown'}.`));
+    });
+  });
+}
+
+async function main() {
+  const options = parseArgs(process.argv.slice(2));
+  if (options.help) {
+    printUsage();
+    return;
+  }
+
+  if (!options.locale) {
+    throw new Error('Locale is required.');
+  }
+  validateLocaleOrThrow(options.locale, 'Locale');
+  validateLocaleOrThrow(options.copyFrom, 'copy-from');
+
+  if (options.locale === options.copyFrom) {
+    throw new Error('Locale must be different from --copy-from.');
+  }
+
+  const root = process.cwd();
+  const resourcesRoot = path.join(root, 'resources', 'i18n');
+  const sourceDir = path.join(resourcesRoot, options.copyFrom);
+  const targetDir = path.join(resourcesRoot, options.locale);
+
+  if (!(await pathExists(sourceDir))) {
+    throw new Error(`Source locale folder not found: ${sourceDir}`);
+  }
+
+  const namespaceFiles = await listJsonFiles(sourceDir);
+  if (namespaceFiles.length === 0) {
+    throw new Error(`Source locale folder has no namespace JSON files: ${sourceDir}`);
+  }
+
+  const targetExisted = await pathExists(targetDir);
+  await fs.mkdir(targetDir, { recursive: true });
+
+  const conflictingFiles = [];
+  for (const fileName of namespaceFiles) {
+    const destinationPath = path.join(targetDir, fileName);
+    if (await pathExists(destinationPath)) {
+      conflictingFiles.push(fileName);
+    }
+  }
+
+  if (conflictingFiles.length > 0 && !options.force) {
+    throw new Error(
+      `Target locale already has existing files: ${conflictingFiles.join(', ')}. Use --force to overwrite.`,
+    );
+  }
+
+  const createdFiles = [];
+  for (const fileName of namespaceFiles) {
+    const sourcePath = path.join(sourceDir, fileName);
+    const destinationPath = path.join(targetDir, fileName);
+    let content = '{}\n';
+
+    if (!options.empty) {
+      content = await fs.readFile(sourcePath, 'utf8');
+      if (!content.endsWith('\n')) {
+        content = `${content}\n`;
+      }
+    }
+
+    await fs.writeFile(destinationPath, content, 'utf8');
+    createdFiles.push(fileName);
+  }
+
+  let syncExecuted = false;
+  if (!options.noSync) {
+    await runSyncCommand(root);
+    syncExecuted = true;
+  }
+
+  console.log('i18n locale added successfully.');
+  console.log(`- locale: ${options.locale}`);
+  console.log(`- copy-from: ${options.copyFrom}`);
+  console.log(`- folder: ${path.join('resources', 'i18n', options.locale)} (${targetExisted ? 'existing' : 'created'})`);
+  console.log(`- files: ${createdFiles.length} (${options.empty ? 'empty {}' : 'copied'})`);
+  for (const fileName of createdFiles) {
+    console.log(`  - ${fileName}`);
+  }
+  console.log(`- sync: ${syncExecuted ? 'pnpm i18n:sync executed' : 'skipped (--no-sync)'}`);
+}
+
+main().catch((error) => {
+  console.error(`Error: ${error instanceof Error ? error.message : String(error)}`);
+  printUsage();
+  process.exitCode = 1;
+});

package/templates/docs-fragments/README/40_i18n.md

@@ -6,6 +6,7 @@ Environment keys:
 
 Resources location: `resources/i18n`.
 These dictionaries are shared by backend (`nestjs-i18n`) and frontend (`react-i18next`).
+Default namespaces: `common`, `errors`, `validation`, `ui`, `notifications`, `meta`.
 
 Packages:
 - `@forgeon/i18n`
@@ -22,5 +23,9 @@ Locale/namespace contracts sync:
 Translation key types generation (manual):
 - `pnpm i18n:types`
 
+Add a new language folder:
+- `pnpm i18n:add uk`
+- optional flags: `--copy-from=en` `--empty` `--force` `--no-sync`
+
 You can apply i18n later with:
 `npx create-forgeon@latest add i18n --project .`

package/templates/module-fragments/i18n/10_overview.md

@@ -7,9 +7,11 @@ Included parts:
 - `@forgeon/i18n-contracts` (generated locale/namespace contracts + checks/types scripts)
 - `@forgeon/i18n-web` (React-side locale helpers)
 - `react-i18next` integration for frontend translations
-- shared dictionaries in `resources/i18n/*` (`en`, `uk`) used by both API and web
+- shared dictionaries in `resources/i18n/*` (`en` by default) used by both API and web
+- default namespaces: `common`, `errors`, `validation`, `ui`, `notifications`, `meta`
 
 Utility commands:
 - `pnpm i18n:sync` - regenerate `I18N_LOCALES` and `I18N_NAMESPACES` from `resources/i18n`.
 - `pnpm i18n:check` - verify generated contracts, JSON validity, and missing/extra keys vs fallback locale.
 - `pnpm i18n:types` - generate translation key type unions for autocomplete.
+- `pnpm i18n:add <locale>` - create `resources/i18n/<locale>` from `--copy-from` namespace files.

package/templates/module-presets/i18n/apps/web/src/App.tsx

@@ -10,12 +10,8 @@ type ProbeResult = {
   body: unknown;
 };
 
-function localeLabelKey(locale: I18nLocale): string {
-  return locale === 'uk' ? 'common:languages.ukrainian' : 'common:languages.english';
-}
-
 export default function App() {
-  const { t } = useTranslation(['common']);
+  const { t } = useTranslation(['ui']);
   const { I18N_LOCALES, getInitialLocale, persistLocale, toLangQuery } = i18nWeb;
   const [locale, setLocale] = useState<I18nLocale>(getInitialLocale);
   const [healthResult, setHealthResult] = useState<ProbeResult | null>(null);
@@ -77,7 +73,7 @@ export default function App() {
     <main className="page">
       <h1>Forgeon Fullstack Scaffold</h1>
       <p>Default frontend preset: React + Vite + TypeScript.</p>
-      <label htmlFor="language">{t('common:language')}:</label>
+      <label htmlFor="language">{t('ui:labels.language')}:</label>
       <select
         id="language"
         value={locale}
@@ -85,20 +81,20 @@ export default function App() {
       >
         {I18N_LOCALES.map((item) => (
           <option key={item} value={item}>
-            {t(localeLabelKey(item))}
+            {item}
           </option>
         ))}
       </select>
       <div className="actions">
-        <button onClick={() => runProbe(setHealthResult, '/health')}>{t('common:checkApiHealth')}</button>
+        <button onClick={() => runProbe(setHealthResult, '/health')}>Check API health</button>
         <button onClick={() => runProbe(setErrorProbeResult, '/health/error')}>
-          {t('common:checkErrorEnvelope')}
+          Check error envelope
         </button>
         <button onClick={() => runProbe(setValidationProbeResult, '/health/validation')}>
-          {t('common:checkValidation')}
+          Check validation (expect 400)
         </button>
         <button onClick={() => runProbe(setDbProbeResult, '/health/db', { method: 'POST' })}>
-          {t('common:checkDatabase')}
+          Check database (create user)
         </button>
       </div>
       {renderResult('Health response', healthResult)}

package/templates/module-presets/i18n/apps/web/src/i18n.ts

@@ -3,22 +3,20 @@ import { initReactI18next } from 'react-i18next';
 import { getInitialLocale, I18N_LOCALES, type I18nLocale } from '@forgeon/i18n-web';
 import enCommon from '../../../resources/i18n/en/common.json';
 import enErrors from '../../../resources/i18n/en/errors.json';
+import enMeta from '../../../resources/i18n/en/meta.json';
+import enNotifications from '../../../resources/i18n/en/notifications.json';
+import enUi from '../../../resources/i18n/en/ui.json';
 import enValidation from '../../../resources/i18n/en/validation.json';
-import ukCommon from '../../../resources/i18n/uk/common.json';
-import ukErrors from '../../../resources/i18n/uk/errors.json';
-import ukValidation from '../../../resources/i18n/uk/validation.json';
 
 const resources = {
   en: {
     common: enCommon,
     errors: enErrors,
+    meta: enMeta,
+    notifications: enNotifications,
+    ui: enUi,
     validation: enValidation,
   },
-  uk: {
-    common: ukCommon,
-    errors: ukErrors,
-    validation: ukValidation,
-  },
 } as const;
 
 const fallbackLocale = (I18N_LOCALES[0] ?? 'en') as I18nLocale;

package/templates/module-presets/i18n/packages/i18n-contracts/src/generated-keys.d.ts

@@ -1,11 +1,100 @@
 /* AUTO-GENERATED BY `pnpm i18n:types`. DO NOT EDIT MANUALLY. */
 
 export type I18nTranslationKey =
-  | "common.checkApiHealth"
-  | "common.language"
-  | "common.languages.english"
-  | "common.languages.ukrainian"
-  | "common.ok"
-  | "errors.accessDenied"
-  | "errors.notFound"
-  | "validation.required";
+  | "common.actions.ok"
+  | "common.actions.cancel"
+  | "common.actions.save"
+  | "common.actions.delete"
+  | "common.actions.edit"
+  | "common.actions.create"
+  | "common.actions.update"
+  | "common.actions.confirm"
+  | "common.actions.retry"
+  | "common.nav.back"
+  | "common.nav.next"
+  | "common.nav.close"
+  | "common.state.loading"
+  | "common.state.empty"
+  | "common.state.selected"
+  | "common.status.active"
+  | "common.status.inactive"
+  | "common.status.pending"
+  | "common.status.disabled"
+  | "common.status.archived"
+  | "common.time.today"
+  | "common.time.yesterday"
+  | "common.time.tomorrow"
+  | "common.time.now"
+  | "common.misc.yes"
+  | "common.misc.no"
+  | "common.misc.on"
+  | "common.misc.off"
+  | "errors.http.NOT_FOUND"
+  | "errors.http.BAD_REQUEST"
+  | "errors.http.UNAUTHORIZED"
+  | "errors.http.FORBIDDEN"
+  | "errors.http.CONFLICT"
+  | "errors.http.TOO_MANY_REQUESTS"
+  | "errors.http.METHOD_NOT_ALLOWED"
+  | "errors.http.UNPROCESSABLE_ENTITY"
+  | "errors.http.INTERNAL_ERROR"
+  | "errors.http.SERVICE_UNAVAILABLE"
+  | "errors.http.BAD_GATEWAY"
+  | "errors.http.GATEWAY_TIMEOUT"
+  | "errors.network.NETWORK_ERROR"
+  | "errors.network.TIMEOUT"
+  | "errors.network.OFFLINE"
+  | "errors.auth.AUTH_INVALID_CREDENTIALS"
+  | "errors.auth.AUTH_TOKEN_EXPIRED"
+  | "errors.validation.VALIDATION_ERROR"
+  | "errors.files.UPLOAD_FILE_TOO_LARGE"
+  | "errors.files.UPLOAD_INVALID_TYPE"
+  | "errors.files.UPLOAD_QUOTA_EXCEEDED"
+  | "meta.pages.home.title"
+  | "meta.pages.home.description"
+  | "notifications.success.saved"
+  | "notifications.success.updated"
+  | "notifications.success.deleted"
+  | "notifications.success.copied"
+  | "notifications.error.saveFailed"
+  | "notifications.error.updateFailed"
+  | "notifications.error.deleteFailed"
+  | "notifications.info.changesDiscarded"
+  | "notifications.info.sessionExpired"
+  | "notifications.progress.uploading"
+  | "notifications.progress.processing"
+  | "ui.labels.name"
+  | "ui.labels.email"
+  | "ui.labels.password"
+  | "ui.labels.search"
+  | "ui.labels.language"
+  | "ui.placeholders.email"
+  | "ui.placeholders.search"
+  | "ui.placeholders.password"
+  | "ui.titles.home"
+  | "ui.titles.dashboard"
+  | "ui.titles.settings"
+  | "ui.messages.emptyState"
+  | "ui.messages.noResults"
+  | "ui.table.rowsPerPage"
+  | "ui.table.noData"
+  | "ui.modal.confirmTitle"
+  | "ui.modal.confirmText"
+  | "validation.generic.required"
+  | "validation.generic.invalid"
+  | "validation.generic.outOfRange"
+  | "validation.string.minLength"
+  | "validation.string.maxLength"
+  | "validation.string.pattern"
+  | "validation.number.min"
+  | "validation.number.max"
+  | "validation.number.int"
+  | "validation.format.email"
+  | "validation.format.phone"
+  | "validation.format.url"
+  | "validation.format.uuid"
+  | "validation.date.minDate"
+  | "validation.date.maxDate"
+  | "validation.date.invalidDate"
+  | "validation.file.fileTooLarge"
+  | "validation.file.invalidType";

package/templates/module-presets/i18n/packages/i18n-contracts/src/generated.ts

@@ -1,7 +1,14 @@
 /* AUTO-GENERATED BY `pnpm i18n:sync`. DO NOT EDIT MANUALLY. */
 
-export const I18N_LOCALES = ["en", "uk"] as const;
-export const I18N_NAMESPACES = ["common", "errors", "validation"] as const;
+export const I18N_LOCALES = ["en"] as const;
+export const I18N_NAMESPACES = [
+  "common",
+  "errors",
+  "meta",
+  "notifications",
+  "ui",
+  "validation"
+] as const;
 
 export type I18nLocale = (typeof I18N_LOCALES)[number];
 export type I18nNamespace = (typeof I18N_NAMESPACES)[number];

package/templates/base/resources/i18n/uk/common.json

@@ -1,12 +0,0 @@
-{
-  "ok": "OK",
-  "checkApiHealth": "Перевірити API health",
-  "checkErrorEnvelope": "Перевірити error envelope",
-  "checkValidation": "Перевірити валідацію (очікуємо 400)",
-  "checkDatabase": "Перевірити базу даних (створити користувача)",
-  "language": "Мова",
-  "languages": {
-    "english": "Англійська",
-    "ukrainian": "Українська"
-  }
-}

package/templates/base/resources/i18n/uk/errors.json

@@ -1,4 +0,0 @@
-{
-  "accessDenied": "Доступ заборонено",
-  "notFound": "Ресурс не знайдено"
-}

package/templates/base/resources/i18n/uk/validation.json

@@ -1,3 +0,0 @@
-{
-  "required": "Поле є обов'язковим"
-}