=======================================================================
 jitREADME.txt — HOW THIS THING WORKS
 The jit-tr translation pipeline, explained with nothing left out.
=======================================================================

 There is no magic in here. No service to sign up for, no account.
 It is a handful of plain PHP files that read your website, ask an
 AI to translate the words, and write out one folder per language.

 You can read every line of it in an afternoon. That is on purpose:
 the code IS the support plan. Any developer you hire — this year or
 in twenty — can maintain it, because there is nothing to learn but
 PHP and one idea.

 This file explains the one idea, then everything iis built on top of it.

 In a hurry? You need two commands and nothing else:

     php jit.php          where things stand, and what to do next
     php jit.php go       do everything

 The rest of this file is for when you want to know WHY.
=======================================================================


1. THE ONE IDEA
-----------------------------------------------------------------------
Every piece of translatable text is identified by a hash of itself:

        name = hash('fnv1a64', "Put Your Website Here!")

That hash is the string's NAME. Anyone holding the text can work it
out; it is the same on every machine, in every stage, forever.

Nothing assigns id numbers. Nothing records "this was the 42nd string
on page 3." There are no positions to get out of step, no counters to
drift, no database to disagree with the files. A translation is
matched to its English by its hashed name, and only by name.

That single decision removes an entire category of failure. The
classic disaster of translation tooling — the French sentence landing
in the German paragraph because something was inserted upstream — is
not guarded against here. It is impossible to express. There is no
"place" for a string to be in the wrong one.

Three consequences you will actually feel:

  * Move text between pages, reorder your site, change <h2> to <h1>:
    the words are the same, so the names are the same, so the
    translations still apply. Cost: nothing.
  * The same phrase used on ten pages is translated once and applied
    ten times.
  * Everything you have ever paid for is stored, by name, in a plain
    file on your own server. You never buy the same sentence twice.


2. THE FILES (the machine)
-----------------------------------------------------------------------
Five verbs, one inspector, one judge, and one command that runs them
in the right order. Each script carries its own manual in its header
comment — read the top of any file and you know what it does.

  extract    THE CENSUS. Walks your source folder and writes down
             every human-readable string: page text, alt/title/
             placeholder attributes, strings inside <script>, strings
             inside <?php ... ?>. Result: {name: english} for the
             whole site. Merges with what it already knew, so running
             it twice is harmless. Reads only. Costs nothing.

  submit     ASK THE UNANSWERED. For each language it compares the
             census against that language's answer-book and sends
             ONLY the names with no answer yet. First run pays for the
             site; every run after pays for what changed. One batch
             per language, submitted in seconds — then the script
             exits. Nothing on your machine has to stay running.

  harvest    OPEN THE ENVELOPES. Collects finished batches and writes
             each answer into the language's answer-book. The book
             only ever grows. A string that failed simply isn't
             written — which means it is still unanswered, which means
             the next submit asks for it again. There is no retry
             logic anywhere in this system; retry is just arithmetic.

  build      SPEAK THE ANSWERS. Takes your source file's bytes,
             swaps each known English string for its translation, and
             writes the result into the language folder. It does not
             parse your HTML. It does not rebuild your page. If your
             English page works in a browser, the French one works,
             because it IS your English page with different words in
             it. Never deletes anything. Costs nothing; run it as
             often as you like.

  verify     THE INSPECTOR. Checks the things that can still be
             wrong: does every census entry hash to its own name, has
             your source gained text the census hasn't seen, which
             strings have no translation yet (those show as English
             on the built site), and is every page actually built.
             Prints one line — VERIFY: 1 (fine) or VERIFY: 2
             (problems) — and writes a full report with a "-> FIX:"
             command under every problem. Free.

  validate   THE JUDGE (optional). Sends each answer-book back to the
             AI with an auditor's prompt: is this really Spanish, and
             is it a reasonable translation? Anything that fails is
             DELETED from the book, which means the next run buys it
             again. Costs cents. Catches wrong-language, gibberish,
             truncation, English-passed-through.

  jit.php    THE ONLY COMMAND YOU NEED.
                 php jit.php         status, and one NEXT line
                 php jit.php go      inherit -> extract -> submit ->
                                     harvest -> build -> verify
                 php jit.php fresh   buy every translation again
                                     (asks first; deletes nothing)

  jitHELP.txt      Q&A for whoever is sitting at the keyboard when
                   something looks wrong. Every answer ends in a
                   command.
  FINISHING.txt    everything AFTER translation: the SEO head,
                   hreflang, canonical, sitemap, going live.


3. THE PAPERWORK (all of it regenerable)
-----------------------------------------------------------------------
The scripts keep their notes in hidden .claude folders, in plain JSON
you can read with `cat`. No database, no binary formats, no lock
files.

  en/.claude/strings.json        the census: {name: english}
  en/.claude/manifest.json       per-page info (convenience only —
                                 nothing depends on it for correctness)
  en/.claude/verify.report.txt   the latest inspection, in full

  <la>/.claude/tr.json           THE ANSWER-BOOK: {name: translation}
                                 This is the only file money bought.
                                 It is yours, on your server, forever.
  <la>/.claude/batch.state.json  which batch is in flight
  <la>/.claude/harvest.report.txt, validate.report.txt, start, status

Keep these off the public web. One line in your .htaccess does it:

    RewriteRule (^|/)\.claude(/|$) - [F]


