@bleedingdev/modern-js-create 3.2.0-ultramodern.11 → 3.2.0-ultramodern.12

package/dist/index.js

@@ -561,8 +561,10 @@ const TYPESCRIPT_NATIVE_PREVIEW_VERSION = '7.0.0-dev.20260518.1';
 const OXLINT_VERSION = '1.65.0';
 const OXFMT_VERSION = '0.50.0';
 const ULTRACITE_VERSION = '7.7.0';
+const I18NEXT_VERSION = '26.2.0';
 const REACT_VERSION = '^19.2.6';
 const REACT_DOM_VERSION = '^19.2.6';
+const REACT_I18NEXT_VERSION = '17.0.8';
 const WORKSPACE_PACKAGE_VERSION = 'workspace:*';
 const RSTACK_AGENT_SKILLS_COMMIT = '61c948b42512e223bad44b83af4080eba48b2677';
 const baselineAgentSkills = [
@@ -585,6 +587,7 @@ const effectTsgoTypecheckCommand = "node -e \"const fs = require('node:fs'); con
 const modernPackageNames = [
     '@modern-js/app-tools',
     '@modern-js/plugin-bff',
+    '@modern-js/plugin-i18n',
     '@modern-js/plugin-tanstack',
     '@modern-js/runtime'
 ];
@@ -917,6 +920,7 @@ function modernPackageSpecifier(packageName, packageSource) {
 }
 function appDependencies(scope, packageSource) {
     return {
+        '@modern-js/plugin-i18n': modernPackageSpecifier('@modern-js/plugin-i18n', packageSource),
         '@modern-js/plugin-tanstack': modernPackageSpecifier('@modern-js/plugin-tanstack', packageSource),
         '@modern-js/runtime': modernPackageSpecifier('@modern-js/runtime', packageSource),
         '@module-federation/modern-js-v3': MODULE_FEDERATION_VERSION,
@@ -924,8 +928,10 @@ function appDependencies(scope, packageSource) {
         '@tanstack/react-router': TANSTACK_ROUTER_VERSION,
         [ultramodern_workspace_packageName(scope, 'shared-contracts')]: WORKSPACE_PACKAGE_VERSION,
         [ultramodern_workspace_packageName(scope, 'shared-design-tokens')]: WORKSPACE_PACKAGE_VERSION,
+        i18next: I18NEXT_VERSION,
         react: REACT_VERSION,
-        'react-dom': REACT_DOM_VERSION
+        'react-dom': REACT_DOM_VERSION,
+        'react-i18next': REACT_I18NEXT_VERSION
     };
 }
 function appDevDependencies(packageSource) {
@@ -955,13 +961,14 @@ function createRootPackageJson(scope, packageSource) {
             build: 'pnpm -r --filter ./apps/** --filter ./services/** build',
             format: 'oxfmt .',
             'format:check': 'oxfmt --check .',
+            'i18n:check': "node ./scripts/check-i18n-strings.mjs",
             lint: 'oxlint .',
             'lint:fix': 'oxlint . --fix',
             typecheck: `pnpm -r --filter "@${scope}/*" typecheck`,
             'skills:install': "node ./scripts/bootstrap-agent-skills.mjs",
             'skills:check': "node ./scripts/bootstrap-agent-skills.mjs --check",
             'ultramodern:check': "node ./scripts/validate-ultramodern-workspace.mjs",
-            check: 'pnpm format:check && pnpm lint && pnpm typecheck && pnpm skills:check && pnpm ultramodern:check'
+            check: 'pnpm format:check && pnpm lint && pnpm typecheck && pnpm i18n:check && pnpm skills:check && pnpm ultramodern:check'
         },
         engines: {
             node: '>=20',
@@ -1126,6 +1133,7 @@ function createSharedPackage(scope, id, description) {
 function createAppModernConfig(app) {
     return `// @effect-diagnostics processEnv:off
 import { appTools, defineConfig, presetUltramodern } from '@modern-js/app-tools';
+import { i18nPlugin } from '@modern-js/plugin-i18n';
 import { tanstackRouterPlugin } from '@modern-js/plugin-tanstack';
 import { moduleFederationPlugin } from '@module-federation/modern-js-v3';
 
@@ -1140,7 +1148,17 @@ export default defineConfig(
         polyfill: 'off',
         splitRouteChunks: false,
       },
-      plugins: [appTools(), tanstackRouterPlugin(), moduleFederationPlugin()],
+      plugins: [
+        appTools(),
+        i18nPlugin({
+          localeDetection: {
+            fallbackLanguage: 'en',
+            languages: ['en', 'cs'],
+          },
+        }),
+        tanstackRouterPlugin(),
+        moduleFederationPlugin(),
+      ],
       server: {
         port,
         ssr: {
@@ -1172,6 +1190,11 @@ function createSharedModuleFederationConfig() {
       singleton: true,
       treeShaking: false,
     },
+    i18next: {
+      requiredVersion: dependencies.i18next,
+      singleton: true,
+      treeShaking: false,
+    },
     react: {
       requiredVersion: reactVersion,
       singleton: true,
@@ -1182,6 +1205,11 @@ function createSharedModuleFederationConfig() {
       singleton: true,
       treeShaking: false,
     },
+    'react-i18next': {
+      requiredVersion: dependencies['react-i18next'],
+      singleton: true,
+      treeShaking: false,
+    },
   }`;
 }
 function formatTsObjectLiteral(value) {
@@ -1277,17 +1305,64 @@ export default defineConfig(
 );
 `;
 }
+function createAppRuntimeConfig() {
+    return `import { defineRuntimeConfig } from '@modern-js/runtime';
+import { createInstance } from 'i18next';
+
+const i18nInstance = createInstance();
+
+export default defineRuntimeConfig({
+  i18n: {
+    i18nInstance,
+    initOptions: {
+      defaultNS: 'translation',
+      fallbackLng: 'en',
+      interpolation: {
+        escapeValue: false,
+      },
+      ns: ['translation'],
+      supportedLngs: ['en', 'cs'],
+    },
+  },
+  router: {
+    framework: 'tanstack',
+  },
+});
+`;
+}
 function createShellPage() {
-    return `const remotes = ['remote-commerce', 'remote-identity', 'remote-design-system'];
+    return `import { useModernI18n } from '@modern-js/plugin-i18n/runtime';
+import { useTranslation } from 'react-i18next';
+
+const remotes = ['remote-commerce', 'remote-identity', 'remote-design-system'];
 
 export default function ShellHome() {
+  const { t } = useTranslation();
+  const { changeLanguage, language } = useModernI18n();
+  const languageOptions = [
+    { code: 'en', label: t('language.en') },
+    { code: 'cs', label: t('language.cs') },
+  ];
+
   return (
     <main>
-      <h1>UltraModern SuperApp Shell</h1>
-      <p data-testid="ultramodern-preset">presetUltramodern workspace</p>
+      <nav aria-label={t('language.switcher')}>
+        {languageOptions.map((option) => (
+          <button
+            disabled={language === option.code}
+            key={option.code}
+            onClick={() => void changeLanguage(option.code)}
+            type="button"
+          >
+            {option.label}
+          </button>
+        ))}
+      </nav>
+      <h1>{t('shell.title')}</h1>
+      <p data-testid="ultramodern-preset">{t('shell.preset')}</p>
       <ul>
         {remotes.map((remote) => (
-          <li key={remote}>{remote}</li>
+          <li key={remote}>{t(\`shell.remotes.\${remote}\`)}</li>
         ))}
       </ul>
     </main>
@@ -1296,11 +1371,15 @@ export default function ShellHome() {
 `;
 }
 function createRemotePage(app) {
-    return `export default function ${toPascalCase(app.id)}Home() {
+    return `import { useTranslation } from 'react-i18next';
+
+export default function ${toPascalCase(app.id)}Home() {
+  const { t } = useTranslation();
+
   return (
     <main>
-      <h1>${app.displayName}</h1>
-      <p data-mf-role="${app.kind}">${app.domain ?? app.kind}</p>
+      <h1>{t('remote.title')}</h1>
+      <p data-mf-role="${app.kind}">{t('remote.domain')}</p>
     </main>
   );
 }
@@ -1321,11 +1400,15 @@ function createRemoteEntry(app) {
 }
 function createRemoteWidget(app) {
     const componentName = 'remote-identity' === app.id ? 'IdentityWidget' : 'CommerceWidget';
-    return `export default function ${componentName}() {
+    return `import { useTranslation } from 'react-i18next';
+
+export default function ${componentName}() {
+  const { t } = useTranslation();
+
   return (
     <section data-mf-remote="${app.id}">
-      <h2>${app.displayName}</h2>
-      <p>Owns the ${app.domain} vertical route surface.</p>
+      <h2>{t('remote.widget.title')}</h2>
+      <p>{t('remote.widget.body')}</p>
     </section>
   );
 }
@@ -1334,7 +1417,7 @@ function createRemoteWidget(app) {
 function createDesignButton() {
     return `import { designTokens } from '../tokens';
 
-export default function Button({ label = 'Design System Button' }: { label?: string }) {
+export default function Button({ label }: { label: string }) {
   return (
     <button
       type="button"
@@ -1361,6 +1444,62 @@ function createDesignTokens() {
 } as const;
 `;
 }
+function createEnglishTranslations(app) {
+    if ('shell' === app.kind) return {
+        language: {
+            cs: 'Czech',
+            en: 'English',
+            switcher: 'Language'
+        },
+        shell: {
+            preset: 'presetUltramodern workspace',
+            remotes: {
+                'remote-commerce': 'Commerce Remote',
+                'remote-design-system': 'Design System Remote',
+                'remote-identity': 'Identity Remote'
+            },
+            title: 'UltraModern SuperApp Shell'
+        }
+    };
+    return {
+        remote: {
+            domain: app.domain ?? app.kind,
+            title: app.displayName,
+            widget: {
+                body: 'vertical' === app.kind ? `Owns the ${app.domain} vertical route surface.` : 'Provides shared UI primitives for the workspace.',
+                title: app.displayName
+            }
+        }
+    };
+}
+function createCzechTranslations(app) {
+    if ('shell' === app.kind) return {
+        language: {
+            cs: 'Cestina',
+            en: 'Anglictina',
+            switcher: 'Jazyk'
+        },
+        shell: {
+            preset: 'presetUltramodern workspace',
+            remotes: {
+                'remote-commerce': 'Commerce remote',
+                'remote-design-system': 'Design system remote',
+                'remote-identity': 'Identity remote'
+            },
+            title: 'UltraModern SuperApp shell'
+        }
+    };
+    return {
+        remote: {
+            domain: app.domain ?? app.kind,
+            title: app.displayName,
+            widget: {
+                body: 'vertical' === app.kind ? `Vlastni ${app.domain} vertical route surface.` : 'Poskytuje sdilene UI prvky pro workspace.',
+                title: app.displayName
+            }
+        }
+    };
+}
 function createEffectSharedApi() {
     return `import {
   HttpApi,
@@ -1700,6 +1839,9 @@ function writeApp(targetDir, scope, app, packageSource) {
     writeJson(targetDir, `${app.directory}/tsconfig.json`, createPackageTsConfig(app.directory));
     writeFile(targetDir, `${app.directory}/src/modern-app-env.d.ts`, "/// <reference types='@modern-js/app-tools/types' />\n");
     writeFile(targetDir, `${app.directory}/modern.config.ts`, createAppModernConfig(app));
+    writeFile(targetDir, `${app.directory}/src/modern.runtime.ts`, createAppRuntimeConfig());
+    writeJson(targetDir, `${app.directory}/config/public/locales/en/translation.json`, createEnglishTranslations(app));
+    writeJson(targetDir, `${app.directory}/config/public/locales/cs/translation.json`, createCzechTranslations(app));
     writeFile(targetDir, `${app.directory}/module-federation.config.ts`, 'shell' === app.kind ? createShellModuleFederationConfig() : createRemoteModuleFederationConfig(app));
     writeFile(targetDir, `${app.directory}/src/routes/layout.tsx`, createLayout(app.id));
     writeFile(targetDir, `${app.directory}/src/routes/page.tsx`, 'shell' === app.kind ? createShellPage() : createRemotePage(app));
@@ -1855,7 +1997,7 @@ function detectBffRuntime() {
     process.exit(1);
 }
 function src_renderTemplate(template, data) {
-    const tagRegex = /\{\{(#if|#unless|\/if|\/unless)(?:\s+(\w+))?\}\}/g;
+    const tagRegex = /\{\{(~?)(#if|#unless|\/if|\/unless)(?:\s+(\w+))?(~?)\}\}/g;
     function renderConditionals(startIndex, expectedClose) {
         let rendered = '';
         let cursor = startIndex;
@@ -1866,7 +2008,7 @@ function src_renderTemplate(template, data) {
                 rendered: rendered + template.slice(cursor),
                 nextIndex: template.length
             };
-            const [raw, tag, condition] = match;
+            const [raw, , tag, condition, rightTrim] = match;
             const tagIndex = match.index;
             rendered += template.slice(cursor, tagIndex);
             cursor = tagIndex + raw.length;
@@ -1882,10 +2024,17 @@ function src_renderTemplate(template, data) {
             }
             if ('/if' === tag || '/unless' === tag) {
                 const kind = '/if' === tag ? 'if' : 'unless';
-                if (expectedClose === kind) return {
-                    rendered,
-                    nextIndex: cursor
-                };
+                if (expectedClose === kind) {
+                    let nextIndex = cursor;
+                    if ('~' === rightTrim) {
+                        const trailingWhitespace = /^\s*/u.exec(template.slice(nextIndex));
+                        nextIndex += trailingWhitespace?.[0].length ?? 0;
+                    }
+                    return {
+                        rendered,
+                        nextIndex
+                    };
+                }
                 rendered += raw;
             }
         }
@@ -1974,6 +2123,7 @@ function createBuiltinTemplateManifest(version) {
                 'AGENTS.md',
                 'README.md',
                 'api/**',
+                'config/**',
                 'modern.config.ts',
                 'oxfmt.config.ts',
                 'oxlint.config.ts',
@@ -2368,6 +2518,7 @@ async function main() {
         tsconfigVersion: singleAppModernPackageSpecifier('@modern-js/tsconfig', packageSource, useWorkspaceProtocol),
         pluginTanstackVersion: singleAppModernPackageSpecifier('@modern-js/plugin-tanstack', packageSource, useWorkspaceProtocol),
         pluginBffVersion: singleAppModernPackageSpecifier('@modern-js/plugin-bff', packageSource, useWorkspaceProtocol),
+        pluginI18nVersion: singleAppModernPackageSpecifier('@modern-js/plugin-i18n', packageSource, useWorkspaceProtocol),
         isSubproject,
         routerFramework,
         bffRuntime,
@@ -2447,6 +2598,7 @@ function copyTemplate(src, dest, options) {
                     tsconfigVersion: options.tsconfigVersion,
                     pluginTanstackVersion: options.pluginTanstackVersion,
                     pluginBffVersion: options.pluginBffVersion,
+                    pluginI18nVersion: options.pluginI18nVersion,
                     isSubproject: options.isSubproject,
                     isTanstackRouter: 'tanstack' === options.routerFramework,
                     enableBff: 'none' !== options.bffRuntime,

package/package.json

@@ -21,7 +21,7 @@
   "engines": {
     "node": ">=20"
   },
-  "version": "3.2.0-ultramodern.11",
+  "version": "3.2.0-ultramodern.12",
   "types": "./dist/types/index.d.ts",
   "main": "./dist/index.js",
   "bin": {
@@ -41,7 +41,7 @@
     "@types/node": "^25.8.0",
     "@typescript/native-preview": "7.0.0-dev.20260516.1",
     "tsx": "^4.22.0",
-    "@modern-js/i18n-utils": "npm:@bleedingdev/modern-js-i18n-utils@3.2.0-ultramodern.11"
+    "@modern-js/i18n-utils": "npm:@bleedingdev/modern-js-i18n-utils@3.2.0-ultramodern.12"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
@@ -54,6 +54,6 @@
     "start": "node ./dist/index.js"
   },
   "ultramodern": {
-    "frameworkVersion": "3.2.0-ultramodern.11"
+    "frameworkVersion": "3.2.0-ultramodern.12"
   }
 }

package/template/AGENTS.md

@@ -7,8 +7,13 @@ This project is generated for Codex-first UltraModern.js work.
 - `pnpm lint` runs Oxlint with the Ultracite preset.
 - `pnpm format` runs oxfmt.
 - `pnpm typecheck` runs effect-tsgo as the TypeScript checker.
+- `pnpm i18n:check` rejects hardcoded user-visible JSX text.
 - `pnpm ultramodern:check` verifies the generated contract.
 
+## Internationalization
+
+Runtime i18n is enabled by default. Agents must put user-visible UI copy in `config/public/locales/<lang>/translation.json` and render it through `react-i18next` or `@modern-js/plugin-i18n/runtime`. Do not add hardcoded JSX text, `aria-label`, `title`, `alt`, or `placeholder` strings unless the value is a non-translatable technical token.
+
 ## Private Skills
 
 Private orchestration skills are not vendored into this template. If you are authorized for `TechsioCZ/skills`, run:

package/template/config/public/locales/cs/translation.json

@@ -0,0 +1,39 @@
+{
+  "home": {
+    "bff": {
+      "response": "Odpoved Effect HttpApi:"
+    },
+    "cards": {
+      "bff": {
+        "body": "Pouzivej Effect jako hlavni BFF cestu, Hono nech jako explicitni zalozni volbu.",
+        "title": "BFF + Effect"
+      },
+      "config": {
+        "body": "Upravuj vygenerovane vychozi hodnoty v modern.config.ts.",
+        "title": "Konfigurace presetUltramodern"
+      },
+      "gates": {
+        "body": "Starter obsahuje PR workflow pro ultramodern:check a build.",
+        "title": "Ultramodern kontroly"
+      },
+      "guide": {
+        "body": "Projdi si verejny preset pripraveny pro MV, TanStack a Effect.",
+        "title": "UltraModern.js pruvodce"
+      }
+    },
+    "description": {
+      "afterConfig": ", udrzuj",
+      "afterPreset": "profil. Zacni v",
+      "end": "zelene a lad vygenerovany preset jen tam, kde aplikace potrebuje mekci cestu.",
+      "intro": "Tento starter prinasi verejny"
+    },
+    "language": {
+      "cs": "Cestina",
+      "en": "Anglictina",
+      "switcher": "Jazyk"
+    },
+    "logoAlt": "Logo UltraModern.js",
+    "name": "presetUltramodern",
+    "title": "UltraModern.js 3.0"
+  }
+}

package/template/config/public/locales/en/translation.json

@@ -0,0 +1,39 @@
+{
+  "home": {
+    "bff": {
+      "response": "Effect HttpApi response:"
+    },
+    "cards": {
+      "bff": {
+        "body": "Keep Effect as the preferred BFF lane while Hono stays an explicit fallback.",
+        "title": "BFF + Effect"
+      },
+      "config": {
+        "body": "Tune the generated defaults in modern.config.ts.",
+        "title": "Configure presetUltramodern"
+      },
+      "gates": {
+        "body": "The starter includes a PR workflow for ultramodern:check and build.",
+        "title": "Ultramodern Gates"
+      },
+      "guide": {
+        "body": "Review the MV-first, TanStack-ready, Effect-ready public preset.",
+        "title": "UltraModern.js Guide"
+      }
+    },
+    "description": {
+      "afterConfig": ", keep",
+      "afterPreset": "profile. Start in",
+      "end": "green, and tune the generated preset only where your app needs a softer lane.",
+      "intro": "This starter ships the public"
+    },
+    "language": {
+      "cs": "Czech",
+      "en": "English",
+      "switcher": "Language"
+    },
+    "logoAlt": "UltraModern.js Logo",
+    "name": "presetUltramodern",
+    "title": "UltraModern.js 3.0"
+  }
+}

package/template/modern.config.ts.handlebars

@@ -2,7 +2,8 @@
 import { appTools, defineConfig, presetUltramodern } from '@modern-js/app-tools';
 import path from 'node:path';
 {{#if enableBff}}import { bffPlugin } from '@modern-js/plugin-bff';
-{{/if}}{{#if isTanstackRouter}}import { tanstackRouterPlugin } from '@modern-js/plugin-tanstack';
+{{/if}}import { i18nPlugin } from '@modern-js/plugin-i18n';
+{{#if isTanstackRouter}}import { tanstackRouterPlugin } from '@modern-js/plugin-tanstack';
 {{/if}}
 const appId = process.env['MODERN_BASELINE_APP_ID'] || path.basename(process.cwd());
 const enableModuleFederationSSR = process.env['MODERN_BASELINE_ENABLE_MF_SSR'] !== 'false';
@@ -27,6 +28,12 @@ export default defineConfig(
 
 {{/if}}      plugins: [
         appTools(),
+        i18nPlugin({
+          localeDetection: {
+            fallbackLanguage: 'en',
+            languages: ['en', 'cs'],
+          },
+        }),
 {{#if isTanstackRouter}}
         tanstackRouterPlugin(),
 {{/if}}{{#if enableBff}}

package/template/package.json.handlebars

@@ -8,9 +8,10 @@
     "build": "modern build",
     "serve": "modern serve",
     "typecheck": "node -e \"const fs = require('node:fs'); const { execFileSync, spawnSync } = require('node:child_process'); const bin = execFileSync('effect-tsgo', ['get-exe-path'], { encoding: 'utf8' }).trim(); if (process.platform !== 'win32') fs.chmodSync(bin, 0o755); const result = spawnSync(bin, ['--noEmit', '-p', 'tsconfig.json'], { stdio: 'inherit' }); process.exit(result.status ?? 1);\"",
+    "i18n:check": "node ./scripts/check-i18n-strings.mjs",
     "skills:install": "node ./scripts/bootstrap-agent-skills.mjs",
     "skills:check": "node ./scripts/bootstrap-agent-skills.mjs --check",
-    "ultramodern:check": "{{#unless isSubproject}}pnpm format:check && pnpm lint && {{/unless}}pnpm typecheck{{#unless isSubproject}} && pnpm skills:check{{/unless}} && node ./scripts/validate-ultramodern.mjs"{{#unless isSubproject}},
+    "ultramodern:check": "{{#unless isSubproject}}pnpm format:check && pnpm lint && {{/unless}}pnpm typecheck && pnpm i18n:check{{#unless isSubproject}} && pnpm skills:check{{/unless}} && node ./scripts/validate-ultramodern.mjs"{{#unless isSubproject}},
     "format": "oxfmt .",
     "format:check": "oxfmt --check .",
     "lint": "oxlint .",
@@ -18,12 +19,16 @@
     "prepare": "simple-git-hooks"{{/unless}}
   },
   "dependencies": {
+    "@modern-js/plugin-i18n": "{{pluginI18nVersion}}",
 {{#if isTanstackRouter}}    "@modern-js/plugin-tanstack": "{{pluginTanstackVersion}}",
-{{/if}}    "@modern-js/runtime": "{{runtimeVersion}}",
+{{/if}}
+    "@modern-js/runtime": "{{runtimeVersion}}",
 {{#if isTanstackRouter}}    "@tanstack/react-router": "1.170.1",
 {{/if}}
+    "i18next": "26.2.0",
     "react": "^19.2.3",
-    "react-dom": "^19.2.0"
+    "react-dom": "^19.2.0",
+    "react-i18next": "17.0.8"
   },
   "devDependencies": {
     "@effect/tsgo": "0.7.3",

package/template/scripts/check-i18n-strings.mjs

@@ -0,0 +1,83 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+const root = process.cwd();
+const scanRoots = ['src'].map((scanRoot) => path.join(root, scanRoot));
+const ignoredDirectories = new Set(['.modern', '.modernjs', 'dist', 'node_modules']);
+const visibleAttributePattern =
+  /\s(?:aria-label|alt|placeholder|title)=["']([^"']*[A-Za-z][^"']*)["']/gu;
+const jsxTextPattern = />([^<>{}]*[A-Za-z][^<>{}]*)</gu;
+
+const collectFiles = (directory) => {
+  if (!fs.existsSync(directory)) {
+    return [];
+  }
+
+  const files = [];
+  for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+    if (entry.isDirectory()) {
+      if (!ignoredDirectories.has(entry.name)) {
+        files.push(...collectFiles(path.join(directory, entry.name)));
+      }
+      continue;
+    }
+
+    if (entry.isFile() && /\.(jsx|tsx)$/u.test(entry.name) && !entry.name.endsWith('.d.ts')) {
+      files.push(path.join(directory, entry.name));
+    }
+  }
+  return files;
+};
+
+const lineNumberForIndex = (content, index) => content.slice(0, index).split('\n').length;
+const isIgnoredLine = (content, index) => {
+  const lineStart = content.lastIndexOf('\n', index) + 1;
+  const lineEnd = content.indexOf('\n', index);
+  const currentLineEnd = lineEnd === -1 ? content.length : lineEnd;
+  const previousLineStart = content.lastIndexOf('\n', Math.max(0, lineStart - 2)) + 1;
+  const nextLineEnd = content.indexOf('\n', currentLineEnd + 1);
+  const context = content.slice(
+    previousLineStart,
+    nextLineEnd === -1 ? content.length : nextLineEnd,
+  );
+  return /i18n-ignore/u.test(context);
+};
+
+const violations = [];
+for (const filePath of scanRoots.flatMap(collectFiles)) {
+  const content = fs.readFileSync(filePath, 'utf-8');
+  for (const match of content.matchAll(visibleAttributePattern)) {
+    if (!isIgnoredLine(content, match.index ?? 0)) {
+      violations.push({
+        filePath,
+        line: lineNumberForIndex(content, match.index ?? 0),
+        text: match[1].trim(),
+      });
+    }
+  }
+
+  for (const match of content.matchAll(jsxTextPattern)) {
+    const text = match[1].replaceAll(/\s+/gu, ' ').trim();
+    if (text && !isIgnoredLine(content, match.index ?? 0)) {
+      violations.push({
+        filePath,
+        line: lineNumberForIndex(content, match.index ?? 0),
+        text,
+      });
+    }
+  }
+}
+
+if (violations.length > 0) {
+  console.error('Hardcoded user-visible JSX strings found. Move copy to locale JSON files.');
+  for (const violation of violations) {
+    console.error(
+      `${path.relative(root, violation.filePath)}:${violation.line} ${JSON.stringify(
+        violation.text,
+      )}`,
+    );
+  }
+  process.exit(1);
+}
+
+console.log('No hardcoded user-visible JSX strings found.');

package/template/scripts/validate-ultramodern.mjs.handlebars

@@ -16,6 +16,7 @@ const requiredTokens = [
   'enableModuleFederationSSR',
   'enableBffRequestId',
   'enableTelemetryExporters',
+  'i18nPlugin(',
 ];
 const missing = requiredTokens.filter((token) => !content.includes(token));
 
@@ -51,6 +52,9 @@ const requiredPaths = [
   'oxlint.config.ts',
   'oxfmt.config.ts',
   'scripts/bootstrap-agent-skills.mjs',
+  'scripts/check-i18n-strings.mjs',
+  'config/public/locales/en/translation.json',
+  'config/public/locales/cs/translation.json',
 ];
 const manifestErrors = [];
 
@@ -118,6 +122,7 @@ const skillsLock = JSON.parse(
 const requiredScripts = {
   format: 'oxfmt .',
   'format:check': 'oxfmt --check .',
+  'i18n:check': 'node ./scripts/check-i18n-strings.mjs',
   lint: 'oxlint .',
   'lint:fix': 'oxlint . --fix',
   'skills:check': 'node ./scripts/bootstrap-agent-skills.mjs --check',
@@ -139,6 +144,13 @@ if (
   process.exit(1);
 }
 
+for (const dependency of ['@modern-js/plugin-i18n', 'i18next', 'react-i18next']) {
+  if (!packageJson.dependencies?.[dependency]) {
+    console.error(`Missing dependency: ${dependency}`);
+    process.exit(1);
+  }
+}
+
 for (const dependency of [
   '@effect/tsgo',
   '@typescript/native-preview',

package/template/src/modern.runtime.ts.handlebars

@@ -1,7 +1,23 @@
 import { defineRuntimeConfig } from '@modern-js/runtime';
+import { createInstance } from 'i18next';
+
+const i18nInstance = createInstance();
 
 export default defineRuntimeConfig({
+  i18n: {
+    i18nInstance,
+    initOptions: {
+      defaultNS: 'translation',
+      fallbackLng: 'en',
+      interpolation: {
+        escapeValue: false,
+      },
+      ns: ['translation'],
+      supportedLngs: ['en', 'cs'],
+    },
+  },
 {{#if isTanstackRouter}}  router: {
     framework: 'tanstack',
-  },{{/if}}
+  },
+{{/if~}}
 });

package/template/src/routes/page.tsx.handlebars

@@ -1,11 +1,19 @@
 import { Helmet } from '@modern-js/runtime/head';
+import { useModernI18n } from '@modern-js/plugin-i18n/runtime';
 {{#if useEffectBff}}import effectBff from '@api/effect/index';
 import { Effect } from '@modern-js/plugin-bff/effect-client';
 import { useEffect, useState } from 'react';
 {{/if}}
+import { useTranslation } from 'react-i18next';
 import './index.css';
 
 const Index = () => {
+  const { t } = useTranslation();
+  const { changeLanguage, language } = useModernI18n();
+  const languageOptions = [
+    { code: 'en', label: t('home.language.en') },
+    { code: 'cs', label: t('home.language.cs') },
+  ];
 {{#if useEffectBff}}  const [effectMessage, setEffectMessage] = useState('loading...');
 
   useEffect(() => {
@@ -36,25 +44,41 @@ const Index = () => {
         />
       </Helmet>
       <main>
+        <nav className="language-switcher" aria-label={t('home.language.switcher')}>
+          {languageOptions.map((option) => (
+            <button
+              disabled={language === option.code}
+              key={option.code}
+              onClick={() => void changeLanguage(option.code)}
+              type="button"
+            >
+              {option.label}
+            </button>
+          ))}
+        </nav>
         <div className="title">
-          UltraModern.js 3.0
+          {t('home.title')}
           <img
+            alt={t('home.logoAlt')}
             className="logo"
             src="https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/modern-js-logo.svg"
-            alt="UltraModern.js Logo"
           />
-          <p className="name">presetUltramodern</p>
+          <p className="name">{t('home.name')}</p>
         </div>
         <p className="description{{#if enableTailwind}} text-emerald-700 font-semibold{{/if}}">
-          This starter ships the public <code className="code">presetUltramodern(...)</code>{' '}
-          profile. Start in
-          <code className="code">modern.config.ts</code>, keep
-          <code className="code">pnpm run ultramodern:check</code> green, and tune the generated
-          preset only where your app needs a softer lane.
+          {t('home.description.intro')} <code className="code">presetUltramodern(...)</code>{' '}
+          {/* i18n-ignore technical token */}
+          {t('home.description.afterPreset')}
+          <code className="code">modern.config.ts</code>
+          {/* i18n-ignore technical token */}
+          {t('home.description.afterConfig')}
+          <code className="code">pnpm run ultramodern:check</code>
+          {/* i18n-ignore technical token */}
+          {t('home.description.end')}
         </p>
 {{#if useEffectBff}}
         <p className="description effect-message{{#if enableTailwind}} text-emerald-700 font-semibold{{/if}}">
-          Effect HttpApi response: <code className="code">{effectMessage}</code>
+          {t('home.bff.response')} <code className="code">{effectMessage}</code>
         </p>
 {{/if}}
         <div className="grid">
@@ -65,14 +89,14 @@ const Index = () => {
             className="card"
           >
             <h2>
-              UltraModern.js Guide
+              {t('home.cards.guide.title')}
               <img
+                alt=""
                 className="arrow-right"
                 src="https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/arrow-right.svg"
-                alt="Guide"
               />
             </h2>
-            <p>Review the MV-first, TanStack-ready, Effect-ready public preset.</p>
+            <p>{t('home.cards.guide.body')}</p>
           </a>
           <a
             href="https://bleedingdev.github.io/ultramodern.js/configure/app/usage.html"
@@ -81,16 +105,14 @@ const Index = () => {
             rel="noreferrer"
           >
             <h2>
-              Configure presetUltramodern
+              {t('home.cards.config.title')}
               <img
+                alt=""
                 className="arrow-right"
                 src="https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/arrow-right.svg"
-                alt="Tutorials"
               />
             </h2>
-            <p>
-              Tune the generated defaults in <code className="code">modern.config.ts</code>.
-            </p>
+            <p>{t('home.cards.config.body')}</p>
           </a>
           <a
             href="https://github.com/BleedingDev/ultramodern.js/blob/main-ultramodern/packages/toolkit/create/template/.github/workflows/ultramodern-gates.yml.handlebars"
@@ -99,17 +121,14 @@ const Index = () => {
             rel="noreferrer"
           >
             <h2>
-              Ultramodern Gates
+              {t('home.cards.gates.title')}
               <img
+                alt=""
                 className="arrow-right"
                 src="https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/arrow-right.svg"
-                alt="Config"
               />
             </h2>
-            <p>
-              The starter includes a PR workflow for <code className="code">ultramodern:check</code>{' '}
-              and build.
-            </p>
+            <p>{t('home.cards.gates.body')}</p>
           </a>
           <a
             href="https://bleedingdev.github.io/ultramodern.js/configure/app/bff/effect.html"
@@ -118,14 +137,14 @@ const Index = () => {
             className="card"
           >
             <h2>
-              BFF + Effect
+              {t('home.cards.bff.title')}
               <img
+                alt=""
                 className="arrow-right"
                 src="https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/arrow-right.svg"
-                alt="Github"
               />
             </h2>
-            <p>Keep Effect as the preferred BFF lane while Hono stays an explicit fallback.</p>
+            <p>{t('home.cards.bff.body')}</p>
           </a>
         </div>
       </main>

package/template-workspace/AGENTS.md

@@ -7,7 +7,12 @@ This workspace is generated as an agent-ready UltraModern.js SuperApp. Agents sh
 - `pnpm lint` runs Oxlint with the Ultracite preset.
 - `pnpm format` runs oxfmt.
 - `pnpm typecheck` runs effect-tsgo as the TypeScript checker.
-- `pnpm check` runs formatting, linting, effect-tsgo, private-skill availability checks, and the generated workspace contract.
+- `pnpm i18n:check` rejects hardcoded user-visible JSX text in generated apps.
+- `pnpm check` runs formatting, linting, effect-tsgo, i18n checks, private-skill availability checks, and the generated workspace contract.
+
+## Internationalization
+
+Runtime i18n is enabled by default for generated apps. Agents must put user-visible UI copy in each app's `config/public/locales/<lang>/translation.json` and render it through `react-i18next` or `@modern-js/plugin-i18n/runtime`. Do not add hardcoded JSX text, `aria-label`, `title`, `alt`, or `placeholder` strings unless the value is a non-translatable technical token.
 
 ## Required Skill Baseline
 

package/template-workspace/scripts/check-i18n-strings.mjs

@@ -0,0 +1,83 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+const root = process.cwd();
+const scanRoots = ['apps'].map((scanRoot) => path.join(root, scanRoot));
+const ignoredDirectories = new Set(['.modern', '.modernjs', 'dist', 'node_modules']);
+const visibleAttributePattern =
+  /\s(?:aria-label|alt|placeholder|title)=["']([^"']*[A-Za-z][^"']*)["']/gu;
+const jsxTextPattern = />([^<>{}]*[A-Za-z][^<>{}]*)</gu;
+
+const collectFiles = (directory) => {
+  if (!fs.existsSync(directory)) {
+    return [];
+  }
+
+  const files = [];
+  for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+    if (entry.isDirectory()) {
+      if (!ignoredDirectories.has(entry.name)) {
+        files.push(...collectFiles(path.join(directory, entry.name)));
+      }
+      continue;
+    }
+
+    if (entry.isFile() && /\.(jsx|tsx)$/u.test(entry.name) && !entry.name.endsWith('.d.ts')) {
+      files.push(path.join(directory, entry.name));
+    }
+  }
+  return files;
+};
+
+const lineNumberForIndex = (content, index) => content.slice(0, index).split('\n').length;
+const isIgnoredLine = (content, index) => {
+  const lineStart = content.lastIndexOf('\n', index) + 1;
+  const lineEnd = content.indexOf('\n', index);
+  const currentLineEnd = lineEnd === -1 ? content.length : lineEnd;
+  const previousLineStart = content.lastIndexOf('\n', Math.max(0, lineStart - 2)) + 1;
+  const nextLineEnd = content.indexOf('\n', currentLineEnd + 1);
+  const context = content.slice(
+    previousLineStart,
+    nextLineEnd === -1 ? content.length : nextLineEnd,
+  );
+  return /i18n-ignore/u.test(context);
+};
+
+const violations = [];
+for (const filePath of scanRoots.flatMap(collectFiles)) {
+  const content = fs.readFileSync(filePath, 'utf-8');
+  for (const match of content.matchAll(visibleAttributePattern)) {
+    if (!isIgnoredLine(content, match.index ?? 0)) {
+      violations.push({
+        filePath,
+        line: lineNumberForIndex(content, match.index ?? 0),
+        text: match[1].trim(),
+      });
+    }
+  }
+
+  for (const match of content.matchAll(jsxTextPattern)) {
+    const text = match[1].replaceAll(/\s+/gu, ' ').trim();
+    if (text && !isIgnoredLine(content, match.index ?? 0)) {
+      violations.push({
+        filePath,
+        line: lineNumberForIndex(content, match.index ?? 0),
+        text,
+      });
+    }
+  }
+}
+
+if (violations.length > 0) {
+  console.error('Hardcoded user-visible JSX strings found. Move copy to locale JSON files.');
+  for (const violation of violations) {
+    console.error(
+      `${path.relative(root, violation.filePath)}:${violation.line} ${JSON.stringify(
+        violation.text,
+      )}`,
+    );
+  }
+  process.exit(1);
+}
+
+console.log('No hardcoded user-visible JSX strings found.');

package/template-workspace/scripts/validate-ultramodern-workspace.mjs.handlebars

@@ -8,6 +8,7 @@ const rstackAgentSkillsCommit = '61c948b42512e223bad44b83af4080eba48b2677';
 const modernPackages = [
   '@modern-js/app-tools',
   '@modern-js/plugin-bff',
+  '@modern-js/plugin-i18n',
   '@modern-js/plugin-tanstack',
   '@modern-js/runtime',
 ];
@@ -58,18 +59,31 @@ const requiredPaths = [
   '.modernjs/ultramodern-workspace-template-manifest.json',
   '.modernjs/ultramodern-package-source.json',
   'scripts/bootstrap-agent-skills.mjs',
+  'scripts/check-i18n-strings.mjs',
   'apps/shell-super-app/package.json',
+  'apps/shell-super-app/config/public/locales/en/translation.json',
+  'apps/shell-super-app/config/public/locales/cs/translation.json',
   'apps/shell-super-app/modern.config.ts',
   'apps/shell-super-app/module-federation.config.ts',
+  'apps/shell-super-app/src/modern.runtime.ts',
   'apps/remotes/remote-commerce/package.json',
+  'apps/remotes/remote-commerce/config/public/locales/en/translation.json',
+  'apps/remotes/remote-commerce/config/public/locales/cs/translation.json',
   'apps/remotes/remote-commerce/modern.config.ts',
   'apps/remotes/remote-commerce/module-federation.config.ts',
+  'apps/remotes/remote-commerce/src/modern.runtime.ts',
   'apps/remotes/remote-identity/package.json',
+  'apps/remotes/remote-identity/config/public/locales/en/translation.json',
+  'apps/remotes/remote-identity/config/public/locales/cs/translation.json',
   'apps/remotes/remote-identity/modern.config.ts',
   'apps/remotes/remote-identity/module-federation.config.ts',
+  'apps/remotes/remote-identity/src/modern.runtime.ts',
   'apps/remotes/remote-design-system/package.json',
+  'apps/remotes/remote-design-system/config/public/locales/en/translation.json',
+  'apps/remotes/remote-design-system/config/public/locales/cs/translation.json',
   'apps/remotes/remote-design-system/modern.config.ts',
   'apps/remotes/remote-design-system/module-federation.config.ts',
+  'apps/remotes/remote-design-system/src/modern.runtime.ts',
   'services/service-recommendations-effect/package.json',
   'services/service-recommendations-effect/modern.config.ts',
   'services/service-recommendations-effect/api/effect/index.ts',
@@ -134,6 +148,7 @@ assert(
 const requiredRootScripts = {
   format: 'oxfmt .',
   'format:check': 'oxfmt --check .',
+  'i18n:check': 'node ./scripts/check-i18n-strings.mjs',
   lint: 'oxlint .',
   'lint:fix': 'oxlint . --fix',
   'skills:check': 'node ./scripts/bootstrap-agent-skills.mjs --check',
@@ -207,6 +222,13 @@ const appPackagePaths = [
 
 for (const packagePath of appPackagePaths) {
   const packageJson = readJson(packagePath);
+  assert(
+    packageJson.dependencies?.['@modern-js/plugin-i18n'] ===
+      expectedModernDependency('@modern-js/plugin-i18n'),
+    `${packagePath} must use @modern-js/plugin-i18n through ${expectedModernDependency(
+      '@modern-js/plugin-i18n',
+    )}`,
+  );
   assert(
     packageJson.dependencies?.['@modern-js/plugin-tanstack'] ===
       expectedModernDependency('@modern-js/plugin-tanstack'),
@@ -236,6 +258,11 @@ for (const packagePath of appPackagePaths) {
     packageJson.dependencies?.[`@${packageScope}/shared-design-tokens`] === 'workspace:*',
     `${packagePath} must link generated shared design tokens through workspace:*`,
   );
+  assert(packageJson.dependencies?.i18next === '26.2.0', `${packagePath} must include i18next`);
+  assert(
+    packageJson.dependencies?.['react-i18next'] === '17.0.8',
+    `${packagePath} must include react-i18next`,
+  );
   assert(
     packageJson.dependencies?.['@tanstack/react-router'] === tanstackVersion,
     `${packagePath} must use @tanstack/react-router ${tanstackVersion}`,
@@ -258,6 +285,7 @@ for (const configPath of [
 ]) {
   const config = readText(configPath);
   assert(config.includes('presetUltramodern('), `${configPath} must use presetUltramodern`);
+  assert(config.includes('i18nPlugin('), `${configPath} must enable plugin-i18n`);
   assert(config.includes('tanstackRouterPlugin()'), `${configPath} must enable plugin-tanstack`);
   assert(
     config.includes('moduleFederationPlugin()'),