create-forgeon 0.1.11 → 0.1.13

package/package.json

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

package/src/modules/executor.test.mjs

@@ -104,7 +104,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, /\/api\/health\/meta/);
+      assert.match(appTsx, /react-i18next/);
       assert.match(appTsx, /checkApiHealth/);
 
       const i18nWebPackage = fs.readFileSync(
@@ -123,14 +123,33 @@ describe('addModule', () => {
         path.join(projectRoot, 'packages', 'i18n-web', 'src', 'index.ts'),
         'utf8',
       );
-      assert.match(i18nWebSource, /@forgeon\/i18n-contracts\/src\/index/);
+      assert.match(i18nWebSource, /@forgeon\/i18n-contracts/);
 
       const enCommon = JSON.parse(
         fs.readFileSync(path.join(projectRoot, 'resources', 'i18n', 'en', 'common.json'), 'utf8'),
       );
-      assert.equal(enCommon.common.checkApiHealth, 'Check API health');
+      assert.equal(enCommon.checkApiHealth, 'Check API health');
       assert.equal(enCommon.languages.english, 'English');
 
+      const enErrors = JSON.parse(
+        fs.readFileSync(path.join(projectRoot, 'resources', 'i18n', 'en', 'errors.json'), 'utf8'),
+      );
+      assert.equal(enErrors.notFound, 'Resource not found');
+
+      const webPackage = fs.readFileSync(path.join(projectRoot, 'apps', 'web', 'package.json'), 'utf8');
+      assert.match(webPackage, /"i18next":/);
+      assert.match(webPackage, /"react-i18next":/);
+
+      const mainTsx = fs.readFileSync(path.join(projectRoot, 'apps', 'web', 'src', 'main.tsx'), 'utf8');
+      assert.match(mainTsx, /import '\.\/i18n';/);
+
+      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/);
+
+      const rootPackage = fs.readFileSync(path.join(projectRoot, 'package.json'), 'utf8');
+      assert.match(rootPackage, /"i18n:check"/);
+
       const caddyDockerfile = fs.readFileSync(
         path.join(projectRoot, 'infra', 'docker', 'caddy.Dockerfile'),
         'utf8',
@@ -144,6 +163,7 @@ describe('addModule', () => {
         caddyDockerfile,
         /COPY packages\/i18n-web\/package\.json packages\/i18n-web\/package\.json/,
       );
+      assert.match(caddyDockerfile, /COPY resources resources/);
     } finally {
       fs.rmSync(targetRoot, { recursive: true, force: true });
     }

package/src/modules/i18n.mjs

@@ -166,6 +166,11 @@ function patchProxyDockerfile(filePath) {
     'COPY packages/i18n-contracts packages/i18n-contracts',
     'COPY packages/i18n-web packages/i18n-web',
   );
+  content = ensureLineAfter(
+    content,
+    'COPY packages/i18n-web packages/i18n-web',
+    'COPY resources resources',
+  );
 
   fs.writeFileSync(filePath, `${content.trimEnd()}\n`, 'utf8');
 }
@@ -232,6 +237,8 @@ function patchWebPackage(targetRoot) {
   );
   ensureDependency(packageJson, '@forgeon/i18n-contracts', 'workspace:*');
   ensureDependency(packageJson, '@forgeon/i18n-web', 'workspace:*');
+  ensureDependency(packageJson, 'i18next', '^23.16.8');
+  ensureDependency(packageJson, 'react-i18next', '^15.1.2');
   writeJson(packagePath, packageJson);
 }
 
@@ -246,6 +253,17 @@ function patchI18nPackage(targetRoot) {
   writeJson(packagePath, packageJson);
 }
 