4. THE THREE THINGS THAT MATTER (back these up; nothing else)
-----------------------------------------------------------------------
    1.  your source folder      — the real website
    2.  API_key.php             — your AI key
    3.  these scripts           — the machine

Everything else in this system regenerates from those three for about
a dollar. That sentence is the entire disaster-recovery plan, and it
is the reason you can be relaxed about the rest.


5. THE INHERITANCE RULE
-----------------------------------------------------------------------
Every run collects any mail already waiting before it asks for
anything new. Batches that were submitted and never collected get
collected first.

So: Ctrl-C in the middle, a server reboot, a two-day gap, a
contractor who quits halfway through — the next run simply finishes
the last one. Interrupted work is inherited, never thrown away, and
never paid for twice.


6. WHAT IT COSTS
-----------------------------------------------------------------------
Translation is billed by the AI provider, by the word.
For a small site (a handful of pages) a complete translation into
every language you have configured runs to a couple of dollars — EACH Time -
no extra staff needed..

    added a paragraph        pennies
    reworded a sentence      pennies
    changed <h2> to <h1>     nothing at all — the words didn't change
    rebuilt every page       nothing at all — build costs nothing
    ran verify               nothing at all

7. WHAT EACH FAILURE COSTS (the honesty table)
-----------------------------------------------------------------------
  a string fails mid-batch     -> it stays unanswered, so the next run
                                  asks again. Nothing to do.
  harvest interrupted          -> rerun. Finished batches wait on the
                                  provider's side for about 29 days.
  build interrupted            -> rerun. It overwrites its own output;
                                  a half-built site is still a site.
  you edit the source mid-run  -> harmless. New text shows as English
                                  until the next run buys it.
  a language folder deleted    -> the next run rebuilds it. If its
                                  answer-book went too, it re-buys.
  all the .claude folders gone -> `php jit.php fresh` — a dollar or
                                  two, and everything is back.
  the SOURCE folder damaged    -> the one real emergency. Restore it
                                  from backup. jit.php refuses to run
                                  when it sees the source has
                                  collapsed, rather than helpfully
                                  propagating the damage.
  a bad translation slips out  -> validate condemns it and deletes it;
                                  the next run buys a fresh one.
  something genuinely broken   -> the verify report names the exact
                                  files to show someone. That is the
                                  only case where you need help.

Notice what is missing from that table: nothing loses your work, and
nothing scrambles your site. The worst outcome available is a page
that shows English where you expected French — visible, harmless, and
fixed by running the thing again.


8. DESIGN PRINCIPLES (why it is shaped this way)
-----------------------------------------------------------------------
  * The hash is the name. Identity comes from content, not from a
    ledger somebody has to keep honest.

  * Recovery is arithmetic, not a feature. Unanswered means
    will-be-asked. Unwritten means unasked. The difference between
    what exists and what is answered IS the to-do list, recomputed
    from scratch every run.

  * Nothing is precious except the three things in section 4. Cheap
    regeneration beats careful protection: a system you can rebuild
    for a dollar does not need to be defended.

  * Build does not parse. It swaps words in your bytes. Every bug
    that comes from rewriting someone's HTML is impossible because
    no HTML is ever rewritten.

  * Nothing deletes. These scripts write and overwrite. Removing
    anything is always your decision, made by hand.

  * Every check a careful operator "could do" is a check a script
    DOES, ending in a verdict line and a report file.

  * Every error message ends in a command.

  * Assume the person at the keyboard is interrupted, confused, or
    new. The system absorbs incompetence instead of punishing it.

  * Flat JSON files that a human can read. No database. The answer-book is
    the truth, not a cache of some truth kept elsewhere.


9. WHAT THIS IS NOT
-----------------------------------------------------------------------
Being honest about the edges, because you will find them eventually:

  * It is not a live translator. It produces files, once, that you
    then serve. We offer that elsewhere - but HERE NO script runs on
    your visitors' browsers.
  * It does not touch your original. Your source folder is read and
    never written.
  * It is not a human translator. It is a very good machine one, with
    an optional second machine checking the first. For legal text,
    medical text, or copy that carries your brand's voice, have a
    human read what it produced. It is cheap to fix and expensive to
    regret.
  * It cannot translate words baked into an image. Those are pixels.
    See FINISHING.txt for the two honest ways around that.
  * It does not do anything about SEO by itself. Translated pages
    that search engines can't understand are pages nobody finds.
    See FINISHING.txt for the  honest way around that 
    — and it is half an hour of work.


10. WHERE TO GO NEXT
-----------------------------------------------------------------------
    php jit.php            see where you are
    jitHELP.txt            something looks wrong, what do I type
    FINISHING.txt          the SEO and go-live work
    the top of any script  its own complete manual

And the standing invitation: open the files. There is nothing in
there you are not meant to see, and nothing you could not have
written yourself. That is the whole point of it being yours.

=======================================================================
 jit-tr.com — the software is free, presented AS IS - without warranty 
 or any liability - yours to keep, modify and sell.  Back reference to
 us is appreciated.
 The Claude Haiku-AI translation service that fills it is advertised at:
 approximately $10/month per website.
=======================================================================

=======================================================================
 You are invited to examine https://jit4all.com — MY on-line Computer
 Science learning center`, in YOUR language.

PS

 If someone backs a truck full of money up to my door tomorrow:
 what you downloaded is still yours. The licence does not expire, the
 files are already on your server, and no new owner can reach them.

 That is not a promise from me — it is just what "yours to keep" means.
=======================================================================

