# amsul/react-translated architecture

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

- Interactive diagram: https://gitdiagram.com/amsul/react-translated
- Repository: https://github.com/amsul/react-translated

## Overview

##### Project Type and Purpose
- This is an open-source React library (“react-translated”) that provides a dead-simple translation layer for React DOM and React Native apps.
- Purpose: supply a `<Provider>` for context, a `<Translate>` component (for JSX output) and a `Translator` helper (for string output), plus interpolation and component-in-text features.

a. Host Application
- React DOM App
- React Native App
- User-supplied translation file (JSON or JS mapping keys to language dictionaries/functions)
b. Library Core (under lib/)
- Provider (context provider for language & translation data)
- Translate component (subscribes to context, renders translated JSX)
- Translator component (provides translate function for string use cases)
- Renderer / createRenderer (internal rendering pipeline)
- createSubscribe / createTranslate (subscription and caching logic)
- getTranslated (core logic that picks the correct translation string/function & applies data, interpolation, Markdown–style or component replacements)
- Utilities & constants (helper functions, default configs)
c. Bundler & Build
- rollup.config.js (defines input `lib/index.js`, output formats)
- .babelrc / .eslintrc / flowconfig (tooling configs)
d. Examples (just for reference—external to core)
- examples/react-dom (demonstrates usage in a web app)
- examples/react-native (demonstrates usage in a native mobile app)

##### Relationships and Data Flow
1. Host App imports `<Provider language translation>` from `react-translated`
2. Provider places `language` & `translation` into React Context
3. Host App renders `<Translate>` or `<Translator>` deeper in component tree
4. Translate/Translator uses createSubscribe to listen to context changes
5. On render, Translate calls getTranslated(text, data, renderMap, language, translation)
- If translation value is a function, it is invoked with `data` to select correct form (pluralization, grammar)
- Interpolation and Markdown-style parsing happen here
- RenderMap components get plugged in
6. createRenderer takes the result and outputs React elements or plain string
7. React reconciler (React DOM or React Native) actually paints the UI

##### Architectural Patterns & Principles
- Context-driven (React Context) for global language & translations
- Publisher–subscriber (createSubscribe) to re-render only impacted `<Translate>` components when language changes
- Functional composition: splitting “translate retrieval” (getTranslated) from “render” (renderer)
- Single responsibility: Provider vs. Translate vs. Translator vs. core logic
- Pluggable interpolation: renderMap for custom component injections

##### Elements
- A “Host App” boundary showing React DOM vs. React Native integration
- Data flow: translation file → Provider → Translate → getTranslated → renderer → React host
- Dependencies: Translate depends on getTranslated and context
- Events: language change triggers providers updates → re-subscribe → re-render
- Host Application (blue)
- Library Core (green)
- User Data/Config (yellow)
- React Host (orange)
- Rectangles for modules/components

## Diagram (Mermaid)

