=======================================================================
 FINISHING-your-web.txt
 Everything AFTER the translation: SEO, structure, and going live
-----------------------------------------------------------------------

 The translator did the words. This file is about the OTHER work that
 decides whether anyone ever reads them:

     1.  Why "translated" is not the same as "found"
     2.  The <head> block  — the whole thing, explained line by line
     3.  Per-page variables: three lines per page, forever
     4.  hreflang: the one tag needed for multilingual sites
     5.  Canonical: the tag that decides if your pages exist
     6.  <article>, headings, and the one-h1 rule
     7.  Structured data (schema.org) — worth 15 minutes
     8.  Images: alt, title, and per-language graphics
     9.  What must NOT be translated (and how to mark it)
         - The sitemap
         - robots.txt
         - .htaccess: the SEO-relevant rules
    10.  Going live: the order to do things in
         - The checklist
         - Asking an AI to do this for you (the honest version)

 Everything here is what jit-tr.com itself does. View source on any
 page of it and you will see this file, running.
=======================================================================


1. WHY "TRANSLATED" IS NOT THE SAME AS "FOUND"
-----------------------------------------------------------------------
You now have your site in 38 languages. Congratulations — and be
warned: search engines do not automatically understand what you just
did. Left alone, they will usually do one of three unhelpful things:

  a) Index only one language and ignore the rest.
  b) Decide the other 37 are DUPLICATES of the first, and drop them.
  c) Show the wrong language to the wrong country.

None of these are bugs. They are search engines behaving reasonably in
the absence of information. The whole job of this file is to give them
that information. It comes down to four small things in your <head>,
one tag around your content, and one file at your root.

The good news: it is all plain HTML. No plugin, no account, no
service, no monthly fee. Half an hour of work, once, and then it is
inherited by every page and every language automatically.


2. THE <head> BLOCK — THE WHOLE THING
-----------------------------------------------------------------------
Here is the complete head that runs jit-tr.com, written as a PHP
include so every page and every language shares it. If your site is
plain HTML, the same tags apply — you just paste them per page and
edit by hand.

Save this as top.php (or head.php — the name is yours):

    <?php
    // ---- per-page vars, set BEFORE the require; these are defaults ----
    $L     = $L     ?? 'en';                 // this site's language
    $HOST  = 'yoursite.com';                 // your bare domain
    $PAGE  = $PAGE  ?? '';                   // '' = homepage, else 'who.php'
    $TITLE = $TITLE ?? 'Your Site — what it is, in one line';
    $DESC  = $DESC  ?? 'One sentence, about 150 characters, that would
                        make someone click on you in a search result.';

    // every language you publish, as hreflang codes
    $LANGS = ['ar','bg','ca','cs','da','de','el','en','es-419','es-es',
              'et','fi','fr','he','hi','hr','hu','it','ja','ko','lt',
              'lv','nl','nb','pl','pt-br','pt-pt','ro','ru','sk','sl',
              'sv','th','tl','tr','uk','vi','zh-cn','zh-tw'];

    // where a given language lives. THIS FUNCTION IS THE DECISION.
    function langURL($c, $host, $page = '') {
      return "https://$c.$host/" . $page;    // subdomain layout
      // subdirectory layout instead? use:
      // return "https://$host/$c/" . $page;
    }
    $SELF = langURL($L, $HOST, $PAGE);
    ?>
    <!DOCTYPE html>
    <html lang="<?= $L ?>">
    <head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">

    <title><?= $TITLE ?></title>
    <meta name="description" content="<?= $DESC ?>">
    <link rel="canonical" href="<?= $SELF ?>">

    <?php foreach ($LANGS as $c): ?>
    <link rel="alternate" hreflang="<?= $c ?>" href="<?= langURL($c, $HOST, $PAGE) ?>">
    <?php endforeach; ?>
    <link rel="alternate" hreflang="x-default" href="https://<?= $HOST ?>/<?= $PAGE ?>">

    <meta property="og:type" content="website">
    <meta property="og:site_name" content="Your Site">
    <meta property="og:url" content="<?= $SELF ?>">
    <meta property="og:title" content="<?= $TITLE ?>">
    <meta property="og:description" content="<?= $DESC ?>">
    <meta property="og:image" content="https://<?= $HOST ?>/imgs/social.<?= $L ?>.png">
    <meta property="og:image:width" content="1024">
    <meta property="og:image:height" content="768">

    <meta name="twitter:card" content="summary_large_image">
    <meta name="twitter:title" content="<?= $TITLE ?>">
    <meta name="twitter:description" content="<?= $DESC ?>">
    <meta name="twitter:image" content="https://<?= $HOST ?>/imgs/social.<?= $L ?>.png">

    <link href="/yoursite.css" rel="stylesheet">
    </head>
    <body>

