# mololab/json-translator architecture

> Architecture diagram of the GitHub repository mololab/json-translator, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mololab/json-translator
- Repository: https://github.com/mololab/json-translator

## Overview

##### Project type and purpose
- This is a Node.js‐based CLI tool *and* a reusable package (“@parvineyvazov/json-translator”) whose job is to take JSON/YAML files or in-memory JSON objects, break them down, translate all text values via one of several external translation services or AI models, reassemble the output, and write it back to disk or return it to the caller.

##### File structure
- Top level:
- bin/jsontt → the shipped CLI executable
- docs/ → language support reference
- src/
– cli/ → parses arguments, prompts, drives the flow
– core/ → engine plumbing: reading/writing files, placeholder handling, orchestration
– modules/ → implements each translation strategy (Google, Bing, DeepL, OpenAI, etc.)
– utils/ → YAML parser, console I/O helpers, micro concurrency queue
– index.ts → package entrypoint exporting the public API
- Config/build files: rollup.config.js, tsconfig.json, jest.config.js, makefile

##### Extract key insights from the README
- Two “faces” of the system: the CLI (`jsontt <path> [options]`) and the programmatic API (`translateWord`, `translateObject`, `translateFile`, etc.).
- Supports multiple translation backends via a plug-in (“strategy”) model.
- Handles deep JSON structures, placeholder ignoring, proxy lists, concurrency limits, fallback logic.

