# davlet42/ai18n architecture

> Architecture diagram of the GitHub repository davlet42/ai18n, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/davlet42/ai18n
- Repository: https://github.com/davlet42/ai18n

## Overview

i18n-agent is a CLI for managing source and target locale files: it plans translations against a committed lockfile, sends batches through a configurable agent/provider, validates results, and writes targets without overwriting human-owned values. It also imports native locale formats, checks drift and Android structure, and exports web, Android, iOS, TypeScript-key, or bundle outputs. The principal flow is documented in the README and supported by the sync and translation excerpts; unsampled command internals and integrations are not expanded beyond documented relationships.

Main entry points: [`src/sync.ts`](https://github.com/davlet42/ai18n/blob/main/src/sync.ts) (Sync orchestrator), [`src/commands/export.ts`](https://github.com/davlet42/ai18n/blob/main/src/commands/export.ts) (Export command), [`src/validators/android-check.ts`](https://github.com/davlet42/ai18n/blob/main/src/validators/android-check.ts) (Android checks), [`src/translate-batch.ts`](https://github.com/davlet42/ai18n/blob/main/src/translate-batch.ts) (Translation and guards)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["CLI workflows"]
  node_cli["CLI entry<br/>[cli.ts]"]
  node_config["Project config<br/>[config.ts]"]
  node_translate_cmd["Translate command<br/>[translate.ts]"]
  node_import_cmd["Import command<br/>[import.ts]"]
  node_check_cmd["Check command<br/>[check.ts]"]
  node_status_cmd["Status command<br/>[status.ts]"]
  node_report_cmd["Report command<br/>[report.ts]"]
end

subgraph group_translation["Translation engine"]
  node_sync["Sync orchestrator<br/>[sync.ts]"]
  node_planner["Change planner<br/>[planner.ts]"]
  node_lockfile["Ownership lockfile<br/>[lockfile.ts]"]
  node_context["Hints and glossary"]
  node_batch["Translation and guards<br/>[translate-batch.ts]"]
  node_provider["Provider transport"]
  node_metrics["Run metrics<br/>[metrics.ts]"]
end

subgraph group_formats["Locale formats"]
  node_locale_io["Locale file IO<br/>[locale-files.ts]"]
  node_android_import["Android importer"]
  node_ios_import["iOS importer"]
  node_android_check["Android checks<br/>[android-check.ts]"]
  node_plural_check["Plural validation<br/>[cldr-plural.ts]"]
  node_placeholder_check["Placeholder validation<br/>[placeholder-set.ts]"]
  node_markup["Android markup rules<br/>[android-markup.ts]"]
end

subgraph group_delivery["Export and delivery"]
  node_export_cmd["Export command<br/>[export.ts]"]
  node_android_export["Android resources<br/>[android.ts]"]
  node_ios_export["iOS catalog<br/>[xcstrings.ts]"]
  node_simple_export["Web and TS output<br/>[simple.ts]"]
  node_transform["Shared format transforms<br/>[transform.ts]"]
  node_bundle["Static bundle<br/>[bundle.ts]"]
  node_nest["Nest delivery module<br/>[index.ts]"]
end

node_user(("Project user"))

node_user -->|"runs commands"| node_cli
node_cli -.->|"dispatches"| node_translate_cmd
node_translate_cmd -->|"loads settings"| node_config
node_translate_cmd -->|"runs sync"| node_sync
node_sync -->|"plans changes"| node_planner
node_sync -->|"reads and writes"| node_locale_io
node_sync -->|"tracks ownership"| node_lockfile
node_sync -->|"loads guidance"| node_context
node_sync -->|"creates transport"| node_provider
node_sync -->|"translates batches"| node_batch
node_sync -->|"records runs"| node_metrics
node_batch -->|"validates plurals"| node_plural_check
node_batch -->|"validates arguments"| node_placeholder_check
node_batch -->|"checks markup"| node_markup
node_plural_check -->|"parses ICU"| node_transform
node_import_cmd -->|"loads settings"| node_config
node_import_cmd -->|"imports Android"| node_android_import
node_import_cmd -->|"imports iOS"| node_ios_import
node_android_import -->|"writes locales"| node_locale_io
node_ios_import -->|"writes locales"| node_locale_io
node_check_cmd -->|"loads settings"| node_config
node_check_cmd -->|"checks Android"| node_android_check
node_status_cmd -->|"checks structure"| node_android_check
node_android_check -->|"validates plurals"| node_plural_check
node_android_check -->|"validates format args"| node_placeholder_check
node_android_check -->|"validates markup"| node_markup
node_report_cmd -.->|"reports metrics"| node_metrics
node_export_cmd -->|"loads settings"| node_config
node_export_cmd -->|"reads locales"| node_locale_io
node_export_cmd -->|"emits Android"| node_android_export
node_export_cmd -->|"emits catalog"| node_ios_export
node_export_cmd -->|"emits web output"| node_simple_export
node_export_cmd -->|"builds bundle"| node_bundle
node_android_export -->|"converts placeholders"| node_transform
node_ios_export -->|"converts placeholders"| node_transform
node_user -->|"requests export"| node_export_cmd
node_user -->|"requests import"| node_import_cmd
node_user -->|"checks drift"| node_check_cmd
node_user -->|"requests status"| node_status_cmd
node_bundle -.->|"serves bundle"| node_nest

click node_cli "https://github.com/davlet42/ai18n/blob/main/src/cli.ts"
click node_config "https://github.com/davlet42/ai18n/blob/main/src/config.ts"
click node_translate_cmd "https://github.com/davlet42/ai18n/blob/main/src/commands/translate.ts"
click node_import_cmd "https://github.com/davlet42/ai18n/blob/main/src/commands/import.ts"
click node_check_cmd "https://github.com/davlet42/ai18n/blob/main/src/commands/check.ts"
click node_status_cmd "https://github.com/davlet42/ai18n/blob/main/src/commands/status.ts"
click node_report_cmd "https://github.com/davlet42/ai18n/blob/main/src/commands/report.ts"
click node_sync "https://github.com/davlet42/ai18n/blob/main/src/sync.ts"
click node_planner "https://github.com/davlet42/ai18n/blob/main/src/planner.ts"
click node_lockfile "https://github.com/davlet42/ai18n/blob/main/src/lockfile.ts"
click node_context "https://github.com/davlet42/ai18n/blob/main/src/context-glossary.ts"
click node_batch "https://github.com/davlet42/ai18n/blob/main/src/translate-batch.ts"
click node_provider "https://github.com/davlet42/ai18n/blob/main/src/translate-provider.ts"
click node_metrics "https://github.com/davlet42/ai18n/blob/main/src/metrics.ts"
click node_locale_io "https://github.com/davlet42/ai18n/blob/main/src/locale-files.ts"
click node_android_import "https://github.com/davlet42/ai18n/blob/main/src/importers/android-xml-import.ts"
click node_ios_import "https://github.com/davlet42/ai18n/blob/main/src/importers/xcstrings-import.ts"
click node_android_check "https://github.com/davlet42/ai18n/blob/main/src/validators/android-check.ts"
click node_plural_check "https://github.com/davlet42/ai18n/blob/main/src/validators/cldr-plural.ts"
click node_placeholder_check "https://github.com/davlet42/ai18n/blob/main/src/validators/placeholder-set.ts"
click node_markup "https://github.com/davlet42/ai18n/blob/main/src/android-markup.ts"
click node_export_cmd "https://github.com/davlet42/ai18n/blob/main/src/commands/export.ts"
click node_android_export "https://github.com/davlet42/ai18n/blob/main/src/exporters/android.ts"
click node_ios_export "https://github.com/davlet42/ai18n/blob/main/src/exporters/xcstrings.ts"
click node_simple_export "https://github.com/davlet42/ai18n/blob/main/src/exporters/simple.ts"
click node_transform "https://github.com/davlet42/ai18n/blob/main/src/exporters/transform.ts"
click node_bundle "https://github.com/davlet42/ai18n/blob/main/src/bundle.ts"
click node_nest "https://github.com/davlet42/ai18n/blob/main/packages/nest/src/index.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_config,node_translate_cmd,node_import_cmd,node_check_cmd,node_status_cmd,node_report_cmd,node_user toneBlue
class node_sync,node_planner,node_lockfile,node_context,node_batch,node_provider,node_metrics toneAmber
class node_locale_io,node_android_import,node_ios_import,node_android_check,node_plural_check,node_placeholder_check,node_markup toneMint
class node_export_cmd,node_android_export,node_ios_export,node_simple_export,node_transform,node_bundle,node_nest toneRose
```

## Components

### CLI workflows

- [CLI entry](https://github.com/davlet42/ai18n/blob/main/src/cli.ts): `src/cli.ts`
- [Project config](https://github.com/davlet42/ai18n/blob/main/src/config.ts): `src/config.ts`
- [Translate command](https://github.com/davlet42/ai18n/blob/main/src/commands/translate.ts): `src/commands/translate.ts`
- [Import command](https://github.com/davlet42/ai18n/blob/main/src/commands/import.ts): `src/commands/import.ts`
- [Check command](https://github.com/davlet42/ai18n/blob/main/src/commands/check.ts): `src/commands/check.ts`
- [Status command](https://github.com/davlet42/ai18n/blob/main/src/commands/status.ts): `src/commands/status.ts`
- [Report command](https://github.com/davlet42/ai18n/blob/main/src/commands/report.ts): `src/commands/report.ts`

### Translation engine

- [Sync orchestrator](https://github.com/davlet42/ai18n/blob/main/src/sync.ts): `src/sync.ts`
- [Change planner](https://github.com/davlet42/ai18n/blob/main/src/planner.ts): `src/planner.ts`
- [Ownership lockfile](https://github.com/davlet42/ai18n/blob/main/src/lockfile.ts): `src/lockfile.ts`
- [Hints and glossary](https://github.com/davlet42/ai18n/blob/main/src/context-glossary.ts): `src/context-glossary.ts`
- [Translation and guards](https://github.com/davlet42/ai18n/blob/main/src/translate-batch.ts): `src/translate-batch.ts`
- [Provider transport](https://github.com/davlet42/ai18n/blob/main/src/translate-provider.ts): `src/translate-provider.ts`
- [Run metrics](https://github.com/davlet42/ai18n/blob/main/src/metrics.ts): `src/metrics.ts`

### Locale formats

- [Locale file IO](https://github.com/davlet42/ai18n/blob/main/src/locale-files.ts): `src/locale-files.ts`
- [Android importer](https://github.com/davlet42/ai18n/blob/main/src/importers/android-xml-import.ts): `src/importers/android-xml-import.ts`
- [iOS importer](https://github.com/davlet42/ai18n/blob/main/src/importers/xcstrings-import.ts): `src/importers/xcstrings-import.ts`
- [Android checks](https://github.com/davlet42/ai18n/blob/main/src/validators/android-check.ts): `src/validators/android-check.ts`
- [Plural validation](https://github.com/davlet42/ai18n/blob/main/src/validators/cldr-plural.ts): `src/validators/cldr-plural.ts`
- [Placeholder validation](https://github.com/davlet42/ai18n/blob/main/src/validators/placeholder-set.ts): `src/validators/placeholder-set.ts`
- [Android markup rules](https://github.com/davlet42/ai18n/blob/main/src/android-markup.ts): `src/android-markup.ts`

### Export and delivery

- [Export command](https://github.com/davlet42/ai18n/blob/main/src/commands/export.ts): `src/commands/export.ts`
- [Android resources](https://github.com/davlet42/ai18n/blob/main/src/exporters/android.ts): `src/exporters/android.ts`
- [iOS catalog](https://github.com/davlet42/ai18n/blob/main/src/exporters/xcstrings.ts): `src/exporters/xcstrings.ts`
- [Web and TS output](https://github.com/davlet42/ai18n/blob/main/src/exporters/simple.ts): `src/exporters/simple.ts`
- [Shared format transforms](https://github.com/davlet42/ai18n/blob/main/src/exporters/transform.ts): `src/exporters/transform.ts`
- [Static bundle](https://github.com/davlet42/ai18n/blob/main/src/bundle.ts): `src/bundle.ts`
- [Nest delivery module](https://github.com/davlet42/ai18n/blob/main/packages/nest/src/index.ts): `packages/nest/src/index.ts`

### Other components

- **Project user**

## Connections

- Project user → CLI entry: runs commands (evidence: `README.md`)
- CLI entry → Translate command: dispatches
- Translate command → Project config: loads settings (evidence: `src/commands/translate.ts`)
- Translate command → Sync orchestrator: runs sync (evidence: `src/commands/translate.ts`)
- Sync orchestrator → Change planner: plans changes (evidence: `src/sync.ts`)
- Sync orchestrator → Locale file IO: reads and writes (evidence: `src/sync.ts`)
- Sync orchestrator → Ownership lockfile: tracks ownership (evidence: `src/sync.ts`)
- Sync orchestrator → Hints and glossary: loads guidance (evidence: `src/sync.ts`)
- Sync orchestrator → Provider transport: creates transport (evidence: `src/sync.ts`)
- Sync orchestrator → Translation and guards: translates batches (evidence: `src/sync.ts`)
- Sync orchestrator → Run metrics: records runs (evidence: `src/sync.ts`)
- Translation and guards → Plural validation: validates plurals (evidence: `src/translate-batch.ts`)
- Translation and guards → Placeholder validation: validates arguments (evidence: `src/translate-batch.ts`)
- Translation and guards → Android markup rules: checks markup (evidence: `src/translate-batch.ts`)
- Plural validation → Shared format transforms: parses ICU (evidence: `src/validators/cldr-plural.ts`)
- Import command → Project config: loads settings (evidence: `src/commands/import.ts`)
- Import command → Android importer: imports Android (evidence: `src/commands/import.ts`)
- Import command → iOS importer: imports iOS (evidence: `src/commands/import.ts`)
- Android importer → Locale file IO: writes locales (evidence: `src/importers/android-xml-import.ts`)
- iOS importer → Locale file IO: writes locales (evidence: `src/importers/xcstrings-import.ts`)
- Check command → Project config: loads settings (evidence: `src/commands/check.ts`)
- Check command → Android checks: checks Android (evidence: `src/commands/check.ts`)
- Status command → Android checks: checks structure (evidence: `src/commands/status.ts`)
- Android checks → Plural validation: validates plurals (evidence: `src/validators/android-check.ts`)
- Android checks → Placeholder validation: validates format args (evidence: `src/validators/android-check.ts`)
- Android checks → Android markup rules: validates markup (evidence: `src/validators/android-check.ts`)
- Report command → Run metrics: reports metrics
- Export command → Project config: loads settings (evidence: `src/commands/export.ts`)
- Export command → Locale file IO: reads locales (evidence: `src/commands/export.ts`)
- Export command → Android resources: emits Android (evidence: `src/commands/export.ts`)
- Export command → iOS catalog: emits catalog (evidence: `src/commands/export.ts`)
- Export command → Web and TS output: emits web output (evidence: `src/commands/export.ts`)
- Export command → Static bundle: builds bundle (evidence: `src/commands/export.ts`)
- Android resources → Shared format transforms: converts placeholders (evidence: `src/exporters/android.ts`)
- iOS catalog → Shared format transforms: converts placeholders (evidence: `src/exporters/xcstrings.ts`)
- Project user → Export command: requests export (evidence: `README.md`)
- Project user → Import command: requests import (evidence: `README.md`)
- Project user → Check command: checks drift (evidence: `README.md`)
- Project user → Status command: requests status (evidence: `README.md`)
- Static bundle → Nest delivery module: serves bundle (evidence: `README.md`)