Line by line, what each one is for:

  <html lang="xx">
      Tells browsers and screen readers what language the page is in.
      Also what a translation tool checks before offering to translate
      your page for the visitor (you don't want that offer — you
      already did the work).

  <title>
      The blue line in a search result. The single most important
      piece of text on the page. Different on every page, always.

  <meta name="description">
      The grey text under the blue line. Search engines don't rank on
      it, but humans decide on it. Write it like an advertisement,
      because that is exactly what it is. ~150 characters.

  <link rel="canonical">
      "This is my real address." See section 5. Get this wrong and
      pages vanish from the index.

  <link rel="alternate" hreflang>
      "Here are my other languages." See section 4.

  og: and twitter:
      What a link to your page looks like when someone pastes it into
      Facebook, LinkedIn, WhatsApp, Slack, X. Without them, the
      preview is a grey box; with them, it is a picture and a
      headline. Costs nothing, improves every share forever.

The PHP variables are all that changes between pages. The tags never
change. That is the point of the include.


3. PER-PAGE VARIABLES: THREE LINES PER PAGE, FOREVER
-----------------------------------------------------------------------
Every page begins like this and inherits everything else:

    <?php
    $PAGE  = 'who.php';
    $TITLE = 'Who Is This For? — Your Site';
    $DESC  = 'One line about this page. Make someone want to click.';
    require 'top.php';
    ?>
    ... the page ...

The homepage sets nothing and gets the defaults.

WHY THIS MATTERS MORE THAN IT LOOKS: if you hard-code the title,
description and canonical in the include, then every page on your site
tells search engines "I am the homepage." Search engines believe you,
decide the rest are duplicates, and quietly index one page out of ten.
It is the single most common self-inflicted wound in multilingual
sites, and three variables prevent it.


4. hreflang: THE ONE TAG MOST SITES GET WRONG
-----------------------------------------------------------------------
hreflang says: "these pages are the same page in different languages —
show the right one to the right person, and do NOT treat them as
duplicates."

Three rules, all of them mandatory:

  RULE 1 — RECIPROCAL, AND INCLUDING ITSELF.
      Every language version must list ALL of them, including its own.
      The French page lists French. The German page lists French too.
      If page A points at B but B does not point back at A, search
      engines discard the whole set. Half a hreflang block is worth
      nothing at all.
      The foreach loop above satisfies this automatically, because
      every language runs the same loop over the same list.

  RULE 2 — PAGE TO PAGE, NOT PAGE TO HOMEPAGE.
      /who.php in English must point at /who.php in French, not at the
      French homepage. That is why $PAGE is threaded through
      langURL(). One variable, and all 38 × N pages are correct.

  RULE 3 — x-default IS THE FALLBACK.
      One extra line, pointing at whichever version a visitor should
      get when none of your languages match theirs. Usually your
      primary language.

CODES: use language, or language-region. 'de' means German
everywhere; 'de-at' means German for Austria. 'es-419' is Latin
American Spanish (419 is the UN code for Latin America). 'pt-br' is
Brazilian Portuguese. Don't invent codes — if a code isn't real, the
line is ignored.