##### Main components & their interactions
a. Components:
1. CLI Frontend
2. Argument Parser & Prompt (src/cli)
3. Core Orchestrator (src/core/translator.ts & core.ts)
4. File I/O layer (src/core/json_file.ts, proxy_file.ts)
5. JSON Processor (src/core/json_object.ts)
6. Placeholder Ignorer (src/core/ignorer.ts)
7. Translation Module Manager (src/modules/modules.ts + modules/functions.ts + modules/languages.ts)
8. Individual Module Implementations (Google/Bing/Libre/Argos/DeepL/OpenAI…)
9. Utility Layer (YAML parser, concurrency “micro” queue, console logger)
10. External Services (HTTP APIs, OpenAI endpoints)
11. Disk / Environment (filesystem, env-vars for API keys)
- User invokes `jsontt` → CLI Frontend
- CLI → Argument Parser → Core Orchestrator
- Orchestrator → File I/O reads JSON/YAML
- JSON Processor flattens/traverses object
- Placeholder Ignorer extracts tokens (e.g. `{name}`, URLs)
- Orchestrator → Module Manager selects translation strategy
- Strategy → External Service → returns translated strings
- Orchestrator merges results → Placeholder Ignorer re-inserts tokens
- Orchestrator → File I/O writes output file(s)
- CLI → Console Logger reports progress/status
c. Architectural patterns:
- Strategy pattern for pluggable translation modules
- Pipeline design (read → preprocess → translate → postprocess → write)
- Separation of concerns: CLI vs. Core vs. Modules vs. Utils
- Concurrency control via “micro” queue and optional proxy support
d. Key technologies/frameworks:
- Node.js + TypeScript
- Rollup for bundling the package
- Jest for unit tests
- External HTTP clients (fetch or axios inside modules)
- Env-vars for API keys (OPENAI_API_KEY, DEEPL_API_KEY, etc.)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Layer
    subgraph "CLI Layer"
        CLIExe["CLI Executable\nbin/jsontt"]:::cli
        CLIFront["CLI Frontend\ncli.ts"]:::cli
        Prompt["Argument Parser & Prompt\nprompt.ts"]:::cli
    end

    %% Library Core
    subgraph "Library Core"
        CoreEntr["Public API\nindex.ts"]:::core
        subgraph "Core Orchestration"
            Orchestrator["Core Orchestrator\ntranslator.ts, core.ts"]:::core
        end
        subgraph "Pipeline"
            JSONFile["JSON File I/O\njson_file.ts"]:::core
            ProxyFile["Proxy File I/O\nproxy_file.ts"]:::core
            JSONProc["JSON Processor\njson_object.ts"]:::core
            Ignorer["Placeholder Ignorer\nignorer.ts"]:::core
            ModMgr["Translation Module Manager\nmodules.ts\nfunctions.ts\nlanguages.ts"]:::core
        end
    end

    %% Translation Modules
    subgraph "Translation Modules"
        Helpers["Module Helpers\nhelpers.ts"]:::module
    end

    %% Utilities
    subgraph "Utilities"
        YAML["YAML Parser\nyaml.ts"]:::util
        Queue["Concurrency Queue\nmicro.ts"]:::util
        Logger["Console Logger\nconsole.ts"]:::util
    end

    %% External Dependencies
    Filesystem["Filesystem & Env\n(env-vars)"]:::ext
    ExtService["External Translation APIs\n(HTTP endpoints)"]:::ext
    Docs["Language Support Reference\ndocs/LANGUAGES.md"]:::ext

    %% Connections
    CLIExe --> CLIFront
    CLIFront --> Prompt
    Prompt --> Orchestrator
    CLIFront --> Logger
    CoreEntr --> Orchestrator

    Orchestrator --> JSONFile
    Orchestrator --> ProxyFile
    JSONFile --> Filesystem
    ProxyFile --> Filesystem

    JSONFile --> JSONProc
    JSONProc --> Ignorer
    Ignorer --> ModMgr
    ModMgr --> Helpers
    Helpers -.-> ExtService
    ExtService -.-> Helpers
    Helpers --> ModMgr
    ModMgr --> Orchestrator
    Orchestrator --> Ignorer
    Orchestrator --> JSONFile
    JSONFile --> Filesystem

    Docs --> ModMgr

    %% Click Events
    click CLIExe "https://github.com/mololab/json-translator/tree/master/bin/jsontt"
    click CLIFront "https://github.com/mololab/json-translator/blob/master/src/cli/cli.ts"
    click Prompt "https://github.com/mololab/json-translator/blob/master/src/cli/prompt.ts"
    click Orchestrator "https://github.com/mololab/json-translator/blob/master/src/core/translator.ts"
    click JSONFile "https://github.com/mololab/json-translator/blob/master/src/core/json_file.ts"
    click ProxyFile "https://github.com/mololab/json-translator/blob/master/src/core/proxy_file.ts"
    click JSONProc "https://github.com/mololab/json-translator/blob/master/src/core/json_object.ts"
    click Ignorer "https://github.com/mololab/json-translator/blob/master/src/core/ignorer.ts"
    click ModMgr "https://github.com/mololab/json-translator/blob/master/src/modules/modules.ts"
    click ModMgr "https://github.com/mololab/json-translator/blob/master/src/modules/functions.ts"
    click ModMgr "https://github.com/mololab/json-translator/blob/master/src/modules/languages.ts"
    click Helpers "https://github.com/mololab/json-translator/blob/master/src/modules/helpers.ts"
    click YAML "https://github.com/mololab/json-translator/blob/master/src/utils/yaml.ts"
    click Queue "https://github.com/mololab/json-translator/blob/master/src/utils/micro.ts"
    click Logger "https://github.com/mololab/json-translator/blob/master/src/utils/console.ts"
    click CoreEntr "https://github.com/mololab/json-translator/blob/master/src/index.ts"
    click Docs "https://github.com/mololab/json-translator/blob/master/docs/LANGUAGES.md"

    %% Styles
    classDef cli fill:#D0E4F5,stroke:#1B4F72,color:#1B2631
    classDef core fill:#D5F5D0,stroke:#196F3D,color:#1B2631
    classDef module fill:#FAD7A0,stroke:#B9770E,color:#1B2631
    classDef util fill:#E5E7E9,stroke:#566573,color:#1B2631
    classDef ext fill:#BFC9CA,stroke:#566573,color:#1B2631
```