```mermaid
graph TD
    %% User Data/Config
    TranslationFile["Translation File<br/>(JSON/JS)"]:::userConfig

    %% Host Application
    subgraph "Host Application" 
        direction TB
        HostAppWeb["React DOM App"]:::hostApp
        HostAppNative["React Native App"]:::hostApp
    end

    %% Library Core
    subgraph "Library Core" 
        direction TB
        EntryPoint["lib/index.js<br/>(Entry Point)"]:::core
        Provider["Provider"]:::core
        TranslateDOM["Translate (DOM)"]:::core
        TranslateNative["Translate (Native)"]:::core
        Translator["Translator Helper"]:::core
        Subscribe["createSubscribe"]:::core
        TranslateWrap["createTranslate"]:::core
        GetTranslated["getTranslated"]:::core
        Renderer["createRenderer"]:::core
        CoreRenderer["Core Renderer Logic<br/>(lib/renderer.js)"]:::core
        Utils["Utilities"]:::core
        Constants["Constants & Defaults"]:::core
    end

    %% React Host
    subgraph "React Reconciler" 
        direction TB
        ReactDOMRenderer["React DOM Reconciler"]:::reactHost
        ReactNativeRenderer["React Native Reconciler"]:::reactHost
    end

    %% Bundler & Build
    subgraph "Build & Tooling" 
        direction TB
        Rollup["rollup.config.js"]:::build
        Babel[".babelrc"]:::build
        ESLint[".eslintrc"]:::build
        Flow[".flowconfig"]:::build
    end

    %% Examples
    ExamplesWeb["examples/react-dom"] 
    ExamplesNative["examples/react-native"] 

    %% Connections: Data Flow
    TranslationFile -->|"language & dictionary"| Provider
    HostAppWeb -->|"imports Provider"| Provider
    HostAppNative -->|"imports Provider"| Provider

    Provider -->|"provides context"| Subscribe
    Subscribe -->|"notifies"| TranslateDOM
    Subscribe -->|"notifies"| TranslateNative
    Subscribe -->|"notifies"| Translator

    TranslateDOM -->|"calls getTranslated(text,data,renderMap,lang,dict)"| GetTranslated
    TranslateNative -->|"calls getTranslated(text,data,renderMap,lang,dict)"| GetTranslated
    Translator -->|"calls getTranslated(text,data,{},lang,dict)"| GetTranslated

    GetTranslated -->|"produces token tree"| Renderer
    Renderer -->|"generates React elements or string"| ReactDOMRenderer
    Renderer -->|"generates React elements or string"| ReactNativeRenderer

    %% Extension optional flow
    GetTranslated -.->|"renderMap injection"| TranslateWrap

    %% Core renderer logic usage
    Renderer --> CoreRenderer

    %% Utilities & constants usage
    Provider --> Utils
    GetTranslated --> Utils
    GetTranslated --> Constants

    %% Entry point ties core
    EntryPoint --> Provider
    EntryPoint --> TranslateDOM
    EntryPoint --> TranslateNative
    EntryPoint --> Translator
    EntryPoint --> Renderer
    EntryPoint --> Subscribe
    EntryPoint --> TranslateWrap
    EntryPoint --> GetTranslated
    EntryPoint --> Utils
    EntryPoint --> Constants

    %% Build & Tooling
    EntryPoint --> Rollup
    Rollup --> Babel
    Rollup --> ESLint
    Rollup --> Flow

    %% Examples reference
    ExamplesWeb -->|“demonstrates usage”| HostAppWeb
    ExamplesNative -->|“demonstrates usage”| HostAppNative

    %% Click Events
    click Provider "https://github.com/amsul/react-translated/blob/master/lib/components/Provider.js"
    click TranslateDOM "https://github.com/amsul/react-translated/blob/master/lib/components/Translate.js"
    click TranslateNative "https://github.com/amsul/react-translated/blob/master/lib/components/Translate.native.js"
    click Translator "https://github.com/amsul/react-translated/blob/master/lib/components/Translator.js"
    click Renderer "https://github.com/amsul/react-translated/blob/master/lib/components/createRenderer.js"
    click CoreRenderer "https://github.com/amsul/react-translated/blob/master/lib/renderer.js"
    click Subscribe "https://github.com/amsul/react-translated/blob/master/lib/components/createSubscribe.js"
    click TranslateWrap "https://github.com/amsul/react-translated/blob/master/lib/components/createTranslate.js"
    click GetTranslated "https://github.com/amsul/react-translated/blob/master/lib/getTranslated.js"
    click Utils "https://github.com/amsul/react-translated/blob/master/lib/utils.js"
    click Constants "https://github.com/amsul/react-translated/blob/master/lib/constants.js"
    click EntryPoint "https://github.com/amsul/react-translated/blob/master/lib/index.js"
    click Rollup "https://github.com/amsul/react-translated/blob/master/rollup.config.js"
    click Babel "https://github.com/amsul/react-translated/blob/master/.babelrc"
    click ESLint "https://github.com/amsul/react-translated/blob/master/.eslintrc"
    click Flow "https://github.com/amsul/react-translated/blob/master/.flowconfig"
    click ExamplesWeb "https://github.com/amsul/react-translated/tree/master/examples/react-dom"
    click ExamplesNative "https://github.com/amsul/react-translated/tree/master/examples/react-native"

    %% Styles
    classDef hostApp fill:#cce5ff,stroke:#3399ff,color:#000;
    classDef core fill:#d4edda,stroke:#28a745,color:#000;
    classDef userConfig fill:#fff3cd,stroke:#ffcd39,color:#000;
    classDef reactHost fill:#ffe5b4,stroke:#ff8c00,color:#000;
    classDef build fill:#f0f0f0,stroke:#999,color:#000;

    %% Dashed style for optional flows
    linkStyle default stroke-dasharray: 5 5;
```
