@wads.dev/i18n-ts 0.0.1-alpha.0 → 0.0.1-alpha.1

package/AI/ARCHITECTURE.md

@@ -12,13 +12,16 @@ Read this document before changing a consuming project's translations. The host
 `i18n.config.json` describes how translation paths map to the repository:
 
 - `levelCount` defines how many leading key segments are structural groups, excluding root.
+- `catalogFile` identifies the project-root-relative TypeScript module that exports `Langs`.
 - `levelNames` gives those groups human-readable names.
 - `levelImports[0]` describes the root translation location without consuming a key segment.
 - `levelImports[1...levelCount]` map group values to directories and may define `valueReplacer` and `fullReplacer` rules.
-- `importAliases` resolves project-root prefixes; unaliased level paths are relative to their parent.
+- `exportConfig.importAliases` resolves project-root prefixes; unaliased level paths are relative to their parent.
+- `exportConfig.codeFormat` controls quotes, semicolons, shorthand properties, trailing commas, indentation and fit-based object/array wrapping in generated TypeScript. Defaults are single quotes, semicolons, shorthand properties, trailing commas, a 120-character print width, at most 4 inline object properties, at most 8 inline array items and two spaces per level. Nested collections are always multiline; only shallow collections may be inline.
 - `translationsDirectory` is the locale directory inside the resolved group.
 - `languageFileTemplate` maps a language identifier to its file.
 - `languageReplacer` maps a catalog language key to a different filename when required.
+- `deletion` controls how tools report and remove files inside translation directories that are absent from the generated plan. `false` disables detection; otherwise `ignoredExtensions` preserves intentional colocated files and `autoDelete` opts the project into deletion without the CLI `--delete` flag.
 
 Replacers accept dotted full paths or nested objects. `valueReplacer` changes the value inserted in `{value}`. A string in `fullReplacer` redirects a subtree, while `null` keeps the subtree in the parent level's translation files.
 

package/README.md

@@ -6,6 +6,16 @@ Framework-independent TypeScript foundations for strongly typed internationaliza
 
 > Status: `0.0.1-alpha.0`. Public APIs and JSON formats may change before `1.0.0`.
 