TESTING IT: view source on two different languages of the same page.
The hreflang blocks should be IDENTICAL except for nothing — they are
the same list. The canonical is what differs. If the blocks differ,
something is wrong.


5. CANONICAL: THE TAG THAT DECIDES IF YOUR PAGES EXIST
-----------------------------------------------------------------------
    <link rel="canonical" href="https://fr.yoursite.com/who.php">

It means: "of all the addresses that might show this content, THIS is
the real one." Every page carries exactly one, pointing at itself.

Three ways to break it, all common:

  * Hard-coded to the homepage → your other pages are declared to be
    copies of the homepage, and drop out of the index.
  * Pointing at a URL that redirects → search engines treat that as a
    soft error. Whatever your .htaccess redirects to, canonical must
    point at the DESTINATION, not the source. If yoursite.com
    redirects to en.yoursite.com, then the canonical says
    en.yoursite.com.
  * Pointing at the English version from the French page → you have
    just told Google the French page is a copy of the English one, and
    should not be shown. This one hurts, because it looks tidy and it
    is exactly backwards. Each language is canonical to ITSELF.
    hreflang is what links them, not canonical.


6. <article>, HEADINGS, AND THE ONE-H1 RULE
-----------------------------------------------------------------------
Search engines read structure. Structure means headings in order and
content wrapped in something that says "this is the content."

THE HEADING LADDER:

    <h1>   one per page. The page's subject. Not your logo.
    <h2>   the sections of that subject
    <h3>   the sub-points of a section
    ...    no skipping levels; h1 -> h3 with no h2 confuses the ladder

One <h1> per page. Not two, not zero. If your design wants big text
somewhere else, that is what CSS is for — style an <h2> to look big.
Two h1s split the signal and neither wins.

ONE LONG <article> OR MANY SMALL ONES?
Honest answer: for search engines, the <article> tag carries little
direct weight. What actually matters is:

    one topic  =  one URL  =  one <article>  =  one <h1>

A page holding six mini-articles on six subjects competes with itself
and ranks for none of them. Six PAGES, each tightly about one thing,
each with its own title, description and canonical, rank for six
things. If you have six topics, you want six URLs — and now that
translation is nearly free, six pages × 38 languages costs you
nothing but the writing.

Multiple <article> blocks on one page are correct only when they are
genuinely separate items — a news list, a blog index — and even then
each should link to its own full page.

WORST CASE, IF YOUR SITE IS ONE BIG BLOB: wrap it.

    <body>
    <article>
      ... your whole page ...
    </article>
    </body>

Even that is a signal. It says "the content is here, the rest is
furniture." Give search engines some structure; they will use it.


7. STRUCTURED DATA (schema.org) — WORTH 15 MINUTES
-----------------------------------------------------------------------
Structured data is invisible labelling that turns your page into
something a machine can quote: a product with a price, an article with
an author, a business with an address and opening hours. It is what
produces the rich results — stars, prices, FAQs — in search listings.

The cheapest useful version, inline on what you already have:

    <article itemscope itemtype="https://schema.org/Product">
      <h1 itemprop="name">What You Sell</h1>
      <p itemprop="description">What it does, in a sentence.</p>

      <p itemprop="offers" itemscope itemtype="https://schema.org/Offer">
        <span itemprop="price" content="10">$10</span>/month
        <meta itemprop="priceCurrency" content="USD">
      </p>
    </article>

Note `content="10"` on the price: the human sees "$10", the machine
reads the number 10. That pattern — visible text for people, a clean
`content` attribute for machines — is the whole trick.

Other types worth knowing: Article (blogs), LocalBusiness (a shop with
an address), FAQPage (question-and-answer sections), BreadcrumbList
(navigation trails). Look them up on schema.org when you need one;
they are all the same shape.

