# elinchi/emctranslator architecture

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

- Interactive diagram: https://gitdiagram.com/elinchi/emctranslator
- Repository: https://github.com/elinchi/emctranslator

## Overview

#### Purpose and Entry Points
EMCT is a desktop GUI for translating Minecraft localization JSON, including language files extracted from mod JARs. It supports manual editing, AI-assisted translation, project persistence, previews, and resource-pack export.

- Application launcher: `Minecraft-Translator-GUI-last.py`
- Main orchestration/window layer: `program/app/window.py`
- Build script for distribution: `build.ps1`

#### Application Orchestration and UI
The main window owns user-driven workflow: opening source files, switching projects/mods, invoking translation, updating editor state, and coordinating persistence/export. GUI controllers separate interactive behaviors from core services.

- Main window: `program/app/window.py`
- Translation UI interaction: `program/gui/translation_controller.py`
- Multi-project UI: `program/gui/multiproject_panel.py`

Preview behavior is isolated so the editor can render raw JSON-oriented output or Minecraft-style formatted text without making rendering part of translation storage.

- Preview coordination: `program/gui/preview_controller.py`
- Minecraft text rendering: `program/gui/mc_renderer.py`

#### Translation Domain and Validation
Translation state consists of source keys/original values and editable translated values. Translation processing preserves Minecraft formatting requirements through validation of placeholders and escape sequences before output is accepted.

- Translation model/logic: `program/core/translation.py`
- Translation workflow service: `program/core/translation_service.py`
- Format validation: `program/core/validation.py`

The UI controller is the boundary between row-level editing/ghost suggestions and domain operations; persistent project and cache services should not depend on GUI widgets.

#### AI Provider Boundary
AI work is provider-specific behind the `program/ai` layer. A worker coordinates translation execution, while DeepL and Ollama adapters handle their respective external interfaces.

- Translation worker: `program/ai/worker.py`
- DeepL integration: `program/ai/deepl.py`
- Ollama integration: `program/ai/ollama.py`

DeepL requires an API key and tracks usage; Ollama relies on a locally available `ollama` CLI and selected model. Provider/model/key preferences are retained in cache/config state.

#### Input, Projects, and Cache Persistence
Source localization can be loaded from standalone JSON or from JAR archives. Projects use `.mctproj` files to persist translation state, preview state, and project-local cache; loading merges project cache with global cache without replacing existing global entries.

- JSON read/write: `program/core/json_io.py`
- JAR extraction/access: `program/core/jar_io.py`
- Project lifecycle: `program/core/project_service.py`
- Project serialization: `program/core/project_store.py`
- Global translation memory/cache: `program/core/cache.py`

The durable global cache is intended for `%LOCALAPPDATA%/EMCT/translation_cache.json`; tracked cache JSON files such as `program/app/translation_cache.json` are repository-side artifacts/defaults rather than the intended user-state location.

#### Multi-Project Resource-Pack Pipeline
Multi-project mode scans mod JARs recursively, selects those with usable language JSON and no existing Ukrainian translation, and maintains each mod’s translation state in memory while switching items. Export combines completed translations into Minecraft resource-pack paths such as `assets/<namespace>/lang/uk_ua.json`.

- Multi-project state/workflow: `program/core/multiproject_service.py`
- Resource-pack assembly: `program/core/resource_pack.py`
- JAR discovery/extraction: `program/core/jar_io.py`

This is the main aggregation boundary: individual project/mod translations are edited independently, then emitted together as one resource pack.

#### Runtime Assets and Localization
The application is Python-based with dependencies declared in `requirements.txt`. Its desktop UI includes bundled fonts and audio feedback, while interface localization is data-driven through language JSON.

- Dependencies: `requirements.txt`
- UI localization loader: `program/config/i18n.py`
- Language catalogs: `program/config/lang/en_us.json`, `program/config/lang/uk_ua.json`
- Audio assets: `program/sounds/click.wav`

