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

package/AI/ARCHITECTURE.md

@@ -0,0 +1,52 @@
+# i18n project architecture for AI agents
+
+Read this document before changing a consuming project's translations. The host project's own instructions still take precedence.
+
+## Discover the project first
+
+1. Read the repository instructions and its root `i18n.config.json` when present.
+2. Locate the root translation type, language catalog and locale implementations. Do not assume fixed filenames.
+3. Inspect the existing runtime integration before changing component usage. It may be React, Swift, Kotlin or another platform.
+4. List the configured languages and grouping levels before editing files.
+
+`i18n.config.json` describes how translation paths map to the repository:
+
+- `levelCount` defines how many leading key segments are structural groups, excluding root.
+- `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.
+- `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.
+
+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.
+
+Use defaults from `@wads.dev/i18n-ts/config` only when the project does not provide a value.
+
+## Translation contracts
+
+- A root TypeScript contract describes the complete translation tree.
+- Every locale must implement the same structure.
+- Nested records represent namespaces; strings represent static text.
+- Parameterized text uses typed functions with identical signatures in every locale.
+- Renderable or tokenized values use the host runtime's typed render mechanism.
+- Keep the catalog metadata (`name`, `short`, `locale` and loader) synchronized with the locale files.
+
+## Editing rules
+
+- Never leave user-visible text hardcoded when the host project requires i18n.
+- Search for an existing semantically equivalent key before creating another.
+- Put a key in the closest configured group that owns its meaning.
+- Update the type contract first, then every locale implementation.
+- Preserve function parameters, token names, nesting and value kinds across languages.
+- Translate intent rather than words literally; preserve the product's terminology and tone.
+- Do not silently replace copy in languages you cannot translate reliably. Report the limitation.
+- Validate with the host project's typecheck, tests and lint commands.
+
+## Package boundaries
+
+- `@wads.dev/i18n-ts` provides framework-independent runtime types and language loading.
+- `@wads.dev/i18n-ts/bundle` provides the portable bundle contract.
+- `@wads.dev/i18n-ts/config` provides the portable project-configuration contract.
+- Framework adapters and editor operations are separate packages. Discover their APIs in the consuming project rather than assuming one platform.

package/AI/DEV_USE.md

@@ -0,0 +1,17 @@
+# Using the AI guides
+
+Always begin with `ARCHITECTURE.md`, then select the task guide:
+
+- `PROMPT_TRANSLATE_FILE.md` — move user-visible literals from source code into translations.
+- `PROMPT_ADD_LANG_TO_PROJECT.md` — add a language to the complete catalog.
+- `PROMPT_CREATE_TRANSLATION_KEY.md` — create one or more typed keys in every locale.
+- `PROMPT_UPDATE_TRANSLATION.md` — change existing copy consistently.
+
+Example:
+
+```text
+Read node_modules/@wads.dev/i18n-ts/AI/ARCHITECTURE.md and then follow
+node_modules/@wads.dev/i18n-ts/AI/PROMPT_TRANSLATE_FILE.md for <source-file>.
+```
+
+These documents describe portable behavior. Repository instructions, `i18n.config.json` and existing code determine the actual paths and platform integration.

package/AI/PROMPT_ADD_LANG_TO_PROJECT.md

@@ -0,0 +1,27 @@
+# Add a language to a project
+
+Read `ARCHITECTURE.md` first.
+
+## Objective
+
+Add one locale while preserving the complete typed structure and the conventions of the consuming project.
+
+## Procedure
+
+1. Read `i18n.config.json`, the language catalog, root contract and every existing locale.
+2. Confirm the language key, display name, short identifier and standards-based locale identifier.
+3. Use the most complete existing locale as the structural reference.
+4. Create the new locale file in every configured translation group that has locale implementations.
+5. Preserve nesting, function signatures, tokens and renderable value shapes exactly.
+6. Translate all values with terminology consistent with the product. Do not leave source-language text disguised as a completed translation.
+7. Add the locale metadata and loader to the catalog using the existing pattern.
+8. Search for fixed language lists or locale-specific branches and update only those that should support the new locale.
+9. Run typecheck, tests and lint.
+
+## Completion checklist
+
+- [ ] Every configured translation group has the new locale where applicable.
+- [ ] The new locale satisfies the root and nested TypeScript contracts.
+- [ ] Catalog metadata and loader are complete.
+- [ ] Functions and tokens match every other locale.
+- [ ] No language whitelist unintentionally excludes the new locale.

package/AI/PROMPT_CREATE_TRANSLATION_KEY.md

@@ -0,0 +1,26 @@
+# Create translation keys
+
+Read `ARCHITECTURE.md` first.
+
+## Objective
+
+Add the requested translation paths to the correct typed contract and every supported locale.
+
+## Procedure
+
+1. Read `i18n.config.json` and map each requested path to its configured structural group.
+2. Search for an existing key with the same meaning before creating a duplicate.
+3. Inspect neighboring keys to preserve naming, ordering, terminology and value type.
+4. Add the key to the closest owning TypeScript contract.
+5. Implement the identical shape in every locale file belonging to that group.
+6. Use typed functions for interpolation and the host integration's typed render mechanism for rich content.
+7. Keep function parameters, token names and nesting identical across locales.
+8. Update consuming code if the requested change includes usage.
+9. Run typecheck, tests and lint.
+
+## Completion checklist
+
+- [ ] Each key belongs to the correct configured group.
+- [ ] The type contract and every locale expose the same shape.
+- [ ] Copy is meaningful in every language.
+- [ ] No duplicate semantic key or temporary placeholder remains.