TRANSLATION NOTE: itemprop VALUES that are visible text get translated
like any other text, which is right. The itemtype URLs and the
`content="10"` attributes are code and stay untouched — which is also
right. You don't have to do anything about it.


8. IMAGES: alt, title, AND PER-LANGUAGE GRAPHICS
-----------------------------------------------------------------------
    <img src="/imgs/poster.en.png"
         alt="Vintage advertisement: put your website here — software
              yours to keep, AI translator inside, $10 a month"
         title="Click to read the page">

  alt    — what the image SAYS, for people who cannot see it and for
           image search. It is not decoration: it is the only text a
           search engine can read inside a picture. Write the sentence
           the graphic would say out loud. It gets translated, so
           every language gets its own image description for free.
           An image with words in it and no alt text is, to a search
           engine, a blank rectangle.

  title  — the little tooltip on hover. Optional, also translated.
           Note that alt does NOT show on hover; if you want a hint on
           hover you must use title.

PER-LANGUAGE GRAPHICS: text baked into a PNG cannot be translated by
any tool — it is pixels. Two honest options:

  a) Keep graphics text-free, put the words in HTML over or beside
     them. Then they translate themselves, forever, free.
  b) Make one graphic per language, named by language:
         poster.en.png  poster.fr.png  poster.de.png
     and let get_img.php (in this kit) serve the right one, falling
     back to the default when a language's version doesn't exist yet.
     That way you can add languages' graphics one at a time, whenever
     you feel like it, with no page edits ever.

Most sites should do (a) for anything that changes and (b) for the
handful of hero images worth the effort.


9. WHAT MUST NOT BE TRANSLATED (AND HOW TO MARK IT)
-----------------------------------------------------------------------
The rule the translator follows: if a human reads it, it translates.
That is right almost always — and wrong for brand names, part
numbers, code samples, commands, legal names, and slogans you want to
stay in one language everywhere.

Mark those. The markers are comments, invisible to browsers, free to
leave in place forever:

    IN HTML
        <p>Our motto: <!-- NOtr -->Just In Time!<!-- NOtrEND --></p>
        the visitor sees:  Our motto: Just In Time!
        on the French site: everything French except those words

    IN JAVASCRIPT (or PHP)
        alert(/*NOtr*/"BRAND-NAME 3000"/*NOtrEND*/ + " " + msg);
        the message translates; the product name never does

WHAT TO MARK, IN PRACTICE:
    * brand and product names
    * commands, file names, code examples, folder paths
    * part numbers, SKUs, model numbers
    * language pickers (the list of language codes themselves — you
      do NOT want "EN" translated into Japanese)
    * legal entity names, trademark lines
    * anything where a customer might copy the text and paste it into
      a terminal or a search box

WHAT NOT TO MARK: ordinary sentences, headings, alt text, buttons,
error messages, form labels. Those are exactly what you're paying to
have translated.

If in doubt, leave it unmarked and look at the result. Unmarked and
wrong costs one edit; marked and forgotten costs you a market.


10. THE SITEMAP
-----------------------------------------------------------------------
A sitemap is a list of your URLs handed directly to search engines. It
does not improve ranking. It improves DISCOVERY — which for a site
that just multiplied by 38 is the entire problem.

For a multilingual site, generate it. Hand-maintaining 38 × N lines is
a promise you will break in a month. A minimal generator, sitemap.php:

    <?php
    header('Content-Type: application/xml; charset=UTF-8');
    $HOST  = 'yoursite.com';
    $LANGS = ['en','fr','de','es-es'];              // your list
    $PAGES = ['', 'who.php', 'what.php', 'how.php'] ;  // your pages
    function langURL($c,$h,$p=''){ return "https://$c.$h/".$p; }
    echo '<?xml version="1.0" encoding="UTF-8"?>', "\n";
    ?>
    <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"
            xmlns:xhtml="http://www.w3.org/1999/xhtml">
    <?php foreach ($LANGS as $l): foreach ($PAGES as $p): ?>
      <url>
        <loc><?= langURL($l,$HOST,$p) ?></loc>
    <?php foreach ($LANGS as $a): ?>
        <xhtml:link rel="alternate" hreflang="<?= $a ?>" href="<?= langURL($a,$HOST,$p) ?>"/>
    <?php endforeach; ?>
        <lastmod><?= date('Y-m-d') ?></lastmod>
      </url>
    <?php endforeach; endforeach; ?>
    </urlset>