Main entry points: [`program/app/window.py`](https://github.com/elinchi/emctranslator/blob/main/program/app/window.py) (Main window), [`program/core/project_service.py`](https://github.com/elinchi/emctranslator/blob/main/program/core/project_service.py) (Project lifecycle), [`program/core/translation_service.py`](https://github.com/elinchi/emctranslator/blob/main/program/core/translation_service.py) (Translation service), [`program/core/multiproject_service.py`](https://github.com/elinchi/emctranslator/blob/main/program/core/multiproject_service.py) (Multi-project service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Desktop UI"]
  node_window["Main window<br/>workflow orchestrator<br/>[window.py]"]
  node_translation_ui["Translation controller<br/>UI controller"]
  node_multiproject_ui["Multi-project panel<br/>UI controller"]
  node_preview["Preview controller<br/>UI controller"]
  node_renderer["Minecraft text renderer<br/>presentation renderer<br/>[mc_renderer.py]"]
  node_i18n["UI localization<br/>catalog loader<br/>[i18n.py]"]
end

subgraph group_core["Translation Core"]
  node_translation["Translation model<br/>domain model<br/>[translation.py]"]
  node_translation_service["Translation service<br/>domain workflow"]
  node_validation["Format validation<br/>domain validator<br/>[validation.py]"]
end

subgraph group_storage["Projects &amp; Export"]
  node_json_io["JSON I/O<br/>file adapter<br/>[json_io.py]"]
  node_jar_io["JAR I/O<br/>archive adapter<br/>[jar_io.py]"]
  node_project_service["Project lifecycle<br/>project workflow<br/>[project_service.py]"]
  node_project_store[("Project store<br/>serialization adapter<br/>[project_store.py]")]
  node_cache[("Translation cache<br/>global persistence<br/>[cache.py]")]
  node_multiproject["Multi-project service<br/>aggregation workflow"]
  node_resource_pack["Resource-pack exporter<br/>export assembler<br/>[resource_pack.py]"]
end

subgraph group_ai["AI Providers"]
  node_worker["AI translation worker<br/>provider coordinator<br/>[worker.py]"]
  node_deepl["DeepL adapter<br/>external provider adapter<br/>[deepl.py]"]
  node_ollama["Ollama adapter<br/>local provider adapter<br/>[ollama.py]"]
end

node_launcher["Application launcher<br/>Python entry point"]
node_build["Distribution build<br/>build script<br/>[build.ps1]"]
node_dependencies["Python dependencies<br/>dependency manifest<br/>[requirements.txt]"]

node_launcher -->|"starts"| node_window
node_window -->|"coordinates editing"| node_translation_ui
node_window -->|"hosts"| node_multiproject_ui
node_window -->|"updates"| node_preview
node_preview -->|"renders formatted preview"| node_renderer
node_translation_ui -->|"invokes"| node_translation_service
node_translation_service -->|"updates"| node_translation
node_translation_service -->|"validates output"| node_validation
node_translation_service -->|"requests AI translation"| node_worker
node_worker -->|"uses"| node_deepl
node_worker -->|"uses"| node_ollama
node_worker -.->|"reads provider preferences"| node_cache
node_window -->|"opens and saves projects"| node_project_service
node_project_service -->|"serializes"| node_project_store
node_project_service -->|"merges project cache"| node_cache
node_project_service -->|"reads source JSON"| node_json_io
node_project_service -->|"loads JAR localization"| node_jar_io
node_multiproject_ui -->|"drives"| node_multiproject
node_multiproject -->|"scans mod JARs"| node_jar_io
node_multiproject -->|"maintains per-mod state"| node_translation
node_multiproject -->|"exports completed mods"| node_resource_pack
node_window -.->|"loads UI language"| node_i18n
node_build -->|"packages"| node_launcher
node_dependencies -.->|"runtime requirements"| node_launcher

click node_launcher "https://github.com/elinchi/emctranslator/blob/main/Minecraft-Translator-GUI-last.py"
click node_window "https://github.com/elinchi/emctranslator/blob/main/program/app/window.py"
click node_translation_ui "https://github.com/elinchi/emctranslator/blob/main/program/gui/translation_controller.py"
click node_multiproject_ui "https://github.com/elinchi/emctranslator/blob/main/program/gui/multiproject_panel.py"
click node_preview "https://github.com/elinchi/emctranslator/blob/main/program/gui/preview_controller.py"
click node_renderer "https://github.com/elinchi/emctranslator/blob/main/program/gui/mc_renderer.py"
click node_translation "https://github.com/elinchi/emctranslator/blob/main/program/core/translation.py"
click node_translation_service "https://github.com/elinchi/emctranslator/blob/main/program/core/translation_service.py"
click node_validation "https://github.com/elinchi/emctranslator/blob/main/program/core/validation.py"
click node_json_io "https://github.com/elinchi/emctranslator/blob/main/program/core/json_io.py"
click node_jar_io "https://github.com/elinchi/emctranslator/blob/main/program/core/jar_io.py"
click node_project_service "https://github.com/elinchi/emctranslator/blob/main/program/core/project_service.py"
click node_project_store "https://github.com/elinchi/emctranslator/blob/main/program/core/project_store.py"
click node_cache "https://github.com/elinchi/emctranslator/blob/main/program/core/cache.py"
click node_multiproject "https://github.com/elinchi/emctranslator/blob/main/program/core/multiproject_service.py"
click node_resource_pack "https://github.com/elinchi/emctranslator/blob/main/program/core/resource_pack.py"
click node_worker "https://github.com/elinchi/emctranslator/blob/main/program/ai/worker.py"
click node_deepl "https://github.com/elinchi/emctranslator/blob/main/program/ai/deepl.py"
click node_ollama "https://github.com/elinchi/emctranslator/blob/main/program/ai/ollama.py"
click node_i18n "https://github.com/elinchi/emctranslator/blob/main/program/config/i18n.py"
click node_build "https://github.com/elinchi/emctranslator/blob/main/build.ps1"
click node_dependencies "https://github.com/elinchi/emctranslator/blob/main/requirements.txt"

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_window,node_translation_ui,node_multiproject_ui,node_preview,node_renderer,node_i18n toneBlue
class node_translation,node_translation_service,node_validation toneAmber
class node_json_io,node_jar_io,node_project_service,node_project_store,node_cache,node_multiproject,node_resource_pack toneMint
class node_worker,node_deepl,node_ollama toneRose
class node_launcher,node_build,node_dependencies toneNeutral
```

## Components

### Desktop UI

- [Main window](https://github.com/elinchi/emctranslator/blob/main/program/app/window.py): workflow orchestrator · Owns user workflows, editor state, persistence, and export coordination. · `program/app/window.py`
- [Translation controller](https://github.com/elinchi/emctranslator/blob/main/program/gui/translation_controller.py): UI controller · Bridges row editing and ghost suggestions to domain operations. · `program/gui/translation_controller.py`
- [Multi-project panel](https://github.com/elinchi/emctranslator/blob/main/program/gui/multiproject_panel.py): UI controller · `program/gui/multiproject_panel.py`
- [Preview controller](https://github.com/elinchi/emctranslator/blob/main/program/gui/preview_controller.py): UI controller · `program/gui/preview_controller.py`
- [Minecraft text renderer](https://github.com/elinchi/emctranslator/blob/main/program/gui/mc_renderer.py): presentation renderer · Renders Minecraft-style formatted text separately from stored translations. · `program/gui/mc_renderer.py`
- [UI localization](https://github.com/elinchi/emctranslator/blob/main/program/config/i18n.py): catalog loader · Loads English and Ukrainian interface catalogs. · `program/config/i18n.py`

### Translation Core

- [Translation model](https://github.com/elinchi/emctranslator/blob/main/program/core/translation.py): domain model · Holds source keys, originals, and editable translations. · `program/core/translation.py`
- [Translation service](https://github.com/elinchi/emctranslator/blob/main/program/core/translation_service.py): domain workflow · Processes translations and accepts validated output. · `program/core/translation_service.py`
- [Format validation](https://github.com/elinchi/emctranslator/blob/main/program/core/validation.py): domain validator · Preserves placeholders and escape sequences. · `program/core/validation.py`

### Projects & Export

- [JSON I/O](https://github.com/elinchi/emctranslator/blob/main/program/core/json_io.py): file adapter · `program/core/json_io.py`
- [JAR I/O](https://github.com/elinchi/emctranslator/blob/main/program/core/jar_io.py): archive adapter · Reads localization JSON from mod archives. · `program/core/jar_io.py`
- [Project lifecycle](https://github.com/elinchi/emctranslator/blob/main/program/core/project_service.py): project workflow · `program/core/project_service.py`
- [Project store](https://github.com/elinchi/emctranslator/blob/main/program/core/project_store.py): serialization adapter · Persists .mctproj state and project-local cache. · `program/core/project_store.py`
- [Translation cache](https://github.com/elinchi/emctranslator/blob/main/program/core/cache.py): global persistence · Durable user cache is stored under LOCALAPPDATA. · `program/core/cache.py`
- [Multi-project service](https://github.com/elinchi/emctranslator/blob/main/program/core/multiproject_service.py): aggregation workflow · Maintains independent mod translation states while switching projects. · `program/core/multiproject_service.py`
- [Resource-pack exporter](https://github.com/elinchi/emctranslator/blob/main/program/core/resource_pack.py): export assembler · Writes completed translations to assets/<namespace>/lang/uk_ua.json. · `program/core/resource_pack.py`

### AI Providers

- [AI translation worker](https://github.com/elinchi/emctranslator/blob/main/program/ai/worker.py): provider coordinator · `program/ai/worker.py`
- [DeepL adapter](https://github.com/elinchi/emctranslator/blob/main/program/ai/deepl.py): external provider adapter · Uses API key and tracks usage. · `program/ai/deepl.py`
- [Ollama adapter](https://github.com/elinchi/emctranslator/blob/main/program/ai/ollama.py): local provider adapter · Invokes the local ollama CLI with a selected model. · `program/ai/ollama.py`

### Other components

- [Application launcher](https://github.com/elinchi/emctranslator/blob/main/Minecraft-Translator-GUI-last.py): Python entry point · `Minecraft-Translator-GUI-last.py`
- [Distribution build](https://github.com/elinchi/emctranslator/blob/main/build.ps1): build script · `build.ps1`
- [Python dependencies](https://github.com/elinchi/emctranslator/blob/main/requirements.txt): dependency manifest · `requirements.txt`

## Connections

- Application launcher → Main window: starts
- Main window → Translation controller: coordinates editing
- Main window → Multi-project panel: hosts
- Main window → Preview controller: updates
- Preview controller → Minecraft text renderer: renders formatted preview
- Translation controller → Translation service: invokes
- Translation service → Translation model: updates
- Translation service → Format validation: validates output
- Translation service → AI translation worker: requests AI translation
- AI translation worker → DeepL adapter: uses
- AI translation worker → Ollama adapter: uses
- AI translation worker → Translation cache: reads provider preferences
- Main window → Project lifecycle: opens and saves projects
- Project lifecycle → Project store: serializes
- Project lifecycle → Translation cache: merges project cache
- Project lifecycle → JSON I/O: reads source JSON
- Project lifecycle → JAR I/O: loads JAR localization
- Multi-project panel → Multi-project service: drives
- Multi-project service → JAR I/O: scans mod JARs
- Multi-project service → Translation model: maintains per-mod state
- Multi-project service → Resource-pack exporter: exports completed mods
- Main window → UI localization: loads UI language
- Distribution build → Application launcher: packages
- Python dependencies → Application launcher: runtime requirements