package/AI/PROMPT_TRANSLATE_FILE.md

@@ -0,0 +1,25 @@
+# Move a source file's text to i18n
+
+Read `ARCHITECTURE.md` first.
+
+## Objective
+
+Replace human-facing literals in the requested source file with typed translations that follow the consuming project's existing runtime integration.
+
+## Procedure
+
+1. Read `i18n.config.json`, the target file and the nearest project architecture instructions.
+2. Determine the owning translation group from the configured levels and the file's product responsibility.
+3. Find all user-visible literals, including labels, validation messages, accessibility text and user-facing errors. Do not move protocol values, identifiers, test fixtures or debug-only logs.
+4. Search for reusable existing keys before creating new ones.
+5. Add missing keys to the owning contract and every locale, following `PROMPT_CREATE_TRANSLATION_KEY.md`.
+6. Replace literals using the runtime pattern already present in the project. Do not invent a new hook, provider or accessor.
+7. Model interpolation with typed functions and rich content with the existing typed render mechanism.
+8. Remove obsolete imports and run typecheck, tests and lint.
+
+## Completion checklist
+
+- [ ] No applicable user-facing literal remains in the target file.
+- [ ] Every new key exists with the same shape in every locale.
+- [ ] Existing runtime conventions were preserved.
+- [ ] Dynamic values remain typed and safe.

package/AI/PROMPT_UPDATE_TRANSLATION.md