+function patchRootPackage(targetRoot) {
+  const packagePath = path.join(targetRoot, 'package.json');
+  if (!fs.existsSync(packagePath)) {
+    return;
+  }
+
+  const packageJson = JSON.parse(fs.readFileSync(packagePath, 'utf8'));
+  ensureScript(packageJson, 'i18n:check', 'pnpm --filter @forgeon/i18n-contracts check:keys');
+  writeJson(packagePath, packageJson);
+}
+
 export function applyI18nModule({ packageRoot, targetRoot }) {
   copyFromBase(packageRoot, targetRoot, path.join('packages', 'i18n'));
   copyFromBase(packageRoot, targetRoot, path.join('resources', 'i18n'));
@@ -253,6 +271,8 @@ export function applyI18nModule({ packageRoot, targetRoot }) {
   copyFromPreset(packageRoot, targetRoot, path.join('packages', 'i18n-contracts'));
   copyFromPreset(packageRoot, targetRoot, path.join('packages', 'i18n-web'));
   copyFromPreset(packageRoot, targetRoot, path.join('apps', 'web', 'src', 'App.tsx'));
+  copyFromPreset(packageRoot, targetRoot, path.join('apps', 'web', 'src', 'i18n.ts'));
+  copyFromPreset(packageRoot, targetRoot, path.join('apps', 'web', 'src', 'main.tsx'));
 
   copyFromBase(packageRoot, targetRoot, path.join('apps', 'api', 'src', 'app.module.ts'));
   copyFromBase(packageRoot, targetRoot, path.join('apps', 'api', 'src', 'config', 'app.config.ts'));
@@ -270,6 +290,7 @@ export function applyI18nModule({ packageRoot, targetRoot }) {
   patchI18nPackage(targetRoot);
   patchApiPackage(targetRoot);
   patchWebPackage(targetRoot);
+  patchRootPackage(targetRoot);
   patchApiDockerfile(targetRoot);
   patchProxyDockerfiles(targetRoot);
 

package/src/presets/i18n.mjs

@@ -58,7 +58,8 @@ export function applyI18nDisabled(targetRoot) {
       )
       .replace(/^COPY packages\/i18n-web\/package\.json packages\/i18n-web\/package\.json\r?\n/gm, '')
       .replace(/^COPY packages\/i18n-contracts packages\/i18n-contracts\r?\n/gm, '')
-      .replace(/^COPY packages\/i18n-web packages\/i18n-web\r?\n/gm, '');
+      .replace(/^COPY packages\/i18n-web packages\/i18n-web\r?\n/gm, '')
+      .replace(/^COPY resources resources\r?\n/gm, '');
 
     fs.writeFileSync(dockerfilePath, content, 'utf8');
   }
@@ -75,10 +76,21 @@ export function applyI18nDisabled(targetRoot) {
     if (webPackage.dependencies) {
       delete webPackage.dependencies['@forgeon/i18n-contracts'];
       delete webPackage.dependencies['@forgeon/i18n-web'];
+      delete webPackage.dependencies.i18next;
+      delete webPackage.dependencies['react-i18next'];
     }
 
     writeJson(webPackagePath, webPackage);
   }
+
+  const rootPackagePath = path.join(targetRoot, 'package.json');
+  if (fs.existsSync(rootPackagePath)) {
+    const rootPackage = JSON.parse(fs.readFileSync(rootPackagePath, 'utf8'));
+    if (rootPackage.scripts) {
+      delete rootPackage.scripts['i18n:check'];
+    }
+    writeJson(rootPackagePath, rootPackage);
+  }
 
   const appModulePath = path.join(targetRoot, 'apps', 'api', 'src', 'app.module.ts');
   fs.writeFileSync(

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

@@ -16,26 +16,18 @@ export class HealthController {
     };
   }
 
-  @Get('meta')
-  getMeta(@Query('lang') lang?: string) {
-    return {
-      checkApiHealth: this.translate('common.checkApiHealth', lang),
-      languageLabel: this.translate('common.language', lang),
-    };
-  }
-
   @Get('echo')
   getEcho(@Query() query: EchoQueryDto) {
     return { value: query.value };
   }
 
   private translate(key: string, lang?: string): string {
-    if (!this.i18n) {
+    if (!this.i18n) {
       if (key === 'common.ok') return 'OK';
       if (key === 'common.checkApiHealth') return 'Check API health';
       if (key === 'common.language') return 'Language';
-      if (key === 'languages.english') return 'English';
-      if (key === 'languages.ukrainian') return 'Ukrainian';
+      if (key === 'common.languages.english') return 'English';
+      if (key === 'common.languages.ukrainian') return 'Ukrainian';
       return key;
     }
 
@@ -52,6 +44,6 @@ export class HealthController {
   }
 
   private localeNameKey(locale: 'en' | 'uk'): string {
-    return locale === 'uk' ? 'languages.ukrainian' : 'languages.english';
+    return locale === 'uk' ? 'common.languages.ukrainian' : 'common.languages.english';
   }
 }

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

@@ -1,13 +1,7 @@
 {
-  "errors": {
-    "accessDenied": "Access denied",
-    "notFound": "Resource not found"
-  },
-  "common": {
-    "ok": "OK",
-    "checkApiHealth": "Check API health",
-    "language": "Language"
-  },
+  "ok": "OK",
+  "checkApiHealth": "Check API health",
+  "language": "Language",
   "languages": {
     "english": "English",
     "ukrainian": "Ukrainian"

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

@@ -0,0 +1,4 @@
+{
+  "accessDenied": "Access denied",
+  "notFound": "Resource not found"
+}

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

@@ -1,5 +1,3 @@
 {
-  "validation": {
-    "required": "Field is required"
-  }
+  "required": "Field is required"
 }

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

@@ -1,13 +1,7 @@
 {
-  "errors": {
-    "accessDenied": "Доступ заборонено",
-    "notFound": "Ресурс не знайдено"
-  },
-  "common": {
-    "ok": "OK",
-    "checkApiHealth": "Перевірити API health",
-    "language": "Мова"
-  },
+  "ok": "OK",
+  "checkApiHealth": "Перевірити API health",
+  "language": "Мова",
   "languages": {
     "english": "Англійська",
     "ukrainian": "Українська"

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

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

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

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

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

@@ -6,11 +6,16 @@ Environment keys:
 - `I18N_FALLBACK_LANG=en`
 
 Resources location: `resources/i18n`.
+These dictionaries are shared by backend (`nestjs-i18n`) and frontend (`react-i18next`).
 
 Packages:
 - `@forgeon/i18n`
 - `@forgeon/i18n-contracts`
 - `@forgeon/i18n-web`
+- `react-i18next`
+
+Dictionary key validation:
+- `pnpm i18n:check`
 
 You can apply i18n later with:
 `npx create-forgeon@latest add i18n --project .`

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

@@ -4,6 +4,7 @@ Adds optional i18n support across backend and frontend.
 
 Included parts:
 - `@forgeon/i18n` (NestJS i18n integration package)
-- `@forgeon/i18n-contracts` (shared locale/query constants)
+- `@forgeon/i18n-contracts` (shared locale/query constants and key checks)
 - `@forgeon/i18n-web` (React-side locale helpers)
-- `resources/i18n/*` dictionaries (`en`, `uk`)
+- `react-i18next` integration for frontend translations
+- shared dictionaries in `resources/i18n/*` (`en`, `uk`) used by both API and web

package/templates/module-fragments/i18n/20_scope.md

@@ -3,5 +3,7 @@
 - API module wiring (`AppModule`, config, filter, health endpoint translation)
 - API package/deps/scripts updates
 - Docker env + compose i18n env keys
-- Frontend language selector in `apps/web/src/App.tsx`
+- Frontend `react-i18next` setup (`apps/web/src/i18n.ts`)
+- Frontend language selector and translated UI in `apps/web/src/App.tsx`
 - Frontend package/deps/scripts updates for i18n helpers
+- Root script `i18n:check` for dictionary key consistency across locales

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

@@ -1,4 +1,6 @@
-import { useEffect, useState } from 'react';
+import { useState } from 'react';
+import { useTranslation } from 'react-i18next';
+import i18n from './i18n';
 import * as i18nWeb from '@forgeon/i18n-web';
 import type { I18nLocale } from '@forgeon/i18n-web';
 import './styles.css';
@@ -9,47 +11,23 @@ type HealthResponse = {
   i18n: string;
 };
 
-type HealthMetaResponse = {
-  checkApiHealth: string;
-  languageLabel: string;
-};
+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;
   const [locale, setLocale] = useState<I18nLocale>(getInitialLocale);
   const [data, setData] = useState<HealthResponse | null>(null);
   const [error, setError] = useState<string | null>(null);
-  const [labels, setLabels] = useState<HealthMetaResponse>({
-    checkApiHealth: 'Check API health',
-    languageLabel: 'Language',
-  });
 
   const changeLocale = (nextLocale: I18nLocale) => {
     setLocale(nextLocale);
     persistLocale(nextLocale);
+    void i18n.changeLanguage(nextLocale);
   };
 
-  useEffect(() => {
-    const loadLabels = async () => {
-      try {
-        const response = await fetch(`/api/health/meta${toLangQuery(locale)}`, {
-          headers: {
-            'Accept-Language': locale,
-          },
-        });
-        if (!response.ok) {
-          return;
-        }
-        const payload = (await response.json()) as HealthMetaResponse;
-        setLabels(payload);
-      } catch {
-        // Keep fallback labels if meta request fails.
-      }
-    };
-
-    void loadLabels();
-  }, [locale, toLangQuery]);
-
   const checkApi = async () => {
     setError(null);
     try {
@@ -72,7 +50,7 @@ export default function App() {
     <main className="page">
       <h1>Forgeon Fullstack Scaffold</h1>
       <p>Default frontend preset: React + Vite + TypeScript.</p>
-      <label htmlFor="language">{labels.languageLabel}:</label>
+      <label htmlFor="language">{t('common:language')}:</label>
       <select
         id="language"
         value={locale}
@@ -80,11 +58,11 @@ export default function App() {
       >
         {I18N_LOCALES.map((item) => (
           <option key={item} value={item}>
-            {item}
+            {t(localeLabelKey(item))}
           </option>
         ))}
       </select>
-      <button onClick={checkApi}>{labels.checkApiHealth}</button>
+      <button onClick={checkApi}>{t('common:checkApiHealth')}</button>
       {data ? <pre>{JSON.stringify(data, null, 2)}</pre> : null}
       {error ? <p className="error">{error}</p> : null}
     </main>

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

@@ -0,0 +1,35 @@
+import i18n from 'i18next';
+import { initReactI18next } from 'react-i18next';
+import { I18N_DEFAULT_LANG } from '@forgeon/i18n-contracts';
+import { getInitialLocale } from '@forgeon/i18n-web';
+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: {
+    common: enCommon,
+    errors: enErrors,
+    validation: enValidation,
+  },
+  uk: {
+    common: ukCommon,
+    errors: ukErrors,
+    validation: ukValidation,
+  },
+} as const;
+
+void i18n.use(initReactI18next).init({
+  resources,
+  lng: getInitialLocale(),
+  fallbackLng: I18N_DEFAULT_LANG,
+  interpolation: {
+    escapeValue: false,
+  },
+  defaultNS: 'common',
+});
+
+export default i18n;

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

@@ -0,0 +1,10 @@
+import React from 'react';
+import ReactDOM from 'react-dom/client';
+import './i18n';
+import App from './App';
+
+ReactDOM.createRoot(document.getElementById('root')!).render(
+  <React.StrictMode>
+    <App />
+  </React.StrictMode>,
+);

package/templates/module-presets/i18n/packages/i18n-contracts/package.json

@@ -5,7 +5,8 @@
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "scripts": {
-    "build": "tsc -p tsconfig.json"
+    "build": "tsc -p tsconfig.json",
+    "check:keys": "node scripts/check-keys.mjs"
   },
   "devDependencies": {
     "@types/node": "^22.10.7",

package/templates/module-presets/i18n/packages/i18n-contracts/scripts/check-keys.mjs

@@ -0,0 +1,97 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const projectRoot = path.resolve(__dirname, '..', '..', '..');
+const resourcesRoot = path.join(projectRoot, 'resources', 'i18n');
+const baseLocale = 'en';
+
+function readJson(filePath) {
+  return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+}
+
+function flattenKeys(value, prefix = '') {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    return prefix ? [prefix] : [];
+  }
+
+  const entries = Object.entries(value);
+  if (entries.length === 0) {
+    return prefix ? [prefix] : [];
+  }
+
+  const result = [];
+  for (const [key, nested] of entries) {
+    const nextPrefix = prefix ? `${prefix}.${key}` : key;
+    result.push(...flattenKeys(nested, nextPrefix));
+  }
+  return result;
+}
+
+function sorted(array) {
+  return [...array].sort((a, b) => a.localeCompare(b));
+}
+
+function main() {
+  if (!fs.existsSync(resourcesRoot)) {
+    console.error(`Missing resources folder: ${resourcesRoot}`);
+    process.exit(1);
+  }
+
+  const localeDirs = fs
+    .readdirSync(resourcesRoot, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name);
+
+  if (!localeDirs.includes(baseLocale)) {
+    console.error(`Missing base locale "${baseLocale}" in ${resourcesRoot}`);
+    process.exit(1);
+  }
+
+  const baseLocaleDir = path.join(resourcesRoot, baseLocale);
+  const baseFiles = fs
+    .readdirSync(baseLocaleDir)
+    .filter((name) => name.endsWith('.json'));
+
+  const errors = [];
+
+  for (const locale of localeDirs) {
+    const localeDir = path.join(resourcesRoot, locale);
+    for (const fileName of baseFiles) {
+      const baseFilePath = path.join(baseLocaleDir, fileName);
+      const localeFilePath = path.join(localeDir, fileName);
+
+      if (!fs.existsSync(localeFilePath)) {
+        errors.push(`[${locale}] missing file: ${fileName}`);
+        continue;
+      }
+
+      const baseKeys = sorted(flattenKeys(readJson(baseFilePath)));
+      const localeKeys = sorted(flattenKeys(readJson(localeFilePath)));
+
+      const missingKeys = baseKeys.filter((key) => !localeKeys.includes(key));
+      const extraKeys = localeKeys.filter((key) => !baseKeys.includes(key));
+
+      for (const key of missingKeys) {
+        errors.push(`[${locale}] missing key in ${fileName}: ${key}`);
+      }
+      for (const key of extraKeys) {
+        errors.push(`[${locale}] extra key in ${fileName}: ${key}`);
+      }
+    }
+  }
+
+  if (errors.length > 0) {
+    console.error('i18n key check failed:');
+    for (const error of errors) {
+      console.error(`- ${error}`);
+    }
+    process.exit(1);
+  }
+
+  console.log('i18n key check passed.');
+}
+
+main();

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

@@ -1,6 +1,8 @@
 export const I18N_LOCALES = ['en', 'uk'] as const;
+export const I18N_NAMESPACES = ['common', 'errors', 'validation'] as const;
 
 export type I18nLocale = (typeof I18N_LOCALES)[number];
+export type I18nNamespace = (typeof I18N_NAMESPACES)[number];
 
 export const I18N_DEFAULT_LANG: I18nLocale = 'en';
 export const I18N_FALLBACK_LANG: I18nLocale = 'en';

package/templates/module-presets/i18n/packages/i18n-web/src/index.ts

@@ -3,7 +3,7 @@ import {
   I18N_LOCALES,
   LANG_QUERY_PARAM,
   type I18nLocale,
-} from '@forgeon/i18n-contracts/src/index';
+} from '@forgeon/i18n-contracts';
 
 const LOCALE_STORAGE_KEY = 'forgeon.locale';