create-forgeon 0.1.26 → 0.1.27

package/package.json

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

package/src/modules/executor.test.mjs

@@ -208,6 +208,10 @@ describe('addModule', () => {
       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/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),
+      i18n: this.translate('common.languages.english', lang),
     };
   }
 
   @Get('error')
-  getErrorProbe() {
+  getErrorProbe(@Query('lang') lang?: string) {
     throw new ConflictException({
-      message: 'Email already exists',
+      message: this.translate('errors.emailAlreadyExists', lang),
       details: {
         feature: 'core-errors',
-        probe: 'health.error',
+        probeId: 'health.error',
+        probe: this.translate('common.probes.error', lang),
       },
     });
   }
 
   @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.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/README.md

@@ -6,3 +6,12 @@
 - `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/resources/i18n/en/common.json

@@ -5,8 +5,10 @@
   "checkValidation": "Check validation (expect 400)",
   "checkDatabase": "Check database (create user)",
   "language": "Language",
+  "probes": {
+    "error": "Error envelope probe"
+  },
   "languages": {
-    "english": "English",
-    "ukrainian": "Ukrainian"
+    "english": "English"
   }
 }

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

@@ -1,4 +1,5 @@
 {
   "accessDenied": "Access denied",
-  "notFound": "Resource not found"
+  "notFound": "Resource not found",
+  "emailAlreadyExists": "Email already exists"
 }

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

@@ -0,0 +1,188 @@
+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 = process.platform === 'win32' ? 'pnpm.cmd' : 'pnpm';
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, ['i18n:sync'], { cwd, stdio: 'inherit' });
+    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

@@ -22,5 +22,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,10 @@ 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
 
 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,10 +10,6 @@ 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 { I18N_LOCALES, getInitialLocale, persistLocale, toLangQuery } = i18nWeb;
@@ -85,7 +81,7 @@ export default function App() {
       >
         {I18N_LOCALES.map((item) => (
           <option key={item} value={item}>
-            {t(localeLabelKey(item))}
+            {t(`common:languages.${item}`, { defaultValue: item })}
           </option>
         ))}
       </select>

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

@@ -4,9 +4,6 @@ import { getInitialLocale, I18N_LOCALES, type I18nLocale } from '@forgeon/i18n-w
 import enCommon from '../../../resources/i18n/en/common.json';
 import enErrors from '../../../resources/i18n/en/errors.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: {
@@ -14,11 +11,6 @@ const resources = {
     errors: enErrors,
     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

@@ -2,10 +2,14 @@
 
 export type I18nTranslationKey =
   | "common.checkApiHealth"
+  | "common.checkDatabase"
+  | "common.checkErrorEnvelope"
+  | "common.checkValidation"
   | "common.language"
   | "common.languages.english"
-  | "common.languages.ukrainian"
   | "common.ok"
+  | "common.probes.error"
   | "errors.accessDenied"
+  | "errors.emailAlreadyExists"
   | "errors.notFound"
   | "validation.required";

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

@@ -1,6 +1,6 @@
 /* AUTO-GENERATED BY `pnpm i18n:sync`. DO NOT EDIT MANUALLY. */
 
-export const I18N_LOCALES = ["en", "uk"] as const;
+export const I18N_LOCALES = ["en"] as const;
 export const I18N_NAMESPACES = ["common", "errors", "validation"] as const;
 
 export type I18nLocale = (typeof I18N_LOCALES)[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": "Поле є обов'язковим"
-}