locale-tool 1.0.0

package/.idea/locale-tool.iml

@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<module type="WEB_MODULE" version="4">
+  <component name="NewModuleRootManager">
+    <content url="file://$MODULE_DIR$">
+      <excludeFolder url="file://$MODULE_DIR$/.tmp" />
+      <excludeFolder url="file://$MODULE_DIR$/temp" />
+      <excludeFolder url="file://$MODULE_DIR$/tmp" />
+    </content>
+    <orderEntry type="inheritedJdk" />
+    <orderEntry type="sourceFolder" forTests="false" />
+  </component>
+</module>

package/.idea/material_theme_project_new.xml

@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="MaterialThemeProjectNewConfig">
+    <option name="metadata">
+      <MTProjectMetadataState>
+        <option name="migrated" value="true" />
+        <option name="pristineConfig" value="false" />
+        <option name="userId" value="6dbcab2b:1923e02f15b:-7ff1" />
+      </MTProjectMetadataState>
+    </option>
+    <option name="titleBarState">
+      <MTProjectTitleBarConfigState>
+        <option name="overrideColor" value="false" />
+      </MTProjectTitleBarConfigState>
+    </option>
+  </component>
+</project>

package/.idea/modules.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="ProjectModuleManager">
+    <modules>
+      <module fileurl="file://$PROJECT_DIR$/.idea/locale-tool.iml" filepath="$PROJECT_DIR$/.idea/locale-tool.iml" />
+    </modules>
+  </component>
+</project>

package/.idea/vcs.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="VcsDirectoryMappings">
+    <mapping directory="$PROJECT_DIR$" vcs="Git" />
+  </component>
+</project>

package/dist/index.js