+## Wads i18n ecosystem
+
+| Project | Responsibility |
+| --- | --- |
+| [`@wads.dev/i18n-ts`](https://github.com/wads-dev/i18n-ts) | Framework-independent contracts, language loading, project configuration and portable bundles. |
+| [`@wads.dev/i18n-react`](https://github.com/wads-dev/i18n-react) | React Provider, hooks and rich translation rendering built on `i18n-ts`. |
+| [`@wads.dev/i18n-editor`](https://github.com/wads-dev/i18n-editor) | Local editor for inspecting and changing bundles and, incrementally, regenerating project files. |
+
+Use only the packages required by the project. The core remains independent of React and of the Editor.
+
 ## Why it exists
 
 Translation files are application code: their structure changes, keys move, languages grow and mistakes should fail during development rather than reach users. This package keeps that foundation small and explicit:
@@ -16,7 +26,7 @@ Translation files are application code: their structure changes, keys move, lang
 - A JSON bundle lets editors and tools work without importing the application runtime.
 - `i18n.config.json` explains project structure to CLIs, editors and AI agents.
 
-Platform integrations are separate. React support belongs to `@wads.dev/i18n-react`; translation editing belongs to `@wads.dev/i18n-editor`. The same contracts can support future Swift and Kotlin runtimes.
+Platform integrations are separate. React support belongs to [`@wads.dev/i18n-react`](https://github.com/wads-dev/i18n-react); translation editing belongs to [`@wads.dev/i18n-editor`](https://github.com/wads-dev/i18n-editor). The same contracts can support future Swift and Kotlin runtimes.
 
 ## Installation
 
@@ -104,7 +114,7 @@ selected.lang.commons.continue
 
 ## Configure the project structure
 
-Add `i18n.config.json` to the repository root. The application runtime does not need this file: it exists primarily to describe the project to AI agents and to `@wads.dev/i18n-editor`.
+Add `i18n.config.json` to the repository root. The application runtime does not need this file: it exists primarily to describe the project to AI agents and to `@wads.dev/i18n-editor`. Its `catalogFile` points to the project-root-relative TypeScript module that exports `Langs`, allowing the Editor to generate a missing bundle automatically.
 
 The Editor uses it to understand which key segments represent modules or features, how object names map to real folders, where root translations belong and which files should be regenerated after editing. This keeps structural knowledge outside application code.
 
@@ -121,7 +131,7 @@ npx i18n-bundle \
   --output i18n.bundle.json
 ```
 
-The bundle can be opened by `@wads.dev/i18n-editor` or shared with translators without giving them the repository or asking them to navigate many TypeScript files. After review, the edited bundle can return to the development team and be redistributed into the configured project structure. The resulting source changes remain ordinary files, so the Git diff becomes the final safety and review layer before merge.
+The bundle can be opened by [`@wads.dev/i18n-editor`](https://github.com/wads-dev/i18n-editor) or shared with translators without giving them the repository or asking them to navigate many TypeScript files. After review, the edited bundle can return to the development team and be redistributed into the configured project structure. The resulting source changes remain ordinary files, so the Git diff becomes the final safety and review layer before merge.
 
 The alpha currently supports bundle generation, visualization and in-memory editing. Regenerating the complete TypeScript file tree from a reviewed bundle is the next Editor/CLI integration step; the configuration and export plan already describe those destinations.
 

package/dist/cli/exportBundle.js

@@ -17,7 +17,7 @@ function loadTypeScript() {
 }
 function parseArguments(argv) {
     const options = {
-        input: 'src/shared/i18n/translations/index.ts',
+        input: 'src/shared/i18n/index.ts',
         output: 'i18n.bundle.json',
     };
     for (let index = 0; index < argv.length; index += 1) {
@@ -51,7 +51,7 @@ Usage:
   i18n-bundle --input src/shared/i18n/translations/index.ts --output i18n.bundle.json
 
 Options:
-  --input         Project TypeScript catalog (default: src/shared/i18n/translations/index.ts)
+  --input         Project TypeScript catalog (default: src/shared/i18n/index.ts)
   --output        Output JSON file (default: i18n.bundle.json)
   --config        Optional i18n.config.json copied beside the output bundle
   --help, -h      Show this help`);

package/dist/config/index.d.ts

@@ -9,19 +9,47 @@ export type I18nLevelImport = {
     valueReplacer?: I18nPathReplacer;
     fullReplacer?: I18nPathReplacer;
 };
+export type I18nDeletionConfig = {
+    ignoredExtensions: string[];
+    autoDelete: boolean;
+};
+export type I18nIndentationConfig = {
+    character: 'space' | 'tab';
+    size: number;
+};
+export type I18nCollectionLayout = 'fit' | 'multiline';
+export type I18nCodeFormatConfig = {
+    useDoubleQuotes: boolean;
+    useSemicolons: boolean;
+    useShorthandProperties: boolean;
+    useTrailingCommas: boolean;
+    printWidth: number;
+    maxObjectInlineItems: number;
+    maxArrayInlineItems: number;
+    objectLayout: I18nCollectionLayout;
+    arrayLayout: I18nCollectionLayout;
+    indentation: I18nIndentationConfig;
+};
+export type I18nExportConfig = {
+    importAliases: Record<string, string>;
+    codeFormat: I18nCodeFormatConfig;
+};
 export type I18nProjectConfig = {
     format: typeof PROJECT_CONFIG_FORMAT;
     version: typeof PROJECT_CONFIG_VERSION;
+    catalogFile: string;
     levelCount: number;
     levelNames: string;
     levelImports: I18nLevelImport[];
-    importAliases: Record<string, string>;
+    exportConfig: I18nExportConfig;
     translationsDirectory: string;
     languageFileTemplate: string;
     languageReplacer: Record<string, string>;
+    deletion: false | I18nDeletionConfig;
 };
 export declare function getDefaultLevelImport(levelIndex: number): I18nLevelImport;
 export declare function createDefaultProjectConfig(): I18nProjectConfig;
+export declare function normalizeDeletionConfig(value: unknown): false | I18nDeletionConfig;
 export declare function normalizeProjectConfig(value?: Partial<I18nProjectConfig>): I18nProjectConfig;
 export declare function getLevelName(config: I18nProjectConfig, level: number): string;
 export declare function getLevelImport(config: I18nProjectConfig, levelIndex: number): I18nLevelImport;

package/dist/config/index.js

@@ -13,6 +13,7 @@ export function createDefaultProjectConfig() {
     return {
         format: PROJECT_CONFIG_FORMAT,
         version: PROJECT_CONFIG_VERSION,
+        catalogFile: 'src/shared/i18n/index.ts',
         levelCount: 2,
         levelNames: 'Module, Feature',
         levelImports: [
@@ -20,10 +21,31 @@ export function createDefaultProjectConfig() {
             getDefaultLevelImport(1),
             getDefaultLevelImport(2),
         ],
-        importAliases: { '@/': 'src/' },
+        exportConfig: {
+            importAliases: { '@/': 'src/' },
+            codeFormat: {
+                useDoubleQuotes: false,
+                useSemicolons: true,
+                useShorthandProperties: true,
+                useTrailingCommas: true,
+                printWidth: 120,
+                maxObjectInlineItems: 4,
+                maxArrayInlineItems: 8,
+                objectLayout: 'fit',
+                arrayLayout: 'fit',
+                indentation: {
+                    character: 'space',
+                    size: 2,
+                },
+            },
+        },
         translationsDirectory: 'i18n',
         languageFileTemplate: '{language}.ts',
         languageReplacer: {},
+        deletion: {
+            ignoredExtensions: [],
+            autoDelete: false,
+        },
     };
 }
 function isRecord(value) {
@@ -48,13 +70,66 @@ function normalizeStringRecord(value) {
         .filter((entry) => typeof entry[1] === 'string')
         .map(([key, item]) => [key, item.trim()]));
 }
+export function normalizeDeletionConfig(value) {
+    if (value === false)
+        return false;
+    const input = isRecord(value) ? value : {};
+    const ignoredExtensions = Array.isArray(input.ignoredExtensions)
+        ? [...new Set(input.ignoredExtensions
+                .filter((extension) => typeof extension === 'string')
+                .map((extension) => extension.trim().toLowerCase())
+                .filter(Boolean)
+                .map((extension) => extension.startsWith('.') ? extension : `.${extension}`))]
+        : [];
+    return {
+        ignoredExtensions,
+        autoDelete: input.autoDelete === true,
+    };
+}
+function normalizeCodeFormat(value, legacyExportConfig) {
+    const defaults = createDefaultProjectConfig().exportConfig.codeFormat;
+    const input = isRecord(value) ? value : {};
+    const indentation = isRecord(input.indentation) ? input.indentation : {};
+    const rawIndentationSize = Number.parseInt(String(indentation.size ?? defaults.indentation.size), 10);
+    const rawPrintWidth = Number.parseInt(String(input.printWidth ?? defaults.printWidth), 10);
+    const rawMaxObjectInlineItems = Number.parseInt(String(input.maxObjectInlineItems ?? defaults.maxObjectInlineItems), 10);
+    const rawMaxArrayInlineItems = Number.parseInt(String(input.maxArrayInlineItems ?? defaults.maxArrayInlineItems), 10);
+    return {
+        useDoubleQuotes: (input.useDoubleQuotes ?? legacyExportConfig.useDoubleQuotes) === true,
+        useSemicolons: input.useSemicolons !== false,
+        useShorthandProperties: input.useShorthandProperties !== false,
+        useTrailingCommas: input.useTrailingCommas !== false,
+        printWidth: Number.isFinite(rawPrintWidth)
+            ? Math.min(400, Math.max(40, rawPrintWidth))
+            : defaults.printWidth,
+        maxObjectInlineItems: Number.isFinite(rawMaxObjectInlineItems)
+            ? Math.min(100, Math.max(0, rawMaxObjectInlineItems))
+            : defaults.maxObjectInlineItems,
+        maxArrayInlineItems: Number.isFinite(rawMaxArrayInlineItems)
+            ? Math.min(100, Math.max(0, rawMaxArrayInlineItems))
+            : defaults.maxArrayInlineItems,
+        objectLayout: input.objectLayout === 'multiline' ? 'multiline' : 'fit',
+        arrayLayout: input.arrayLayout === 'multiline' ? 'multiline' : 'fit',
+        indentation: {
+            character: indentation.character === 'tab' ? 'tab' : 'space',
+            size: Number.isFinite(rawIndentationSize)
+                ? Math.min(8, Math.max(1, rawIndentationSize))
+                : defaults.indentation.size,
+        },
+    };
+}
 export function normalizeProjectConfig(value = {}) {
     const defaults = createDefaultProjectConfig();
     const levelCount = Math.max(0, Number.parseInt(String(value.levelCount ?? defaults.levelCount), 10) || 0);
     const inputImports = Array.isArray(value.levelImports) ? value.levelImports : [];
+    const inputRecord = value;
+    const exportConfig = isRecord(value.exportConfig) ? value.exportConfig : {};
     return {
         format: PROJECT_CONFIG_FORMAT,
         version: PROJECT_CONFIG_VERSION,
+        catalogFile: typeof value.catalogFile === 'string' && value.catalogFile.trim()
+            ? value.catalogFile.trim()
+            : defaults.catalogFile,
         levelCount,
         levelNames: typeof value.levelNames === 'string' ? value.levelNames : defaults.levelNames,
         levelImports: Array.from({ length: levelCount + 1 }, (_, index) => {
@@ -66,9 +141,12 @@ export function normalizeProjectConfig(value = {}) {
                 fullReplacer: normalizeReplacer(input.fullReplacer),
             };
         }),
-        importAliases: {
-            ...defaults.importAliases,
-            ...normalizeStringRecord(value.importAliases),
+        exportConfig: {
+            importAliases: {
+                ...defaults.exportConfig.importAliases,
+                ...normalizeStringRecord(exportConfig.importAliases ?? inputRecord.importAliases),
+            },
+            codeFormat: normalizeCodeFormat(exportConfig.codeFormat, exportConfig),
         },
         translationsDirectory: typeof value.translationsDirectory === 'string' && value.translationsDirectory.trim()
             ? value.translationsDirectory.trim()
@@ -77,6 +155,7 @@ export function normalizeProjectConfig(value = {}) {
             ? value.languageFileTemplate.trim()
             : defaults.languageFileTemplate,
         languageReplacer: normalizeStringRecord(value.languageReplacer),
+        deletion: normalizeDeletionConfig(value.deletion),
     };
 }
 export function getLevelName(config, level) {

package/docs/BUNDLE_WORKFLOW.md

@@ -27,7 +27,7 @@ The catalog module must export `Langs`. When `--config` is supplied, the normali
 
 ## Review and edit
 
-The Editor loads the bundle as one in-memory object and uses `i18n.config.json` to present structural levels such as modules and features. Reviewers can navigate all languages together, compare values and edit text without understanding the source repository.
+The Editor loads the bundle as one in-memory object and uses `i18n.config.json` to present structural levels such as modules and features. When it runs from the project root and the bundle is missing, it can use the configured `catalogFile` to generate the bundle automatically. Reviewers can navigate all languages together, compare values and edit text without understanding the source repository.
 
 The intended collaboration cycle is:
 

package/docs/CONFIGURATION.md

@@ -14,6 +14,7 @@ The application runtime does not read this file. Its primary consumers are:
 {
   "format": "wads-i18n-project-config",
   "version": 1,
+  "catalogFile": "src/shared/i18n/index.ts",
   "levelCount": 2,
   "levelNames": "Module, Feature",
   "levelImports": [
@@ -39,14 +40,35 @@ The application runtime does not read this file. Its primary consumers are:
       }
     }
   ],
-  "importAliases": {
-    "@design/": "src/shared/design-system/",
-    "@/": "src/"
+  "exportConfig": {
+    "importAliases": {
+      "@design/": "src/shared/design-system/",
+      "@/": "src/"
+    },
+    "codeFormat": {
+      "useDoubleQuotes": false,
+      "useSemicolons": true,
+      "useShorthandProperties": true,
+      "useTrailingCommas": true,
+      "printWidth": 120,
+      "maxObjectInlineItems": 4,
+      "maxArrayInlineItems": 8,
+      "objectLayout": "fit",
+      "arrayLayout": "fit",
+      "indentation": {
+        "character": "space",
+        "size": 2
+      }
+    }
   },
   "translationsDirectory": "i18n",
   "languageFileTemplate": "{language}.ts",
   "languageReplacer": {
     "pt": "ptBR"
+  },
+  "deletion": {
+    "ignoredExtensions": [".md"],
+    "autoDelete": false
   }
 }
 ```
@@ -59,13 +81,15 @@ JSON does not support comments. Keep explanations in documentation rather than a
 | --- | --- | --- |
 | `format` | string | Contract identifier. Currently `wads-i18n-project-config`. |
 | `version` | number | Configuration schema version. Currently `1`. |
+| `catalogFile` | string | Project-root-relative TypeScript module that exports `Langs`. The Editor uses it to generate a missing bundle. |
 | `levelCount` | number | Structural key levels, excluding root. |
 | `levelNames` | string | Comma-separated display names used by tools. Missing entries become `Level N`. |
 | `levelImports` | array | Root entry plus one entry for each structural level. Its length is `levelCount + 1`. |
-| `importAliases` | object | Maps path prefixes to project-relative directories. |
+| `exportConfig` | object | Controls generated source formatting and project-path aliases used during export. |
 | `translationsDirectory` | string | Directory appended to every resolved translation owner. |
 | `languageFileTemplate` | string | Locale filename template with `{language}`. |
 | `languageReplacer` | object | Maps catalog language keys to actual filename values. |
+| `deletion` | `false` or object | Controls detection, warnings and removal of files outside the generated plan. |
 
 ## Root and structural levels
 
@@ -137,17 +161,69 @@ Like `valueReplacer`, it accepts dotted keys and nested objects.
 
 ## Import aliases
 
-Aliases map configuration paths to project-relative directories. The longest matching prefix wins.
+`exportConfig.importAliases` maps configuration paths to project-relative directories. The longest matching prefix wins.
 
 ```json
 {
-  "@design/": "src/shared/design-system/",
-  "@/": "src/"
+  "exportConfig": {
+    "importAliases": {
+      "@design/": "src/shared/design-system/",
+      "@/": "src/"
+    }
+  }
 }
 ```
 
 With this definition, use `@/modules/{value}`, not `@/src/modules/{value}`. Adding `src` to both sides would incorrectly produce `src/src/modules/...`.
 
+## Generated TypeScript formatting
+
+`exportConfig.codeFormat` controls the TypeScript emitted by the Editor. Its complete defaults are:
+
+```json
+{
+  "exportConfig": {
+    "codeFormat": {
+      "useDoubleQuotes": false,
+      "useSemicolons": true,
+      "useShorthandProperties": true,
+      "useTrailingCommas": true,
+      "printWidth": 120,
+      "maxObjectInlineItems": 4,
+      "maxArrayInlineItems": 8,
+      "objectLayout": "fit",
+      "arrayLayout": "fit",
+      "indentation": {
+        "character": "space",
+        "size": 2
+      }
+    }
+  }
+}
+```
+
+| Field | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `useDoubleQuotes` | boolean | `false` | Uses double quotes instead of single quotes for generated strings, quoted keys, imports, metadata and language unions. |
+| `useSemicolons` | boolean | `true` | Terminates generated declarations, imports, exports and type members with semicolons. |
+| `useShorthandProperties` | boolean | `true` | Emits `feature,` instead of `feature: feature,` when the property and imported identifier match. |
+| `useTrailingCommas` | boolean | `true` | Keeps a comma after the final item in multiline objects and arrays. Required separators between earlier items are always emitted. |
+| `printWidth` | integer from 40 to 400 | `120` | Maximum generated line width used when deciding whether a collection fits inline. |
+| `maxObjectInlineItems` | integer from 0 to 100 | `4` | Maximum number of properties allowed in a shallow inline object. `0` disables inline objects. |
+| `maxArrayInlineItems` | integer from 0 to 100 | `8` | Maximum number of items allowed in a shallow inline array. `0` disables inline arrays. |
+| `objectLayout` | `"fit"` or `"multiline"` | `"fit"` | Keeps a shallow object inline when it fits both `printWidth` and `maxObjectInlineItems`, or always expands it. |
+| `arrayLayout` | `"fit"` or `"multiline"` | `"fit"` | Keeps a shallow array inline when it fits both `printWidth` and `maxArrayInlineItems`, or always expands it. |
+
+Only shallow collections can be rendered inline. An object or array that directly contains another object or array is always multiline; this rule is not configurable. The nested shallow collection may still be inline on its own property or item line.
+| `indentation.character` | `"space"` or `"tab"` | `"space"` | Selects the indentation character. |
+| `indentation.size` | integer from 1 to 8 | `2` | Number of indentation characters per nesting level. |
+
+Function bodies stored in bundles retain their original source text and are not reformatted internally.
+
+Generated imports follow the corresponding structural path configuration. Aliased `levelImports` and `fullReplacer` paths generate the most specific matching alias, while relative level paths generate relative imports. Child imports use the child key segment as their local identifier, enabling shorthand composition such as `finance,`.
+
+The built-in options intentionally cover deterministic source generation without depending on one formatter. A future integration may read established formatter settings or run a configured post-export command. Such a command must remain explicit, project-controlled and separate from source generation because it executes code in the consuming repository.
+
 ## Language filenames
 
 `languageFileTemplate` controls the generated filename:
@@ -164,6 +240,44 @@ When a catalog key differs from the existing filename, use `languageReplacer`:
 
 The catalog language `pt` then generates `ptBR.ts`.
 
+## Divergent files and deletion
+
+Translation directories are treated as managed project structure. A file found inside one of these directories but absent from the generated plan is a deletion candidate.
+
+The safe default detects and reports every candidate, but does not delete it automatically:
+
+```json
+{
+  "deletion": {
+    "ignoredExtensions": [],
+    "autoDelete": false
+  }
+}
+```
+
+Use `ignoredExtensions` for files that are intentionally colocated with translations and must not appear as deletion candidates. Extensions are case-insensitive and may be written with or without the leading dot:
+
+```json
+{
+  "deletion": {
+    "ignoredExtensions": [".md"],
+    "autoDelete": false
+  }
+}
+```
+
+With this configuration, documentation such as `ARCHITECTURE.md` is preserved while divergent TypeScript files are still reported. An ignored file is never deleted, and its containing directory remains while it is nonempty.
+
+Set `autoDelete` to `true` only when the project intentionally allows every non-ignored candidate to be removed during export without the CLI `--delete` option. Interactive export confirmation still applies unless `--yes` is used.
+
+Set `deletion` to `false` to disable candidate detection, deletion warnings and automatic deletion entirely:
+
+```json
+{ "deletion": false }
+```
+
+Without `autoDelete`, use `i18n-edit export --delete` to apply the reported deletions for a single export. Preview remains read-only.
+
 ## Generated destinations
 
 For every resolved owner, the Editor export plan currently includes:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wads.dev/i18n-ts",
-  "version": "0.0.1-alpha.0",
+  "version": "0.0.1-alpha.1",
   "description": "Dependency-free typed i18n contracts, bundle tools and language loading.",
   "license": "MIT",
   "author": {
@@ -55,7 +55,7 @@
     }
   },
   "peerDependencies": {
-    "typescript": ">=5"
+    "typescript": ">=5 <7"
   },
   "peerDependenciesMeta": {
     "typescript": {