Serve it at /sitemap.xml with one .htaccess line (see section 12),
then submit that URL once in Google Search Console and Bing Webmaster
Tools. Both are free. That single submission is the difference between
"found in a week" and "found in a few months."

Note the xhtml:link lines: the sitemap repeats your hreflang
information. Belt and braces — and the belt is the one search engines
read first.


11. robots.txt
-----------------------------------------------------------------------
At your web root, /robots.txt:

    User-agent: *
    Allow: /

    Sitemap: https://yoursite.com/sitemap.xml

That is genuinely all most sites need. Two warnings, both learned the
hard way by somebody:

  * A stray "Disallow: /" — often left over from a staging site — will
    remove your entire website from every search engine, silently, and
    you will not notice for weeks. Check this file the day you go
    live. Then check it again.
  * Do not "disallow" your other languages to avoid duplicate content.
    That is what hreflang is for. Blocking them means they cannot rank
    at all, which is a very thorough way to solve a problem you did
    not have.


12. .htaccess: THE SEO-RELEVANT RULES
-----------------------------------------------------------------------
The full annotated file is elsewhere in this kit (htaccess.annotated).
These are the blocks that exist for SEO reasons specifically:

  ONE PROTOCOL — force https. http and https versions of the same page
  are two URLs with identical content: a duplicate, split between
  them.

  ONE HOST SHAPE — pick www or bare, subdomain or subdirectory, and
  redirect the others. Every alternative spelling of your address is
  another duplicate.

  BLOCK NONSENSE SUBDOMAINS — if you use wildcard DNS (*.yoursite.com)
  then fr.de.yoursite.com answers too, and serves your site, and can
  be indexed. One rule rejects stacked language labels with a 400.
  Without it, bots will find combinations you never imagined and each
  one becomes a duplicate of your homepage.

  CLEAN URLS — if your language folders live at /sites/fr/ internally,
  bounce any direct request for that path to the clean public URL.
  Plumbing should not appear in the address bar or the index.

  SITEMAP ROUTE —
      RewriteCond %{REQUEST_URI} ^/sitemap.xml$
      RewriteRule ^sitemap\.xml$ sitemap.php [L]

  ERROR PAGES — a real 404 page, in the visitor's language, is worth
  more than a server's default shrug: it keeps the visitor.

  302 WHILE BUILDING, 301 WHEN FINAL — browsers cache 301 redirects
  hard, and a wrong one haunts you for weeks. Use 302 until you are
  certain, then switch.

  KEEP THE PAPERWORK PRIVATE — if your translation tool leaves
  bookkeeping folders on the server, deny them:
      RewriteRule (^|/)\.claude(/|$) - [F]
  and while you are there, stop editor backups being served as source
  code:
      <FilesMatch "(~|\.bak|\.orig|\.swp|\.save|\.tmp)$">
         Require all denied
      </FilesMatch>
  A file called index.php~ is not executed by the server — it is
  handed out as PLAIN TEXT. That is your source code, published.