@@ -0,0 +1,462 @@
+#!/usr/bin/env node
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const commander_1 = require("commander");
+const fs_1 = require("fs");
+const path_1 = require("path");
+const url_1 = require("url");
+const LOCALES_DIR = './src/lang/locale';
+const TYPES_DIR = (0, path_1.join)(LOCALES_DIR, '_types');
+const INTERFACES_FILE = (0, path_1.join)(TYPES_DIR, 'interfaces.ts');
+function flattenLocale(nested) {
+    const result = {};
+    function traverse(obj, path = '') {
+        for (const [key, value] of Object.entries(obj)) {
+            const currentPath = path ? `${path}.${key}` : key;
+            if (Array.isArray(value)) {
+                result[currentPath] = value;
+            }
+            else if (typeof value === 'object' && value !== null) {
+                traverse(value, currentPath);
+            }
+            else if (typeof value === 'string') {
+                result[currentPath] = value;
+            }
+        }
+    }
+    traverse(nested);
+    return result;
+}
+function nestifyLocale(flat) {
+    var _a;
+    const result = {};
+    for (const [path, value] of Object.entries(flat)) {
+        const keys = path.split('.');
+        let current = result;
+        for (let i = 0; i < keys.length - 1; i++) {
+            const key = keys[i];
+            (_a = current[key]) !== null && _a !== void 0 ? _a : (current[key] = {});
+            current = current[key];
+        }
+        const lastKey = keys[keys.length - 1];
+        current[lastKey] = value;
+    }
+    return result;
+}
+function generateTypesFromNest(nest) {
+    const interfaceLines = [];
+    function traverse(obj, indent = 1, path = '') {
+        for (const [key, value] of Object.entries(obj)) {
+            const indentStr = '    '.repeat(indent);
+            const currentPath = path ? `${path}.${key}` : key;
+            if (Array.isArray(value)) {
+                interfaceLines.push(`${indentStr}${key}: string[];`);
+            }
+            else if (typeof value === 'object' && value !== null) {
+                interfaceLines.push(`${indentStr}${key}: {`);
+                traverse(value, indent + 1, currentPath);
+                interfaceLines.push(`${indentStr}};`);
+            }
+            else if (typeof value === 'string') {
+                interfaceLines.push(`${indentStr}${key}: string;`);
+            }
+        }
+    }
+    traverse(nest);
+    return `export interface LocaleSchema {\n${interfaceLines.join('\n')}\n}`;
+}
+function getTranslationGuide() {
+    return `# Translation Guide
+
+## Getting Started
+
+### 1. Find Your Language Code
+- Visit [ISO 639-1 Language Codes](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) to find your language code
+- Use the two-letter code (e.g., \`de\` for German, \`fr\` for French, \`es\` for Spanish)
+- For region-specific variants, use format like \`en-US\`, \`zh-CN\`, \`pt-BR\`
+
+### 2. Start Translating
+1. Open \`flat.json\` in this folder
+2. Translate the **values** (keep the keys unchanged)
+3. When done, run: \`npm run locale nest ${process.argv[3] || 'your-locale'}\`
+
+### 3. Submit Your Translation
+- Create a pull request with your locale folder
+- Include both \`flat.json\` and generated \`index.ts\`
+
+## Translation Rules
+
+### ✅ DO:
+- **Preserve structure**: Keep array and object structures intact
+ - \`["item1", "item2"]\` → \`["элемент1", "элемент2"]\`
+- **Keep variables untouched**: Variables in \`{{brackets}}\` must remain exactly as they are
+ - \`"Hello {{name}}"\` → \`"Привет {{name}}"\`
+- **Maintain line breaks**: Keep \`\\n\` for multi-line messages
+- **Respect key hierarchy**: Keys like \`"settings.pages.debug"\` show UI component structure
+
+### ❌ DON'T:
+- Change or remove JSON keys
+- Translate variables in \`{{brackets}}\`
+- Reorder array elements
+- Break JSON syntax (missing quotes, commas, brackets)
+
+## Examples
+
+### Simple String
+\`\`\`json
+"commands.togglePanels.notice.shown": "Control panels shown"
+// ✅ Should become:
+"commands.togglePanels.notice.shown": "Панели управления показаны"
+\`\`\`
+
+### String with Variables
+\`\`\`json
+"settings.pages.debug.clearLogsStorage.desc": "Storage: {{storage}}, Entries: {{entries}}"
+// ✅ Should become:
+"settings.pages.debug.clearLogsStorage.desc": "Хранилище: {{storage}}, Записи: {{entries}}"
+\`\`\`
+
+### Array of Strings
+\`\`\`json
+"settings.pages.debug.reportIssue.desc": [
+  "If you encounter any issues, please report them.",
+  "How to report:",
+  "1. Enable debug logging"
+]
+// ✅ Should become:
+"settings.pages.debug.reportIssue.desc": [
+  "Если у вас возникли проблемы, сообщите о них.",
+  "Как сообщить:",
+  "1. Включите отладочное логирование"
+]
+\`\`\`
+
+## Best Practices
+
+- **Natural translation**: Translate the meaning, not word-by-word
+- **Keep UI context**: Consider where the text appears (buttons, tooltips, messages)
+- **Test length**: Some UI elements have space constraints - shorten if needed
+- **Maintain tone**: Keep the same level of formality as the original
+- **Handle pluralization**: Adapt to your language's plural rules
+
+## Need Help?
+- Check existing translations in other language folders for reference
+- Ask questions in GitHub issues before starting large translations
+- Test your JSON syntax using online JSON validators`;
+}
+function generateTypes() {
+    return __awaiter(this, void 0, void 0, function* () {
+        const enLocaleDir = (0, path_1.join)(LOCALES_DIR, 'en');
+        const jsonPath = (0, path_1.join)(enLocaleDir, 'flat.json');
+        const tsPath = (0, path_1.join)(enLocaleDir, 'index.ts');
+        if (!(0, fs_1.existsSync)(jsonPath)) {
+            console.error('❌ Error: en/flat.json not found. Run "flat en" first.');
+            process.exit(1);
+        }
+        try {
+            const fullPath = (0, url_1.pathToFileURL)((0, path_1.join)(process.cwd(), tsPath)).href;
+            const module = yield Promise.resolve(`${fullPath + '?t=' + Date.now()}`).then(s => __importStar(require(s)));
+            const nested = module.default;
+            const types = generateTypesFromNest(nested);
+            if (!(0, fs_1.existsSync)(TYPES_DIR)) {
+                (0, fs_1.mkdirSync)(TYPES_DIR, { recursive: true });
+            }
+            (0, fs_1.writeFileSync)(INTERFACES_FILE, types);
+            console.log(`✅ Generated ${INTERFACES_FILE}`);
+        }
+        catch (error) {
+            console.error('❌ Error generating types:', error);
+            process.exit(1);
+        }
+    });
+}
+function createTemplate(locale) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const enLocaleDir = (0, path_1.join)(LOCALES_DIR, 'en');
+        const enJsonPath = (0, path_1.join)(enLocaleDir, 'flat.json');
+        if (!(0, fs_1.existsSync)(enJsonPath)) {
+            console.error('❌ Error: en/flat.json not found. Run "flat en" first.');
+            process.exit(1);
+        }
+        const newLocaleDir = (0, path_1.join)(LOCALES_DIR, locale);
+        if ((0, fs_1.existsSync)(newLocaleDir)) {
+            console.error(`❌ Error: Locale "${locale}" already exists`);
+            process.exit(1);
+        }
+        try {
+            (0, fs_1.mkdirSync)(newLocaleDir, { recursive: true });
+            // Копируем flat.json из en
+            const enFlatData = (0, fs_1.readFileSync)(enJsonPath, 'utf8');
+            const newJsonPath = (0, path_1.join)(newLocaleDir, 'flat.json');
+            (0, fs_1.writeFileSync)(newJsonPath, enFlatData);
+            // Создаём гайд
+            const guidePath = (0, path_1.join)(newLocaleDir, 'TRANSLATION_GUIDE.md');
+            (0, fs_1.writeFileSync)(guidePath, getTranslationGuide());
+            console.log(`✅ Created locale template: ${newLocaleDir}/`);
+            console.log(`📄 Files created:`);
+            console.log(`   - flat.json (copy from en, ready for translation)`);
+            console.log(`   - TRANSLATION_GUIDE.md (translation instructions)`);
+            console.log(`\n🚀 Next steps:`);
+            console.log(`   1. Edit ${locale}/flat.json - translate the values`);
+            console.log(`   2. Run: npm run locale nest ${locale}`);
+            console.log(`   3. Test your translation in the app`);
+        }
+        catch (error) {
+            console.error('❌ Error creating template:', error);
+            process.exit(1);
+        }
+    });
+}
+function flattenAction(locale) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const localeDir = (0, path_1.join)(LOCALES_DIR, locale);
+        const tsPath = (0, path_1.join)(localeDir, 'index.ts');
+        const jsonPath = (0, path_1.join)(localeDir, 'flat.json');
+        const readmePath = (0, path_1.join)(localeDir, 'TRANSLATION_GUIDE.md');
+        if (!(0, fs_1.existsSync)(tsPath)) {
+            console.error(`❌ Error: ${tsPath} not found`);
+            process.exit(1);
+        }
+        try {
+            const fullPath = (0, url_1.pathToFileURL)((0, path_1.join)(process.cwd(), tsPath)).href;
+            const module = yield Promise.resolve(`${fullPath + '?t=' + Date.now()}`).then(s => __importStar(require(s)));
+            const nested = module.default;
+            const flat = flattenLocale(nested);
+            (0, fs_1.writeFileSync)(jsonPath, JSON.stringify(flat, null, 2));
+            if (locale === 'en') {
+                (0, fs_1.writeFileSync)(readmePath, getTranslationGuide());
+                console.log(`✅ Generated ${readmePath}`);
+            }
+            console.log(`✅ Generated ${jsonPath}`);
+        }
+        catch (error) {
+            console.error(`❌ Error processing ${tsPath}:`, error);
+            process.exit(1);
+        }
+    });
+}
+function nestifyAction(locale) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const localeDir = (0, path_1.join)(LOCALES_DIR, locale);
+        const jsonPath = (0, path_1.join)(localeDir, 'flat.json');
+        const tsPath = (0, path_1.join)(localeDir, 'index.ts');
+        if (!(0, fs_1.existsSync)(jsonPath)) {
+            console.error(`❌ Error: ${jsonPath} not found`);
+            process.exit(1);
+        }
+        try {
+            const flatData = JSON.parse((0, fs_1.readFileSync)(jsonPath, 'utf8'));
+            const nested = nestifyLocale(flatData);
+            const tsContent = `import type { LocaleSchema } from '../_types/interfaces';
+${locale !== 'en' ? `import { DeepPartial } from '../../types/definitions';\n` : ''}
+           
+const Locale: ${locale !== 'en' ? 'DeepPartial<LocaleSchema>' : 'LocaleSchema'}  = ${JSON.stringify(nested, null, 4)};
+
+export default Locale;`;
+            (0, fs_1.writeFileSync)(tsPath, tsContent);
+            console.log(`✅ Generated ${tsPath}`);
+            if (locale === 'en') {
+                yield generateTypes();
+            }
+        }
+        catch (error) {
+            console.error(`❌ Error processing ${jsonPath}:`, error);
+            process.exit(1);
+        }
+    });
+}
+function checkAllLocalesAction() {
+    return __awaiter(this, void 0, void 0, function* () {
+        const enFlatPath = (0, path_1.join)(LOCALES_DIR, 'en', 'flat.json');
+        if (!(0, fs_1.existsSync)(enFlatPath)) {
+            console.error('❌ Error: en/flat.json not found');
+            process.exit(1);
+        }
+        const enFlat = JSON.parse((0, fs_1.readFileSync)(enFlatPath, 'utf8'));
+        const enKeys = new Set(Object.keys(enFlat));
+        const totalKeys = enKeys.size;
+        const locales = (0, fs_1.readdirSync)(LOCALES_DIR, { withFileTypes: true })
+            .filter((dirent) => dirent.isDirectory() &&
+            dirent.name !== 'en' &&
+            dirent.name !== '_types')
+            .map((dirent) => dirent.name);
+        const results = [];
+        // Process English
+        console.log(`✅ Locale en: ${totalKeys}/${totalKeys} keys (100%) ✅\n`);
+        // Process other locales
+        for (const locale of locales) {
+            const jsonPath = (0, path_1.join)(LOCALES_DIR, locale, 'flat.json');
+            if (!(0, fs_1.existsSync)(jsonPath)) {
+                console.warn(`⚠️ Warning: ${jsonPath} not found\n`);
+                continue;
+            }
+            try {
+                const flatData = JSON.parse((0, fs_1.readFileSync)(jsonPath, 'utf8'));
+                const flatKeys = new Set(Object.keys(flatData));
+                const missingKeys = [...enKeys].filter((key) => !flatKeys.has(key));
+                const extraKeys = [...flatKeys].filter((key) => !enKeys.has(key));
+                const completed = totalKeys - missingKeys.length;
+                const percentage = Math.round((completed / totalKeys) * 100 * 10) / 10;
+                results.push({
+                    locale,
+                    completed,
+                    missing: missingKeys,
+                    extra: extraKeys,
+                    percentage,
+                });
+                // Status icon based on completion
+                let statusIcon = '✅';
+                if (percentage < 50)
+                    statusIcon = '🔴';
+                else if (percentage < 80)
+                    statusIcon = '🟡';
+                console.log(`${statusIcon} Locale ${locale}: ${completed}/${totalKeys} keys (${percentage}%) ${statusIcon}`);
+                if (missingKeys.length > 0) {
+                    console.log(`❌ Missing keys:`);
+                    // Group missing keys by section for better readability
+                    const keysBySection = new Map();
+                    missingKeys.forEach((key) => {
+                        const section = key.split('.').slice(0, 2).join('.');
+                        if (!keysBySection.has(section)) {
+                            keysBySection.set(section, []);
+                        }
+                        keysBySection.get(section).push(key);
+                    });
+                    keysBySection.forEach((keys, section) => {
+                        if (keys.length === 1) {
+                            console.log(`  - ${keys[0]}`);
+                        }
+                        else if (keys.length <= 3) {
+                            keys.forEach((key) => console.log(`  - ${key}`));
+                        }
+                        else {
+                            console.log(`  - ${section}.* (${keys.length} keys missing)`);
+                            console.log(`    Examples: ${keys
+                                .slice(0, 2)
+                                .map((k) => k.split('.').pop())
+                                .join(', ')}...`);
+                        }
+                    });
+                }
+                if (extraKeys.length > 0) {
+                    console.log(`⚠️ Extra keys: ${extraKeys.join(', ')}`);
+                }
+                console.log(''); // Empty line between locales
+            }
+            catch (error) {
+                console.error(`❌ Error validating ${jsonPath}:`, error);
+            }
+        }
+        // Summary report
+        if (results.length > 0) {
+            console.log('📊 Translation Progress Summary:');
+            console.log(`  English: ${totalKeys}/${totalKeys} (100%) ✅`);
+            results
+                .sort((a, b) => b.percentage - a.percentage)
+                .forEach((result) => {
+                let statusIcon = '✅';
+                if (result.percentage < 50)
+                    statusIcon = '🔴';
+                else if (result.percentage < 80)
+                    statusIcon = '🟡';
+                const padding = ' '.repeat(8 - result.locale.length);
+                console.log(`  ${result.locale}:${padding}${result.completed}/${totalKeys} (${result.percentage}%) ${statusIcon}`);
+            });
+            const avgCompletion = Math.round((results.reduce((sum, r) => sum + r.percentage, 0) /
+                results.length) *
+                10) / 10;
+            console.log(`\n📈 Average completion: ${avgCompletion}%`);
+        }
+    });
+}
+function updateAllNested() {
+    return __awaiter(this, void 0, void 0, function* () {
+        const locales = (0, fs_1.readdirSync)(LOCALES_DIR, { withFileTypes: true })
+            .filter((dirent) => dirent.isDirectory() && dirent.name !== '_types')
+            .map((dirent) => dirent.name);
+        for (const locale of locales) {
+            try {
+                yield nestifyAction(locale);
+                console.log(`✅ Updated nested structure for locale: ${locale}\n`);
+            }
+            catch (error) {
+                console.error(`❌ Error updating locale ${locale}:`, error);
+            }
+        }
+    });
+}
+const program = new commander_1.Command();
+program
+    .name('locale-tool')
+    .description('Locale management tool for translations')
+    .version('1.0.0');
+program
+    .command('flat')
+    .argument('<locale>', 'locale code (e.g., en, ru, de)')
+    .description('Convert TypeScript locale to flat JSON format')
+    .action(flattenAction);
+program
+    .command('nest')
+    .argument('<locale>', 'locale code (e.g., en, ru, de)')
+    .description('Convert flat JSON to nested TypeScript format')
+    .action(nestifyAction);
+program
+    .command('types')
+    .description('Generate TypeScript interfaces from en/flat.json')
+    .action(generateTypes);
+program
+    .command('template')
+    .argument('<locale>', 'new locale code (e.g., de, fr, es)')
+    .description('Create new locale template from en/flat.json')
+    .action(createTemplate);
+program
+    .command('check-all')
+    .description('Check all locales against en/flat.json')
+    .action(checkAllLocalesAction);
+program
+    .command('update-all-nested')
+    .description('Update nested TypeScript files for all locales from their flat.json')
+    .action(updateAllNested);
+program.parse();