@@ -0,0 +1,22 @@
+# Update translation values
+
+Read `ARCHITECTURE.md` first.
+
+## Objective
+
+Change existing copy in every locale while preserving its typed structure and semantic intent.
+
+## Procedure
+
+1. Resolve each requested key through `i18n.config.json` and confirm its current contract.
+2. Update every locale that implements the key.
+3. Preserve the value kind: strings remain strings; functions keep the same parameters; rich values keep the same token names and render contract.
+4. Translate the new intent consistently with each locale's terminology, punctuation and tone.
+5. Search for comments, tests or related copy that intentionally mirrors the old wording and update them when appropriate.
+6. Run typecheck, tests and lint.
+
+## Completion checklist
+
+- [ ] Every locale reflects the requested semantic change.
+- [ ] Function signatures, parameter order and token names are unchanged.
+- [ ] No applicable stale wording remains.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Wads.dev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,181 @@
+# @wads.dev/i18n-ts
+
+Framework-independent TypeScript foundations for strongly typed internationalization.
+
+`i18n-ts` gives a project one translation contract shared by every language, lazy language loading, a portable JSON bundle format and a machine-readable project configuration. It has no runtime dependencies and no React, DOM or application-specific coupling.
+
+> Status: `0.0.1-alpha.0`. Public APIs and JSON formats may change before `1.0.0`.
+
+## 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:
+
+- TypeScript verifies that locales implement compatible structures.
+- Dynamic translations keep the same function signature in every language.
+- Languages can be loaded lazily and their resulting trees are immutable.
+- 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.
+
+## Installation
+
+Install the current alpha explicitly:
+
+```sh
+npm install @wads.dev/i18n-ts@alpha
+```
+
+After a stable release:
+
+```sh
+npm install @wads.dev/i18n-ts
+```
+
+## Define a typed catalog
+
+Create the contract shared by all locales:
+
+```ts
+import type { Translation } from '@wads.dev/i18n-ts'
+
+export interface AppTranslation extends Translation {
+  commons: {
+    continue: string
+  }
+  cart: {
+    itemCount: (count: number) => string
+  }
+}
+```
+
+Implement it once per language:
+
+```ts
+import type { AppTranslation } from '../base.js'
+
+const en: AppTranslation = {
+  commons: { continue: 'Continue' },
+  cart: { itemCount: (count) => `${count} items` },
+}
+
+export default en
+```
+
+```ts
+import type { AppTranslation } from '../base.js'
+
+const pt: AppTranslation = {
+  commons: { continue: 'Continuar' },
+  cart: { itemCount: (count) => `${count} itens` },
+}
+
+export default pt
+```
+
+The compiler now catches missing keys, incompatible nested structures and different function parameters.
+
+## Register and load languages
+
+```ts
+import { loadLanguage, type AvailableLangs } from '@wads.dev/i18n-ts'
+import type { AppTranslation } from './base.js'
+
+const languages = {
+  en: {
+    name: 'English',
+    short: 'EN',
+    locale: 'en-US',
+    lang: () => import('./translations/en.js'),
+  },
+  pt: {
+    name: 'Português',
+    short: 'PT',
+    locale: 'pt-BR',
+    lang: () => import('./translations/pt.js'),
+  },
+} satisfies AvailableLangs<'en' | 'pt', AppTranslation>
+
+const selected = await loadLanguage(languages, 'en', 'pt-BR')
+selected.lang.commons.continue
+```
+
+`loadLanguage` selects an available language, loads it when necessary and deeply freezes the translation tree. Selection accepts an explicit language and otherwise falls back through the environment locale to the configured default.
+
+## 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`.
+
+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.
+
+See [Project configuration](./docs/CONFIGURATION.md) for the complete schema, replacers, aliases and path-resolution examples.
+
+## Export a portable bundle
+
+The bundle is a portable, JSON-safe snapshot of the complete translation catalog, including language metadata, values and `updatedAt`. It separates translation review from the source-code layout.
+
+```sh
+npx i18n-bundle \
+  --input src/i18n/index.ts \
+  --config i18n.config.json \
+  --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 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.
+
+See [Bundle and translation-review workflow](./docs/BUNDLE_WORKFLOW.md) for responsibilities, handoff stages and validation guidance.
+
+The input module must export `Langs`. The command requires TypeScript in the consuming project when the catalog is written in TypeScript. When `--config` is supplied, a normalized `i18n.config.json` is copied beside the generated bundle so a separately served editor can load it automatically.
+
+Bundle APIs are available separately:
+
+```ts
+import {
+  assertBundle,
+  parseBundle,
+  type I18nBundle,
+} from '@wads.dev/i18n-ts/bundle'
+```
+
+Functions inside translation trees are serialized as descriptors so editors can inspect them without executing application code.
+
+## AI agent guides
+
+The published package includes portable instructions under `AI/`. Projects can direct agents to these files instead of copying i18n instructions into every repository:
+
+```text
+node_modules/@wads.dev/i18n-ts/AI/ARCHITECTURE.md
+node_modules/@wads.dev/i18n-ts/AI/PROMPT_TRANSLATE_FILE.md
+node_modules/@wads.dev/i18n-ts/AI/PROMPT_CREATE_TRANSLATION_KEY.md
+node_modules/@wads.dev/i18n-ts/AI/PROMPT_UPDATE_TRANSLATION.md
+node_modules/@wads.dev/i18n-ts/AI/PROMPT_ADD_LANG_TO_PROJECT.md
+```
+
+The guides begin by reading the host repository instructions and `i18n.config.json`; they do not assume React or a fixed project layout.
+
+## Public entry points
+
+| Import | Responsibility |
+| --- | --- |
+| `@wads.dev/i18n-ts` | Runtime types and `loadLanguage`. |
+| `@wads.dev/i18n-ts/bundle` | Portable bundle types, validation and serialization. |
+| `@wads.dev/i18n-ts/config` | Project configuration types, defaults and normalization. |
+
+The root import deliberately excludes editor and CLI concerns.
+
+## Development
+
+```sh
+npm install
+npm run check
+npm run build
+npm pack --dry-run
+```
+
+The source is entirely TypeScript. The build produces ESM JavaScript and declaration files in `dist/`.
+
+## License
+
+MIT

package/dist/bundle/index.d.ts

@@ -0,0 +1,27 @@
+export declare const BUNDLE_FORMAT: "wads-i18n-bundle";
+export declare const BUNDLE_VERSION: 2;
+export type BundleFunction = {
+    $type: 'function';
+    source: string;
+};
+export type BundleValue = string | number | boolean | null | BundleFunction | BundleValue[] | BundleRecord;
+export type BundleRecord = {
+    [key: string]: BundleValue;
+};
+export type BundleLanguage = {
+    name: string;
+    short: string;
+    locale: string;
+    translations: BundleRecord;
+};
+export type I18nBundle = {
+    format: typeof BUNDLE_FORMAT;
+    version: typeof BUNDLE_VERSION;
+    updatedAt: number;
+    languages: Record<string, BundleLanguage>;
+};
+export declare function createBundle(languages?: I18nBundle['languages'], updatedAt?: number): I18nBundle;
+export declare function assertBundle(value: unknown): I18nBundle;
+export declare function withUpdatedAt(bundle: I18nBundle, updatedAt?: number): I18nBundle;
+export declare function parseBundle(text: string): I18nBundle;
+export declare function serializeBundleValue(value: unknown): BundleValue;

package/dist/bundle/index.js

@@ -0,0 +1,62 @@
+export const BUNDLE_FORMAT = 'wads-i18n-bundle';
+export const BUNDLE_VERSION = 2;
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+export function createBundle(languages = {}, updatedAt = Date.now()) {
+    return { format: BUNDLE_FORMAT, version: BUNDLE_VERSION, updatedAt, languages };
+}
+export function assertBundle(value) {
+    if (!isRecord(value))
+        throw new Error('The bundle must be a JSON object.');
+    if (value.format !== BUNDLE_FORMAT) {
+        throw new Error(`Invalid bundle format. Expected: ${BUNDLE_FORMAT}.`);
+    }
+    if (value.version !== BUNDLE_VERSION) {
+        throw new Error(`Unsupported bundle version: ${String(value.version)}.`);
+    }
+    if (!Number.isSafeInteger(value.updatedAt) || Number(value.updatedAt) < 0) {
+        throw new Error('The bundle must contain a valid numeric updatedAt value.');
+    }
+    if (!isRecord(value.languages)) {
+        throw new Error('The bundle must contain a languages object.');
+    }
+    for (const [key, language] of Object.entries(value.languages)) {
+        if (!isRecord(language) || !isRecord(language.translations)) {
+            throw new Error(`Language "${key}" must contain a translations object.`);
+        }
+    }
+    return value;
+}
+export function withUpdatedAt(bundle, updatedAt = Date.now()) {
+    const validBundle = assertBundle(bundle);
+    return {
+        ...validBundle,
+        updatedAt: Math.max(updatedAt, validBundle.updatedAt + 1),
+    };
+}
+export function parseBundle(text) {
+    try {
+        return assertBundle(JSON.parse(text));
+    }
+    catch (error) {
+        if (error instanceof SyntaxError) {
+            throw new Error('The provided content is not valid JSON.');
+        }
+        throw error;
+    }
+}
+export function serializeBundleValue(value) {
+    if (typeof value === 'function') {
+        return { $type: 'function', source: Function.prototype.toString.call(value) };
+    }
+    if (Array.isArray(value))
+        return value.map(serializeBundleValue);
+    if (isRecord(value)) {
+        return Object.fromEntries(Object.entries(value).map(([key, nestedValue]) => [key, serializeBundleValue(nestedValue)]));
+    }
+    if (value === null || typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+        return value;
+    }
+    throw new Error(`Unsupported bundle value type: ${typeof value}.`);
+}

package/dist/cli/exportBundle.d.ts

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+type ExportOptions = {
+    input: string;
+    output: string;
+    config?: string;
+    help?: boolean;
+};
+export declare function exportBundle({ input, output, config }: Pick<ExportOptions, 'input' | 'output' | 'config'>): Promise<{
+    outputPath: string;
+    configOutputPath: string | undefined;
+    languageCount: number;
+}>;
+export {};

package/dist/cli/exportBundle.js

@@ -0,0 +1,155 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+import { createBundle, serializeBundleValue } from '../bundle/index.js';
+import { normalizeProjectConfig, PROJECT_CONFIG_FORMAT, PROJECT_CONFIG_VERSION, } from '../config/index.js';
+const require = createRequire(import.meta.url);
+const projectDirectory = process.cwd();
+function loadTypeScript() {
+    try {
+        return require('typescript');
+    }
+    catch {
+        throw new Error('i18n-bundle requires TypeScript in the consuming project. Install it with "npm install --save-dev typescript".');
+    }
+}
+function parseArguments(argv) {
+    const options = {
+        input: 'src/shared/i18n/translations/index.ts',
+        output: 'i18n.bundle.json',
+    };
+    for (let index = 0; index < argv.length; index += 1) {
+        const argument = argv[index];
+        const value = argv[index + 1];
+        if (argument === '--input' && value) {
+            options.input = value;
+            index += 1;
+        }
+        else if (argument === '--output' && value) {
+            options.output = value;
+            index += 1;
+        }
+        else if (argument === '--config' && value) {
+            options.config = value;
+            index += 1;
+        }
+        else if (argument === '--help' || argument === '-h') {
+            return { ...options, help: true };
+        }
+        else {
+            throw new Error(`Unknown or incomplete argument: ${argument}`);
+        }
+    }
+    return options;
+}
+function printHelp() {
+    console.log(`Exports an i18n catalog as a standalone JSON bundle.
+
+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)
+  --output        Output JSON file (default: i18n.bundle.json)
+  --config        Optional i18n.config.json copied beside the output bundle
+  --help, -h      Show this help`);
+}
+function readTypeScriptConfiguration(ts) {
+    const configPath = ts.findConfigFile(projectDirectory, ts.sys.fileExists, 'tsconfig.json');
+    if (!configPath)
+        return {};
+    const configFile = ts.readConfigFile(configPath, ts.sys.readFile);
+    if (configFile.error) {
+        throw new Error(ts.flattenDiagnosticMessageText(configFile.error.messageText, '\n'));
+    }
+    return ts.parseJsonConfigFileContent(configFile.config, ts.sys, projectDirectory).options;
+}
+function createTypeScriptLoader(ts, compilerOptions) {
+    const cache = new Map();
+    function resolveProjectModule(specifier, containingFile) {
+        const resolution = ts.resolveModuleName(specifier, containingFile, compilerOptions, ts.sys).resolvedModule;
+        if (!resolution || resolution.isExternalLibraryImport)
+            return undefined;
+        return resolution.resolvedFileName;
+    }
+    function load(filePath) {
+        const absolutePath = path.resolve(filePath);
+        const cached = cache.get(absolutePath);
+        if (cached)
+            return cached.exports;
+        const source = fs.readFileSync(absolutePath, 'utf8');
+        const compiled = ts.transpileModule(source, {
+            compilerOptions: {
+                ...compilerOptions,
+                module: ts.ModuleKind.CommonJS,
+                target: ts.ScriptTarget.ES2022,
+                esModuleInterop: true,
+            },
+            fileName: absolutePath,
+        }).outputText;
+        const module = { exports: {} };
+        cache.set(absolutePath, module);
+        const localRequire = (specifier) => {
+            const resolved = resolveProjectModule(specifier, absolutePath);
+            return resolved ? load(resolved) : require(specifier);
+        };
+        const execute = new Function('exports', 'require', 'module', '__filename', '__dirname', compiled);
+        execute(module.exports, localRequire, module, absolutePath, path.dirname(absolutePath));
+        return module.exports;
+    }
+    return load;
+}
+export async function exportBundle({ input, output, config }) {
+    const ts = loadTypeScript();
+    const loadProjectTypeScript = createTypeScriptLoader(ts, readTypeScriptConfiguration(ts));
+    const translationsIndex = loadProjectTypeScript(path.resolve(projectDirectory, input));
+    const langs = translationsIndex.Langs;
+    if (!langs || typeof langs !== 'object') {
+        throw new Error('The provided catalog must export Langs.');
+    }
+    const languages = Object.fromEntries(await Promise.all(Object.entries(langs).map(async ([key, info]) => {
+        const module = await info.lang();
+        const translations = module.default ?? module;
+        return [key, {
+                name: info.name,
+                short: info.short,
+                locale: info.locale,
+                translations: serializeBundleValue(translations),
+            }];
+    })));
+    const bundle = createBundle(languages);
+    const outputPath = path.resolve(projectDirectory, output);
+    fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+    fs.writeFileSync(outputPath, `${JSON.stringify(bundle, null, 2)}\n`);
+    let configOutputPath;
+    if (config) {
+        const configValue = JSON.parse(fs.readFileSync(path.resolve(projectDirectory, config), 'utf8'));
+        if (configValue.format !== PROJECT_CONFIG_FORMAT || configValue.version !== PROJECT_CONFIG_VERSION) {
+            throw new Error(`Invalid project configuration. Expected ${PROJECT_CONFIG_FORMAT} version ${PROJECT_CONFIG_VERSION}.`);
+        }
+        configOutputPath = path.join(path.dirname(outputPath), 'i18n.config.json');
+        fs.writeFileSync(configOutputPath, `${JSON.stringify(normalizeProjectConfig(configValue), null, 2)}\n`);
+    }
+    return { outputPath, configOutputPath, languageCount: Object.keys(languages).length };
+}
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+    try {
+        const options = parseArguments(process.argv.slice(2));
+        if (options.help) {
+            printHelp();
+            process.exit(0);
+        }
+        const result = await exportBundle(options);
+        console.log(`i18n bundle created at ${result.outputPath}`);
+        if (result.configOutputPath)
+            console.log(`i18n project configuration copied to ${result.configOutputPath}`);
+        console.log(`${result.languageCount} languages exported.`);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(`Could not export the i18n bundle: ${message}`);
+        process.exit(1);
+    }
+}

package/dist/config/index.d.ts

@@ -0,0 +1,29 @@
+export declare const PROJECT_CONFIG_FORMAT: "wads-i18n-project-config";
+export declare const PROJECT_CONFIG_VERSION: 1;
+export type I18nPathReplacement = string | null | I18nPathReplacer;
+export type I18nPathReplacer = {
+    [key: string]: I18nPathReplacement;
+};
+export type I18nLevelImport = {
+    path: string;
+    valueReplacer?: I18nPathReplacer;
+    fullReplacer?: I18nPathReplacer;
+};
+export type I18nProjectConfig = {
+    format: typeof PROJECT_CONFIG_FORMAT;
+    version: typeof PROJECT_CONFIG_VERSION;
+    levelCount: number;
+    levelNames: string;
+    levelImports: I18nLevelImport[];
+    importAliases: Record<string, string>;
+    translationsDirectory: string;
+    languageFileTemplate: string;
+    languageReplacer: Record<string, string>;
+};
+export declare function getDefaultLevelImport(levelIndex: number): I18nLevelImport;
+export declare function createDefaultProjectConfig(): I18nProjectConfig;
+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;
+export declare function flattenPathReplacer(replacer: I18nPathReplacer | undefined, parentPath?: string): Record<string, string | null>;
+export declare function resolveImportAlias(path: string, aliases: Record<string, string>): string;

package/dist/config/index.js

@@ -0,0 +1,109 @@
+export const PROJECT_CONFIG_FORMAT = 'wads-i18n-project-config';
+export const PROJECT_CONFIG_VERSION = 1;
+export function getDefaultLevelImport(levelIndex) {
+    if (levelIndex === 0)
+        return { path: '@/shared' };
+    if (levelIndex === 1)
+        return { path: '@/modules/{value}' };
+    if (levelIndex === 2)
+        return { path: 'features/{value}' };
+    return { path: `level-${levelIndex}/{value}` };
+}
+export function createDefaultProjectConfig() {
+    return {
+        format: PROJECT_CONFIG_FORMAT,
+        version: PROJECT_CONFIG_VERSION,
+        levelCount: 2,
+        levelNames: 'Module, Feature',
+        levelImports: [
+            getDefaultLevelImport(0),
+            getDefaultLevelImport(1),
+            getDefaultLevelImport(2),
+        ],
+        importAliases: { '@/': 'src/' },
+        translationsDirectory: 'i18n',
+        languageFileTemplate: '{language}.ts',
+        languageReplacer: {},
+    };
+}
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function normalizeReplacer(value) {
+    if (!isRecord(value))
+        return {};
+    const result = {};
+    Object.entries(value).forEach(([key, replacement]) => {
+        if (replacement === null || typeof replacement === 'string')
+            result[key] = replacement;
+        else if (isRecord(replacement))
+            result[key] = normalizeReplacer(replacement);
+    });
+    return result;
+}
+function normalizeStringRecord(value) {
+    if (!isRecord(value))
+        return {};
+    return Object.fromEntries(Object.entries(value)
+        .filter((entry) => typeof entry[1] === 'string')
+        .map(([key, item]) => [key, item.trim()]));
+}
+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 : [];
+    return {
+        format: PROJECT_CONFIG_FORMAT,
+        version: PROJECT_CONFIG_VERSION,
+        levelCount,
+        levelNames: typeof value.levelNames === 'string' ? value.levelNames : defaults.levelNames,
+        levelImports: Array.from({ length: levelCount + 1 }, (_, index) => {
+            const input = isRecord(inputImports[index]) ? inputImports[index] : {};
+            const fallback = getDefaultLevelImport(index);
+            return {
+                path: typeof input.path === 'string' && input.path.trim() ? input.path.trim() : fallback.path,
+                valueReplacer: normalizeReplacer(input.valueReplacer),
+                fullReplacer: normalizeReplacer(input.fullReplacer),
+            };
+        }),
+        importAliases: {
+            ...defaults.importAliases,
+            ...normalizeStringRecord(value.importAliases),
+        },
+        translationsDirectory: typeof value.translationsDirectory === 'string' && value.translationsDirectory.trim()
+            ? value.translationsDirectory.trim()
+            : defaults.translationsDirectory,
+        languageFileTemplate: typeof value.languageFileTemplate === 'string' && value.languageFileTemplate.trim()
+            ? value.languageFileTemplate.trim()
+            : defaults.languageFileTemplate,
+        languageReplacer: normalizeStringRecord(value.languageReplacer),
+    };
+}
+export function getLevelName(config, level) {
+    if (level === 0)
+        return 'Root';
+    const names = config.levelNames.split(',').map((name) => name.trim()).filter(Boolean);
+    return names[level - 1] || `Level ${level}`;
+}
+export function getLevelImport(config, levelIndex) {
+    return config.levelImports[levelIndex] || getDefaultLevelImport(levelIndex);
+}
+export function flattenPathReplacer(replacer, parentPath = '') {
+    const flattened = {};
+    Object.entries(replacer || {}).forEach(([key, value]) => {
+        const fullKey = parentPath ? `${parentPath}.${key}` : key;
+        if (value === null || typeof value === 'string')
+            flattened[fullKey] = value;
+        else
+            Object.assign(flattened, flattenPathReplacer(value, fullKey));
+    });
+    return flattened;
+}
+export function resolveImportAlias(path, aliases) {
+    const alias = Object.keys(aliases)
+        .filter((candidate) => path.startsWith(candidate))
+        .sort((left, right) => right.length - left.length)[0];
+    if (!alias)
+        return path;
+    return `${aliases[alias]}${path.slice(alias.length)}`;
+}

package/dist/runtime/index.d.ts

@@ -0,0 +1,2 @@
+export { loadLanguage } from './language.js';
+export type { AsyncTranslation, AvailableLangs, DeepReadonly, LangInfo, LoadedLangInfo, Translation, TranslationItems, TranslationRender, TranslationResult, TranslationTokenRender, TranslationTokens, TranslationTokensRender, TranslationWithParams, } from './types.js';

package/dist/runtime/index.js

@@ -0,0 +1 @@
+export { loadLanguage } from './language.js';

package/dist/runtime/language.d.ts

@@ -0,0 +1,2 @@
+import type { AvailableLangs, LoadedLangInfo, Translation } from './types.js';
+export declare function loadLanguage<A extends string, T extends Translation>(availableLangs: AvailableLangs<A, T>, defaultLang: A, language?: A | string): Promise<LoadedLangInfo<T>>;

package/dist/runtime/language.js

@@ -0,0 +1,31 @@
+function detectLanguage() {
+    if (typeof navigator !== 'undefined' && typeof navigator.language === 'string')
+        return navigator.language;
+    if (typeof Intl !== 'undefined')
+        return Intl.DateTimeFormat().resolvedOptions().locale;
+    return undefined;
+}
+export async function loadLanguage(availableLangs, defaultLang, language) {
+    if (!language || !availableLangs[language]) {
+        const browserLang = (detectLanguage() || '').replace('-', '').toLowerCase();
+        const languageKeys = Object.keys(availableLangs).map((key) => key.toLowerCase());
+        language = languageKeys.find((key) => key === browserLang)
+            || languageKeys.find((key) => browserLang.startsWith(key))
+            || defaultLang;
+    }
+    const info = availableLangs[language];
+    const lang = typeof info.lang === 'function'
+        ? await info.lang().then(({ default: loadedLang }) => loadedLang)
+        : info.lang;
+    return { ...info, lang: deepFreeze(lang) };
+}
+function deepFreeze(value) {
+    Object.freeze(value);
+    Object.getOwnPropertyNames(value).forEach((property) => {
+        const nestedValue = value[property];
+        if (nestedValue && (typeof nestedValue === 'object' || typeof nestedValue === 'function') && !Object.isFrozen(nestedValue)) {
+            deepFreeze(nestedValue);
+        }
+    });
+    return value;
+}

package/dist/runtime/types.d.ts

@@ -0,0 +1,27 @@
+export type TranslationResult<T> = unknown;
+export type TranslationTokens<T extends string> = Record<T, string>;
+export type TranslationTokenRender<T> = (text: string, token?: T) => TranslationResult<T>;
+export type TranslationTokensRender<T extends string> = {
+    default?: TranslationTokenRender<T>;
+} & Record<T, TranslationTokenRender<T>>;
+export type TranslationRender<Tokens extends string = string> = (customTokens?: TranslationTokens<Tokens>, customRenders?: TranslationTokensRender<Tokens>) => TranslationResult<Tokens>;
+export type TranslationItems = string[];
+export type TranslationWithParams = (...args: any[]) => string;
+export interface Translation {
+    [key: string]: string | Translation | Translation[] | TranslationItems | TranslationWithParams | TranslationRender<any>;
+}
+export type ModuleReturn<T extends Translation> = {
+    default: T;
+};
+export type AsyncTranslation<T extends Translation> = () => Promise<ModuleReturn<T>>;
+export type LangInfo<T extends Translation, LT = T | AsyncTranslation<T>> = {
+    lang: LT;
+    locale: string;
+    name: string;
+    short: string;
+};
+export type AvailableLangs<A extends string, T extends Translation> = Record<A, LangInfo<T>>;
+export type DeepReadonly<T> = T extends TranslationWithParams | TranslationRender ? T : {
+    readonly [K in keyof T]: DeepReadonly<T[K]>;
+};
+export type LoadedLangInfo<T extends Translation> = LangInfo<T, DeepReadonly<T>>;

package/dist/runtime/types.js

@@ -0,0 +1 @@
+export {};

package/docs/BUNDLE_WORKFLOW.md

@@ -0,0 +1,67 @@
+# Bundle and translation-review workflow
+
+An i18n bundle is a portable JSON snapshot of every configured language. It contains language metadata, the full translation tree and an `updatedAt` timestamp without exposing the repository's TypeScript module layout.
+
+## What the bundle solves
+
+Large applications often distribute translations across root, module and feature directories. That structure is useful for developers but inconvenient for translators and reviewers. A bundle provides one transport format that can be:
+
+- opened in `@wads.dev/i18n-editor`;
+- sent to an internal localization team or external translator;
+- archived as a review artifact;
+- compared with a newer project export;
+- returned to developers without manually editing many source files.
+
+Functions are represented as safe descriptors. Tools can inspect their signatures and bodies without executing application code.
+
+## Export from the project
+
+```sh
+npx i18n-bundle \
+  --input src/i18n/index.ts \
+  --config i18n.config.json \
+  --output i18n.bundle.json
+```
+
+The catalog module must export `Langs`. When `--config` is supplied, the normalized configuration is copied beside the bundle for the Editor.
+
+## 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 intended collaboration cycle is:
+
+1. A developer exports the current bundle and configuration.
+2. The translation team reviews or changes the portable bundle.
+3. The reviewed bundle returns to development.
+4. Editor/CLI tooling resolves every key through the configuration and regenerates the TypeScript translation tree.
+5. Developers inspect the generated Git diff, run validation and merge normally.
+
+## Why regenerate instead of patching files
+
+Deterministic regeneration avoids teaching the importer every possible formatting style or trying to perform fragile textual edits. Translation files should contain only generated translation structures so they can be recreated from the reviewed bundle.
+
+Git remains the safety layer:
+
+- unexpected moves are visible;
+- removed or duplicated keys are reviewable;
+- formatting and structural changes are explicit;
+- typecheck and tests validate the generated result;
+- reverting a problematic import remains straightforward.
+
+## Current alpha status
+
+Available now:
+
+- TypeScript catalog to portable bundle export;
+- normalized project configuration copied beside the bundle;
+- Editor visualization, grouping and in-memory text/key editing;
+- export-plan preview showing the files implied by the configuration.
+
+Still to be implemented:
+
+- importing a reviewed bundle back into generated TypeScript files;
+- deterministic file templates for contracts, indexes and locales;
+- ZIP export/import and conflict-resolution workflows.
+
+The documentation distinguishes this target workflow from the features already shipped so teams can adopt the bundle format without assuming source regeneration is complete.

package/docs/CONFIGURATION.md

@@ -0,0 +1,190 @@
+# Project configuration
+
+`i18n.config.json` is the portable description of how a translation object maps to a repository. Keep it at the project root and commit it with the source code.
+
+The application runtime does not read this file. Its primary consumers are:
+
+- AI agents that need to locate contracts, modules, features and locale files safely;
+- `@wads.dev/i18n-editor`, which groups translations and previews regenerated files;
+- CLI automation that converts between a portable bundle and the project's source layout.
+
+## Complete example
+
+```json
+{
+  "format": "wads-i18n-project-config",
+  "version": 1,
+  "levelCount": 2,
+  "levelNames": "Module, Feature",
+  "levelImports": [
+    { "path": "@/shared" },
+    {
+      "path": "@/modules/{value}",
+      "fullReplacer": {
+        "commons": null,
+        "designSystemPreview": "@design/preview",
+        "firebase": "@/shared/config/firebase"
+      }
+    },
+    {
+      "path": "features/{value}",
+      "valueReplacer": {
+        "logged": {
+          "hubNews": "hub-new",
+          "openStrategy": "open-strategy"
+        }
+      },
+      "fullReplacer": {
+        "logged.navigation": null
+      }
+    }
+  ],
+  "importAliases": {
+    "@design/": "src/shared/design-system/",
+    "@/": "src/"
+  },
+  "translationsDirectory": "i18n",
+  "languageFileTemplate": "{language}.ts",
+  "languageReplacer": {
+    "pt": "ptBR"
+  }
+}
+```
+
+JSON does not support comments. Keep explanations in documentation rather than adding comments to the real configuration file.
+
+## Top-level fields
+
+| Field | Type | Meaning |
+| --- | --- | --- |
+| `format` | string | Contract identifier. Currently `wads-i18n-project-config`. |
+| `version` | number | Configuration schema version. Currently `1`. |
+| `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. |
+| `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. |
+
+## Root and structural levels
+
+`levelImports[0]` is always the root translation location. It consumes no segment of the translation key.
+
+Entries `1...levelCount` consume one segment each. Given the key:
+
+```text
+shell.authentication.login.title
+```
+
+and two configured levels:
+
+- `shell` is level 1 (`Module`);
+- `authentication` is level 2 (`Feature`);
+- `login.title` remains the key inside the feature files.
+
+An aliased path is rooted at the project. An unaliased path is appended to the previously resolved level. Therefore:
+
+```json
+[
+  { "path": "@/shared" },
+  { "path": "@/modules/{value}" },
+  { "path": "features/{value}" }
+]
+```
+
+resolves the example to:
+
+```text
+src/modules/shell/features/authentication/i18n/{language}.ts
+```
+
+## Value replacer
+
+`valueReplacer` changes only the value inserted into `{value}`. Use it when object keys and existing folder names differ by casing, separators or legacy naming.
+
+These forms are equivalent:
+
+```json
+{ "logged.hubNews": "hub-new" }
+```
+
+```json
+{ "logged": { "hubNews": "hub-new" } }
+```
+
+The full object path makes the rule unambiguous even when two modules contain features with the same name.
+
+## Full replacer
+
+`fullReplacer` overrides normal resolution for a complete object path.
+
+A string redirects the subtree:
+
+```json
+{ "designSystemPreview": "@design/preview" }
+```
+
+`null` stops descending and keeps the subtree in its parent translation files:
+
+```json
+{ "logged.navigation": null }
+```
+
+This allows a nested object to remain in `src/modules/logged/i18n` even though the project normally treats the second segment as a feature.
+
+Like `valueReplacer`, it accepts dotted keys and nested objects.
+
+## Import aliases
+
+Aliases map configuration paths to project-relative directories. The longest matching prefix wins.
+
+```json
+{
+  "@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/...`.
+
+## Language filenames
+
+`languageFileTemplate` controls the generated filename:
+
+```json
+{ "languageFileTemplate": "{language}.ts" }
+```
+
+When a catalog key differs from the existing filename, use `languageReplacer`:
+
+```json
+{ "languageReplacer": { "pt": "ptBR" } }
+```
+
+The catalog language `pt` then generates `ptBR.ts`.
+
+## Generated destinations
+
+For every resolved owner, the Editor export plan currently includes:
+
+```text
+i18n/base.ts
+i18n/index.ts
+i18n/{language}.ts
+```
+
+The preview updates immediately when levels, paths, aliases or replacers change.
+
+## TypeScript API
+
+Tooling can consume the same normalized contract:
+
+```ts
+import {
+  normalizeProjectConfig,
+  type I18nProjectConfig,
+} from '@wads.dev/i18n-ts/config'
+```
+
+Always normalize external JSON before resolving paths.

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@wads.dev/i18n-ts",
+  "version": "0.0.1-alpha.0",
+  "description": "Dependency-free typed i18n contracts, bundle tools and language loading.",
+  "license": "MIT",
+  "author": {
+    "name": "Wads.dev",
+    "url": "https://github.com/wads-dev"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wads-dev/i18n-ts.git"
+  },
+  "homepage": "https://github.com/wads-dev/i18n-ts#readme",
+  "bugs": {
+    "url": "https://github.com/wads-dev/i18n-ts/issues"
+  },
+  "keywords": [
+    "i18n",
+    "internationalization",
+    "typescript",
+    "translations"
+  ],
+  "type": "module",
+  "files": [
+    "AI",
+    "docs",
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "node ./scripts/clean-dist.mjs && tsc --project tsconfig.build.json",
+    "check": "tsc --project tsconfig.check.json --noEmit",
+    "prepack": "npm run check && npm run build"
+  },
+  "bin": {
+    "i18n-bundle": "./dist/cli/exportBundle.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/runtime/index.d.ts",
+      "import": "./dist/runtime/index.js"
+    },
+    "./bundle": {
+      "types": "./dist/bundle/index.d.ts",
+      "import": "./dist/bundle/index.js"
+    },
+    "./config": {
+      "types": "./dist/config/index.d.ts",
+      "import": "./dist/config/index.js"
+    }
+  },
+  "peerDependencies": {
+    "typescript": ">=5"
+  },
+  "peerDependenciesMeta": {
+    "typescript": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^6.0.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}