13. GOING LIVE: THE ORDER TO DO THINGS IN
-----------------------------------------------------------------------
  1.  Get ONE language right first — the original. Title, description,
      canonical, headings, alt text, article structure. Everything
      after this is multiplication, and multiplying a mistake by 38
      is a bad afternoon.

  2.  Add the language list and the hreflang loop. Check two languages
      by view-source: identical hreflang blocks, different canonical.

  3.  DNS: wildcard record if you use subdomains (*.yoursite.com).
      Nothing to do for subdirectories.

  4.  SSL: a wildcard certificate for subdomains. Free from Let's
      Encrypt via DNS validation; most control panels have a button.
      Do this BEFORE announcing anything — a certificate warning
      costs more trust than a missing language.

  5.  Upload the language folders. Test three languages by hand,
      including one right-to-left language (Arabic or Hebrew) if you
      publish one, because RTL is where layouts break.

  6.  robots.txt and sitemap.xml at the root. Load both in a browser
      and read them with your own eyes.

  7.  Submit the sitemap to Google Search Console and Bing Webmaster
      Tools. Free, once, five minutes.

  8.  Share one link on any social platform and look at the preview.
      That is your og: tags being tested for free.

  9.  Wait. Indexing takes days to weeks. Nothing is wrong.

 10.  Then, and only then, start adding pages — each one a topic, a
      URL, a title, a description. The translation of each new page
      costs pennies. The writing is the only real cost you have left.


14. THE CHECKLIST
-----------------------------------------------------------------------
Print this. Tick it per site, not per page.

  [ ] every page has its own <title>
  [ ] every page has its own <meta description>
  [ ] every page has a canonical pointing AT ITSELF, in its own
      language, with no redirect at the other end
  [ ] hreflang lists every language INCLUDING the page's own
  [ ] hreflang points page-to-page, not page-to-homepage
  [ ] x-default is present
  [ ] <html lang="xx"> matches the actual language of the page
  [ ] exactly one <h1> per page
  [ ] headings run h1 -> h2 -> h3 with no skipped levels
  [ ] content is inside <article> (or at minimum, wrapped once)
  [ ] every meaningful image has alt text
  [ ] brand names / commands / codes are wrapped in NOtr markers
  [ ] language picker labels are NOtr-wrapped (EN stays EN)
  [ ] og: and twitter: tags present; preview checked on one platform
  [ ] robots.txt exists and does NOT say Disallow: /
  [ ] sitemap.xml loads, lists all languages, submitted to Google+Bing
  [ ] https forced; one host shape; redirects are 301 only when final
  [ ] 404 page is yours, not the server's
  [ ] backup files (*~ .bak .orig) are denied by the server
  [ ] tool paperwork folders are denied by the server
  [ ] tested in at least three languages, one of them RTL if you have
      one


15. ASKING AN AI TO DO THIS FOR YOU (THE HONEST VERSION)
-----------------------------------------------------------------------
Everything above is mechanical, which makes it exactly the kind of
work an AI does well. If you would rather not hand-write it:

  * Send it your page and say:
        "Write the SEO head block for this page: title, meta
         description, canonical, hreflang for these languages [list],
         x-default, and Open Graph tags. My domain is yoursite.com and
         I use [subdomains / subdirectories]."

  * Then:
        "Now show me where the <article> tag and the headings should
         go on this page, and tell me if I have more than one h1."

  * And:
        "Which parts of this page should NOT be translated? Show me
         where to put the NOtr markers."

  * For structure across a whole site:
        "Here are my ten pages. Suggest one title and one 150-character
         description for each, each targeting a different search
         phrase, with no two competing for the same one."

What an AI is good at here: the boilerplate, the consistency, spotting
the missing tag, writing forty descriptions without getting bored.

What it is not good at: knowing what your customers actually search
for, in their language, in their country. That is your job, and it is
the part that is actually worth doing well. A perfect head block on a
page nobody wants ranks for nothing.

One last thing. Do what we did: right-click any page of jit-tr.com,
View Source, and read the <head>. Everything in this file is in there,
working, in 38 languages. Copy it. That is why it's readable.

=======================================================================
 Free, from jit-tr.com — the same setup we run in production.
 The translator: free, yours to keep.
 The translation service that fills it: $10/month per website.
=======================================================================