package/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "locale-tool",
+  "version": "1.0.0",
+  "description": "",
+  "main": "dist/index.js",
+  "devDependencies": {
+    "@types/node": "^24.0.4",
+    "typescript": "^5.5.3"
+  },
+  "private": false,
+  "dependencies": {
+    "commander": "^14.0.0"
+  },
+  "scripts": {
+    "build": "tsc"
+  }
+}

package/src/index.ts

@@ -0,0 +1,501 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import {
+    readFileSync,
+    readdirSync,
+    writeFileSync,
+    existsSync,
+    mkdirSync,
+} from 'fs';
+import { join } from 'path';
+import { pathToFileURL } from 'url';
+
+type NestedObject = {
+    [key: string]: string | string[] | NestedObject;
+};
+
+type FlatObject = Record<string, string | string[]>;
+
+const LOCALES_DIR = './src/lang/locale';
+const TYPES_DIR = join(LOCALES_DIR, '_types');
+const INTERFACES_FILE = join(TYPES_DIR, 'interfaces.ts');
+
+function flattenLocale(nested: NestedObject): FlatObject {
+    const result: FlatObject = {};
+
+    function traverse(obj: NestedObject, path: string = ''): void {
+        for (const [key, value] of Object.entries(obj)) {
+            const currentPath = path ? `${path}.${key}` : key;
+
+            if (Array.isArray(value)) {
+                result[currentPath] = value;
+            } else if (typeof value === 'object' && value !== null) {
+                traverse(value, currentPath);
+            } else if (typeof value === 'string') {
+                result[currentPath] = value;
+            }
+        }
+    }
+
+    traverse(nested);
+    return result;
+}
+
+function nestifyLocale(flat: FlatObject): NestedObject {
+    const result: NestedObject = {};
+
+    for (const [path, value] of Object.entries(flat)) {
+        const keys = path.split('.');
+        let current: any = result;
+
+        for (let i = 0; i < keys.length - 1; i++) {
+            const key = keys[i];
+            current[key] ??= {};
+            current = current[key];
+        }
+
+        const lastKey = keys[keys.length - 1];
+        current[lastKey] = value;
+    }
+
+    return result;
+}
+
+function generateTypesFromNest(nest: NestedObject): string {
+    const interfaceLines: string[] = [];
+
+    function traverse(
+        obj: NestedObject,
+        indent: number = 1,
+        path: string = ''
+    ): void {
+        for (const [key, value] of Object.entries(obj)) {
+            const indentStr = '    '.repeat(indent);
+            const currentPath = path ? `${path}.${key}` : key;
+
+            if (Array.isArray(value)) {
+                interfaceLines.push(`${indentStr}${key}: string[];`);
+            } else if (typeof value === 'object' && value !== null) {
+                interfaceLines.push(`${indentStr}${key}: {`);
+                traverse(value, indent + 1, currentPath);
+                interfaceLines.push(`${indentStr}};`);
+            } else if (typeof value === 'string') {
+                interfaceLines.push(`${indentStr}${key}: string;`);
+            }
+        }
+    }
+
+    traverse(nest);
+    return `export interface LocaleSchema {\n${interfaceLines.join('\n')}\n}`;
+}
+function getTranslationGuide(): string {
+    return `# Translation Guide
+
+## Getting Started
+
+### 1. Find Your Language Code
+- Visit [ISO 639-1 Language Codes](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) to find your language code
+- Use the two-letter code (e.g., \`de\` for German, \`fr\` for French, \`es\` for Spanish)
+- For region-specific variants, use format like \`en-US\`, \`zh-CN\`, \`pt-BR\`
+
+### 2. Start Translating
+1. Open \`flat.json\` in this folder
+2. Translate the **values** (keep the keys unchanged)
+3. When done, run: \`npm run locale nest ${process.argv[3] || 'your-locale'}\`
+
+### 3. Submit Your Translation
+- Create a pull request with your locale folder
+- Include both \`flat.json\` and generated \`index.ts\`
+
+## Translation Rules
+
+### ✅ DO:
+- **Preserve structure**: Keep array and object structures intact
+ - \`["item1", "item2"]\` → \`["элемент1", "элемент2"]\`
+- **Keep variables untouched**: Variables in \`{{brackets}}\` must remain exactly as they are
+ - \`"Hello {{name}}"\` → \`"Привет {{name}}"\`
+- **Maintain line breaks**: Keep \`\\n\` for multi-line messages
+- **Respect key hierarchy**: Keys like \`"settings.pages.debug"\` show UI component structure
+
+### ❌ DON'T:
+- Change or remove JSON keys
+- Translate variables in \`{{brackets}}\`
+- Reorder array elements
+- Break JSON syntax (missing quotes, commas, brackets)
+
+## Examples
+
+### Simple String
+\`\`\`json
+"commands.togglePanels.notice.shown": "Control panels shown"
+// ✅ Should become:
+"commands.togglePanels.notice.shown": "Панели управления показаны"
+\`\`\`
+
+### String with Variables
+\`\`\`json
+"settings.pages.debug.clearLogsStorage.desc": "Storage: {{storage}}, Entries: {{entries}}"
+// ✅ Should become:
+"settings.pages.debug.clearLogsStorage.desc": "Хранилище: {{storage}}, Записи: {{entries}}"
+\`\`\`
+
+### Array of Strings
+\`\`\`json
+"settings.pages.debug.reportIssue.desc": [
+  "If you encounter any issues, please report them.",
+  "How to report:",
+  "1. Enable debug logging"
+]
+// ✅ Should become:
+"settings.pages.debug.reportIssue.desc": [
+  "Если у вас возникли проблемы, сообщите о них.",
+  "Как сообщить:",
+  "1. Включите отладочное логирование"
+]
+\`\`\`
+
+## Best Practices
+
+- **Natural translation**: Translate the meaning, not word-by-word
+- **Keep UI context**: Consider where the text appears (buttons, tooltips, messages)
+- **Test length**: Some UI elements have space constraints - shorten if needed
+- **Maintain tone**: Keep the same level of formality as the original
+- **Handle pluralization**: Adapt to your language's plural rules
+
+## Need Help?
+- Check existing translations in other language folders for reference
+- Ask questions in GitHub issues before starting large translations
+- Test your JSON syntax using online JSON validators`;
+}
+
+async function generateTypes(): Promise<void> {
+    const enLocaleDir = join(LOCALES_DIR, 'en');
+    const jsonPath = join(enLocaleDir, 'flat.json');
+    const tsPath = join(enLocaleDir, 'index.ts');
+
+    if (!existsSync(jsonPath)) {
+        console.error('❌ Error: en/flat.json not found. Run "flat en" first.');
+        process.exit(1);
+    }
+
+    try {
+        const fullPath = pathToFileURL(join(process.cwd(), tsPath)).href;
+        const module = await import(fullPath + '?t=' + Date.now());
+        const nested = module.default;
+
+        const types = generateTypesFromNest(nested);
+
+        if (!existsSync(TYPES_DIR)) {
+            mkdirSync(TYPES_DIR, { recursive: true });
+        }
+
+        writeFileSync(INTERFACES_FILE, types);
+        console.log(`✅ Generated ${INTERFACES_FILE}`);
+    } catch (error) {
+        console.error('❌ Error generating types:', error);
+        process.exit(1);
+    }
+}
+
+async function createTemplate(locale: string): Promise<void> {
+    const enLocaleDir = join(LOCALES_DIR, 'en');
+    const enJsonPath = join(enLocaleDir, 'flat.json');
+
+    if (!existsSync(enJsonPath)) {
+        console.error('❌ Error: en/flat.json not found. Run "flat en" first.');
+        process.exit(1);
+    }
+
+    const newLocaleDir = join(LOCALES_DIR, locale);
+
+    if (existsSync(newLocaleDir)) {
+        console.error(`❌ Error: Locale "${locale}" already exists`);
+        process.exit(1);
+    }
+
+    try {
+        mkdirSync(newLocaleDir, { recursive: true });
+
+        // Копируем flat.json из en
+        const enFlatData = readFileSync(enJsonPath, 'utf8');
+        const newJsonPath = join(newLocaleDir, 'flat.json');
+        writeFileSync(newJsonPath, enFlatData);
+
+        // Создаём гайд
+        const guidePath = join(newLocaleDir, 'TRANSLATION_GUIDE.md');
+        writeFileSync(guidePath, getTranslationGuide());
+
+        console.log(`✅ Created locale template: ${newLocaleDir}/`);
+        console.log(`📄 Files created:`);
+        console.log(`   - flat.json (copy from en, ready for translation)`);
+        console.log(`   - TRANSLATION_GUIDE.md (translation instructions)`);
+        console.log(`\n🚀 Next steps:`);
+        console.log(`   1. Edit ${locale}/flat.json - translate the values`);
+        console.log(`   2. Run: npm run locale nest ${locale}`);
+        console.log(`   3. Test your translation in the app`);
+    } catch (error) {
+        console.error('❌ Error creating template:', error);
+        process.exit(1);
+    }
+}
+
+async function flattenAction(locale: string): Promise<void> {
+    const localeDir = join(LOCALES_DIR, locale);
+    const tsPath = join(localeDir, 'index.ts');
+    const jsonPath = join(localeDir, 'flat.json');
+    const readmePath = join(localeDir, 'TRANSLATION_GUIDE.md');
+
+    if (!existsSync(tsPath)) {
+        console.error(`❌ Error: ${tsPath} not found`);
+        process.exit(1);
+    }
+
+    try {
+        const fullPath = pathToFileURL(join(process.cwd(), tsPath)).href;
+        const module = await import(fullPath + '?t=' + Date.now());
+        const nested = module.default;
+
+        const flat = flattenLocale(nested);
+        writeFileSync(jsonPath, JSON.stringify(flat, null, 2));
+
+        if (locale === 'en') {
+            writeFileSync(readmePath, getTranslationGuide());
+            console.log(`✅ Generated ${readmePath}`);
+        }
+
+        console.log(`✅ Generated ${jsonPath}`);
+    } catch (error) {
+        console.error(`❌ Error processing ${tsPath}:`, error);
+        process.exit(1);
+    }
+}
+
+async function nestifyAction(locale: string): Promise<void> {
+    const localeDir = join(LOCALES_DIR, locale);
+    const jsonPath = join(localeDir, 'flat.json');
+    const tsPath = join(localeDir, 'index.ts');
+
+    if (!existsSync(jsonPath)) {
+        console.error(`❌ Error: ${jsonPath} not found`);
+        process.exit(1);
+    }
+
+    try {
+        const flatData = JSON.parse(readFileSync(jsonPath, 'utf8'));
+        const nested = nestifyLocale(flatData);
+
+        const tsContent = `import type { LocaleSchema } from '../_types/interfaces';
+${locale !== 'en' ? `import { DeepPartial } from '../../types/definitions';\n` : ''}
+           
+const Locale: ${locale !== 'en' ? 'DeepPartial<LocaleSchema>' : 'LocaleSchema'}  = ${JSON.stringify(nested, null, 4)};
+
+export default Locale;`;
+
+        writeFileSync(tsPath, tsContent);
+        console.log(`✅ Generated ${tsPath}`);
+
+        if (locale === 'en') {
+            await generateTypes();
+        }
+    } catch (error) {
+        console.error(`❌ Error processing ${jsonPath}:`, error);
+        process.exit(1);
+    }
+}
+
+async function checkAllLocalesAction(): Promise<void> {
+    const enFlatPath = join(LOCALES_DIR, 'en', 'flat.json');
+    if (!existsSync(enFlatPath)) {
+        console.error('❌ Error: en/flat.json not found');
+        process.exit(1);
+    }
+
+    const enFlat: FlatObject = JSON.parse(readFileSync(enFlatPath, 'utf8'));
+    const enKeys = new Set(Object.keys(enFlat));
+    const totalKeys = enKeys.size;
+
+    const locales = readdirSync(LOCALES_DIR, { withFileTypes: true })
+        .filter(
+            (dirent) =>
+                dirent.isDirectory() &&
+                dirent.name !== 'en' &&
+                dirent.name !== '_types'
+        )
+        .map((dirent) => dirent.name);
+
+    const results: Array<{
+        locale: string;
+        completed: number;
+        missing: string[];
+        extra: string[];
+        percentage: number;
+    }> = [];
+
+    // Process English
+    console.log(`✅ Locale en: ${totalKeys}/${totalKeys} keys (100%) ✅\n`);
+
+    // Process other locales
+    for (const locale of locales) {
+        const jsonPath = join(LOCALES_DIR, locale, 'flat.json');
+        if (!existsSync(jsonPath)) {
+            console.warn(`⚠️ Warning: ${jsonPath} not found\n`);
+            continue;
+        }
+
+        try {
+            const flatData: FlatObject = JSON.parse(
+                readFileSync(jsonPath, 'utf8')
+            );
+            const flatKeys = new Set(Object.keys(flatData));
+
+            const missingKeys = [...enKeys].filter((key) => !flatKeys.has(key));
+            const extraKeys = [...flatKeys].filter((key) => !enKeys.has(key));
+            const completed = totalKeys - missingKeys.length;
+            const percentage =
+                Math.round((completed / totalKeys) * 100 * 10) / 10;
+
+            results.push({
+                locale,
+                completed,
+                missing: missingKeys,
+                extra: extraKeys,
+                percentage,
+            });
+
+            // Status icon based on completion
+            let statusIcon = '✅';
+            if (percentage < 50) statusIcon = '🔴';
+            else if (percentage < 80) statusIcon = '🟡';
+
+            console.log(
+                `${statusIcon} Locale ${locale}: ${completed}/${totalKeys} keys (${percentage}%) ${statusIcon}`
+            );
+
+            if (missingKeys.length > 0) {
+                console.log(`❌ Missing keys:`);
+                // Group missing keys by section for better readability
+                const keysBySection = new Map<string, string[]>();
+
+                missingKeys.forEach((key) => {
+                    const section = key.split('.').slice(0, 2).join('.');
+                    if (!keysBySection.has(section)) {
+                        keysBySection.set(section, []);
+                    }
+                    keysBySection.get(section)!.push(key);
+                });
+
+                keysBySection.forEach((keys, section) => {
+                    if (keys.length === 1) {
+                        console.log(`  - ${keys[0]}`);
+                    } else if (keys.length <= 3) {
+                        keys.forEach((key) => console.log(`  - ${key}`));
+                    } else {
+                        console.log(
+                            `  - ${section}.* (${keys.length} keys missing)`
+                        );
+                        console.log(
+                            `    Examples: ${keys
+                                .slice(0, 2)
+                                .map((k) => k.split('.').pop())
+                                .join(', ')}...`
+                        );
+                    }
+                });
+            }
+
+            if (extraKeys.length > 0) {
+                console.log(`⚠️ Extra keys: ${extraKeys.join(', ')}`);
+            }
+
+            console.log(''); // Empty line between locales
+        } catch (error) {
+            console.error(`❌ Error validating ${jsonPath}:`, error);
+        }
+    }
+
+    // Summary report
+    if (results.length > 0) {
+        console.log('📊 Translation Progress Summary:');
+        console.log(`  English: ${totalKeys}/${totalKeys} (100%) ✅`);
+
+        results
+            .sort((a, b) => b.percentage - a.percentage)
+            .forEach((result) => {
+                let statusIcon = '✅';
+                if (result.percentage < 50) statusIcon = '🔴';
+                else if (result.percentage < 80) statusIcon = '🟡';
+
+                const padding = ' '.repeat(8 - result.locale.length);
+                console.log(
+                    `  ${result.locale}:${padding}${result.completed}/${totalKeys} (${result.percentage}%) ${statusIcon}`
+                );
+            });
+
+        const avgCompletion =
+            Math.round(
+                (results.reduce((sum, r) => sum + r.percentage, 0) /
+                    results.length) *
+                10
+            ) / 10;
+        console.log(`\n📈 Average completion: ${avgCompletion}%`);
+    }
+}
+
+async function updateAllNested(): Promise<void> {
+    const locales = readdirSync(LOCALES_DIR, { withFileTypes: true })
+        .filter((dirent) => dirent.isDirectory() && dirent.name !== '_types')
+        .map((dirent) => dirent.name);
+
+    for (const locale of locales) {
+        try {
+            await nestifyAction(locale);
+            console.log(`✅ Updated nested structure for locale: ${locale}\n`);
+        } catch (error) {
+            console.error(`❌ Error updating locale ${locale}:`, error);
+        }
+    }
+}
+
+const program = new Command();
+
+program
+    .name('locale-tool')
+    .description('Locale management tool for translations')
+    .version('1.0.0');
+
+program
+    .command('flat')
+    .argument('<locale>', 'locale code (e.g., en, ru, de)')
+    .description('Convert TypeScript locale to flat JSON format')
+    .action(flattenAction);
+
+program
+    .command('nest')
+    .argument('<locale>', 'locale code (e.g., en, ru, de)')
+    .description('Convert flat JSON to nested TypeScript format')
+    .action(nestifyAction);
+
+program
+    .command('types')
+    .description('Generate TypeScript interfaces from en/flat.json')
+    .action(generateTypes);
+
+program
+    .command('template')
+    .argument('<locale>', 'new locale code (e.g., de, fr, es)')
+    .description('Create new locale template from en/flat.json')
+    .action(createTemplate);
+
+program
+    .command('check-all')
+    .description('Check all locales against en/flat.json')
+    .action(checkAllLocalesAction);
+
+program
+    .command('update-all-nested')
+    .description(
+        'Update nested TypeScript files for all locales from their flat.json'
+    )
+    .action(updateAllNested);
+
+program.parse();

package/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "target": "es2016",
+    "module": "commonjs",
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "outDir": "dist"
+  },
+  "include": ["src"]
+}