From 77e47592210c73b0331bd8e2c1211adfd8c70038 Mon Sep 17 00:00:00 2001
From: Tomoki Kobayashi <temoki@gmail.com>
Date: Thu, 27 Aug 2026 20:17:01 +0900
Subject: [PATCH 1/2] Give each language a URL a search engine can index
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Both pages already read in one language and already take it from `?lang=`,
which is where App Store Connect's per-localization URLs point. What was
missing is that nothing said so. A crawler renders the page, the script
negotiates from navigator.languages — `en-US` for Googlebot — and the
Japanese half goes display:none, on the one URL anybody links to. So the
Japanese page was not ranked badly; it did not exist.

Three things fix that, and none of them changes how the site works.

hreflang alternates in both heads, naming `?lang=en`, `?lang=ja` and the bare
URL as x-default. The set is identical on every variant, self-reference
included, which is what lets one file serve all three. There is deliberately
no rel=canonical: it would have to differ per URL, and a static one pointing
anywhere folds the other two into it and un-indexes the Japanese page, while
a script-written one is the case Google says not to rely on.

Real links in both footers. The picker is a <select>, which a crawler cannot
follow, so until now the Japanese URL was declared in the head and reachable
from nowhere.

And a per-language meta description, carried on the section like the title
already was, so adding a language is still a code, an <option> and a
translated <section>. The static one stays bilingual, because that is what
the bare URL and a script-less reader get.

The OG card stays single and stays English, and the comment saying why now
says the real reason: a social scraper does not run the script that picks a
language, so per-language cards would have to be written by JavaScript
nothing would execute.
---
 site/index.html   | 38 +++++++++++++++++++++++++++++++++++---
 site/privacy.html | 37 +++++++++++++++++++++++++++++++------
 2 files changed, 66 insertions(+), 9 deletions(-)

diff --git a/site/index.html b/site/index.html
index 1e9eb86..5f51151 100644
--- a/site/index.html
+++ b/site/index.html
@@ -7,7 +7,23 @@
 <meta name="description" content="Tortoise Blocks is a visual programming app for kids on iPad, Mac and Apple Vision Pro: snap blocks together, press play, and watch the tortoise draw. Tortoise Blocks は、ブロックをならべてカメに絵をかいてもらう、iPad と Mac と Apple Vision Pro のための子ども向けプログラミングアプリです。">
 <link rel="icon" href="icon-176.png">
 
-<!-- One card serves both languages, because both are served from one URL. -->
+<!-- Each language is a URL, so each language is a page a search engine can
+     index on its own. The set is identical on every variant, self-reference
+     included, which is exactly what lets it be static in one file that serves
+     all three; `x-default` is the bare URL because that is the one that
+     negotiates. There is deliberately no `rel=canonical`: it would have to
+     differ per URL, and one file cannot say three things — a static one
+     pointing anywhere folds the other two into it and un-indexes the Japanese
+     page, while a script-written one is the case Google says not to rely on.
+     hreflang carries the relationship instead, which is what it is for. -->
+<link rel="alternate" hreflang="en" href="https://temoki.github.io/TortoiseBlocks/?lang=en">
+<link rel="alternate" hreflang="ja" href="https://temoki.github.io/TortoiseBlocks/?lang=ja">
+<link rel="alternate" hreflang="x-default" href="https://temoki.github.io/TortoiseBlocks/">
+
+<!-- One card for both languages, and English by default. The alternates
+     above give each language a URL, but a social scraper is not a browser: it
+     does not run the script that picks a language, so a per-language card
+     would have to be written by JavaScript nothing would execute. -->
 <meta property="og:type" content="website">
 <meta property="og:site_name" content="Tortoise Blocks">
 <meta property="og:title" content="Tortoise Blocks">
@@ -239,7 +255,9 @@
 <main>
 
 <!-- ============================ English ============================= -->
-<section lang="en" data-title="Tortoise Blocks — Snap blocks together, watch the tortoise draw">
+<section lang="en"
+         data-title="Tortoise Blocks — Snap blocks together, watch the tortoise draw"
+         data-description="A visual programming app for kids on iPad, Mac and Apple Vision Pro. Snap blocks into a program, press play, and watch a tortoise draw your picture.">
 
   <div class="hero">
     <img class="icon" src="icon-256.png" alt="" width="112" height="112">
@@ -451,7 +469,9 @@ <h2>Quiet about the child using it</h2>
 </section>
 
 <!-- ============================ 日本語 ============================== -->
-<section lang="ja" data-title="Tortoise Blocks — ブロックをならべて、カメに絵をかいてもらおう">
+<section lang="ja"
+         data-title="Tortoise Blocks — ブロックをならべて、カメに絵をかいてもらおう"
+         data-description="iPad と Mac と Apple Vision Pro のための子ども向けビジュアルプログラミングアプリ。ブロックをならべて再生ボタンを押すと、カメが1本ずつ線をかいていきます。">
 
   <div class="hero">
     <img class="icon" src="icon-256.png" alt="" width="112" height="112">
@@ -608,6 +628,11 @@ <h2>使う子どものことを、何も集めません</h2>
   <a href="https://github.com/temoki/TortoiseBlocks">GitHub</a>
   <a href="privacy.html">Privacy / プライバシー</a>
   <a href="https://github.com/temoki/TortoiseBlocks/issues">Issues</a>
+  <!-- Real links, and not a second picker: a <select> is not something a
+       crawler can follow, so without these the Japanese URL is declared in the
+       head and reachable from nowhere. -->
+  <a href="?lang=en" hreflang="en" lang="en">English</a>
+  <a href="?lang=ja" hreflang="ja" lang="ja">日本語</a>
   <span>© hiraku.space</span>
 </footer>
 
@@ -624,6 +649,13 @@ <h2>使う子どものことを、何も集めません</h2>
       // so a new language needs no edit here.
       var section = document.querySelector('section[lang="' + lang + '"]');
       if (section && section.dataset.title) document.title = section.dataset.title;
+      // The static description names both languages, because that is what the
+      // bare URL and a script-less reader get. Once a language is resolved the
+      // page is only in that one, and the description should say so.
+      var desc = document.querySelector('meta[name="description"]');
+      if (desc && section && section.dataset.description) {
+        desc.setAttribute("content", section.dataset.description);
+      }
       if (remember) {
         // The choice rides in the URL, not in storage: this site promises the
         // app stores nothing, and the page has no business doing otherwise —
diff --git a/site/privacy.html b/site/privacy.html
index c87675f..a6b89b3 100644
--- a/site/privacy.html
+++ b/site/privacy.html
@@ -7,8 +7,22 @@
 <meta name="description" content="Tortoise Blocks collects no data and makes no network connections. Tortoise Blocks は利用者の情報を一切収集せず、ネットワーク通信も行いません。">
 <link rel="icon" href="icon-176.png">
 
-<!-- The same card as the landing page, and English for the same reason: both
-     languages of this page live at one URL, so a preview can only be one. -->
+<!-- Each language is a URL, so each language is a page a search engine can
+     index on its own. The set is identical on every variant, self-reference
+     included, which is exactly what lets it be static in one file that serves
+     all three; `x-default` is the bare URL because that is the one that
+     negotiates. There is deliberately no `rel=canonical`: it would have to
+     differ per URL, and one file cannot say three things — a static one
+     pointing anywhere folds the other two into it and un-indexes the Japanese
+     page, while a script-written one is the case Google says not to rely on.
+     hreflang carries the relationship instead, which is what it is for. -->
+<link rel="alternate" hreflang="en" href="https://temoki.github.io/TortoiseBlocks/privacy.html?lang=en">
+<link rel="alternate" hreflang="ja" href="https://temoki.github.io/TortoiseBlocks/privacy.html?lang=ja">
+<link rel="alternate" hreflang="x-default" href="https://temoki.github.io/TortoiseBlocks/privacy.html">
+
+<!-- The same card as the landing page, and English for the same reason: a
+     social scraper does not run the script that picks a language, so the
+     per-language URLs declared above buy a preview nothing. -->
 <meta property="og:type" content="article">
 <meta property="og:site_name" content="Tortoise Blocks">
 <meta property="og:title" content="Privacy Policy — Tortoise Blocks">
@@ -150,7 +164,8 @@ <h1>Tortoise&nbsp;Blocks</h1>
   </div>
 </header>
 
-<section lang="en">
+<section lang="en"
+         data-description="Tortoise Blocks collects no information about the people who use it: no accounts, no analytics, no advertising, and no network connections at all.">
 
   <h2 style="border-top:0;padding-top:0;margin-top:2.5rem">Privacy Policy</h2>
 
@@ -248,7 +263,8 @@ <h2>8. Contact</h2>
 
 </section>
 
-<section lang="ja">
+<section lang="ja"
+         data-description="Tortoise Blocks は利用者の情報を一切収集しません。アカウントも、解析も、広告も、ネットワーク通信もありません。">
 
   <h2 style="border-top:0;padding-top:0;margin-top:2.5rem">プライバシーポリシー</h2>
 
@@ -327,7 +343,9 @@ <h2>8. お問い合わせ</h2>
 
 <footer>
   <a href="./">Tortoise Blocks</a> ·
-  <a href="https://github.com/temoki/TortoiseBlocks">GitHub</a>
+  <a href="https://github.com/temoki/TortoiseBlocks">GitHub</a> ·
+  <a href="?lang=en" hreflang="en" lang="en">English</a> ·
+  <a href="?lang=ja" hreflang="ja" lang="ja">日本語</a>
 </footer>
 
 </main>
@@ -343,8 +361,15 @@ <h2>8. お問い合わせ</h2>
       select.value = lang;
       // Taken from the page rather than a parallel list of titles, so a new
       // language needs no edit here.
-      var heading = document.querySelector('section[lang="' + lang + '"] h2');
+      var section = document.querySelector('section[lang="' + lang + '"]');
+      var heading = section && section.querySelector("h2");
       if (heading) document.title = heading.textContent.trim() + " — Tortoise Blocks";
+      // The static description names both languages, because that is what the
+      // bare URL and a script-less reader get.
+      var desc = document.querySelector('meta[name="description"]');
+      if (desc && section && section.dataset.description) {
+        desc.setAttribute("content", section.dataset.description);
+      }
       if (remember) {
         // The choice rides in the URL, not in storage: a page promising no
         // data collection has no business writing localStorage, and this

From e9fe946010a93df759954df0c3236d5629663741 Mon Sep 17 00:00:00 2001
From: Tomoki Kobayashi <temoki@gmail.com>
Date: Thu, 27 Aug 2026 20:18:39 +0900
Subject: [PATCH 2/2] Say what the app is, and where the pages are
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A sitemap and a structured-data block, which is the rest of what the search
turned up. Neither changes a word the reader sees.

site/sitemap.xml lists six URLs rather than two: an hreflang set names every
variant from every variant, so each of the three addresses each page answers
to gets an entry carrying the whole set. It has no lastmod, changefreq or
priority — Google ignores the last two, and lastmod only counts while it is
honest, which a hand-deployed site would not keep it.

It is meant to be submitted in Search Console rather than announced from a
robots.txt, and that is not a preference. A robots.txt is only read at the
host root — temoki.github.io/robots.txt — which belongs to no repository
here, so one added to site/ would be served, ignored, and easy to mistake
for working. A sitemap may sit at any level at or above what it lists.

The JSON-LD is the weakest item of the four and is written to stay checkable:
the price, the family rating and the seller come from the App Store listing,
the license from LICENSE, the requirements from the specs table further down
the page. It carries no aggregateRating, and must not grow one that nobody
left.
---
 .claude/skills/release/SKILL.md | 37 +++++++++++++++++++++
 site/index.html                 | 43 ++++++++++++++++++++++++
 site/sitemap.xml                | 58 +++++++++++++++++++++++++++++++++
 3 files changed, 138 insertions(+)
 create mode 100644 site/sitemap.xml

diff --git a/.claude/skills/release/SKILL.md b/.claude/skills/release/SKILL.md
index 75178fd..7799e76 100644
--- a/.claude/skills/release/SKILL.md
+++ b/.claude/skills/release/SKILL.md
@@ -87,6 +87,43 @@ quantization is what keeps that a non-issue. Only CSS `background-image` would a
 not worth trading `<img alt>` on the page's content images to save one
 language's worth of cached bytes.
 
+**The site is registered with Google Search Console, and the SEO is three
+files' worth of plumbing rather than copywriting.** The landing page went a
+month without appearing in a search, and the first suspicion — that something
+was blocking crawlers — was wrong: there is no `robots.txt` anywhere, no
+`noindex`, no `X-Robots-Tag`, and the repository is public. It had simply never
+been registered, and one thing about it was genuinely broken. **A crawler
+renders the page, so it negotiates like a browser** — Googlebot's
+`navigator.languages` is `en-US` — and the Japanese `<section>` therefore goes
+`display:none` on the one URL anyone links to. The Japanese page was not
+ranking badly; it did not exist. The fix keeps every decision above intact:
+hreflang alternates naming `?lang=en`, `?lang=ja` and the bare URL as
+`x-default`, real `<a href="?lang=…">` links in both footers because a
+`<select>` is not something a crawler can follow, and a `data-description` on
+each section beside the `data-title` that was already there — so adding a
+language is still a code, an `<option>` and a translated `<section>`.
+**There is deliberately no `rel=canonical`.** It would have to differ per URL,
+and one file cannot say three things: a static one pointing anywhere folds the
+other two into it and un-indexes the Japanese page, while a script-written one
+is the case Google says not to rely on. hreflang carries the relationship, and
+that is what it is for. The `?lang=` spelling is not free to change either —
+it is what `appstore/metadata*/*/marketing_url.txt` and `privacy_url.txt`
+already point at, so a move to `/ja/` paths would mean re-pushing both
+listings.
+`site/sitemap.xml` lists six URLs rather than two, because an hreflang set has
+to name every variant from every variant. It carries no `lastmod`: the site is
+deployed by hand at release time, so the date would go stale the first time
+someone forgot it, and Google ignores a lastmod it cannot trust. **It is
+submitted in Search Console, not announced from a `robots.txt`** — a
+`robots.txt` is only read at the *host* root, `temoki.github.io/robots.txt`,
+which belongs to no repository here; one placed in `site/` would be served,
+ignored, and mistaken for working. A sitemap has no such rule and may sit at
+any level at or above the URLs it lists.
+The JSON-LD `SoftwareApplication` block is the weakest of these and is kept
+honest on purpose: every value in it is checkable against the App Store
+listing, `LICENSE`, or the specs table on the page itself, and there is no
+`aggregateRating` — nor may one ever be added that nobody left.
+
 **The landing page is written for parents and teachers**, not for the kid and
 not for a developer — the technical account lives in the README. Three things
 about it are decisions rather than taste. The App Store badge is Apple's own
diff --git a/site/index.html b/site/index.html
index 5f51151..1beb6c1 100644
--- a/site/index.html
+++ b/site/index.html
@@ -35,6 +35,49 @@
 <meta property="og:image:alt" content="The Tortoise Blocks tortoise, in a purple beret with a paintbrush for a tail.">
 <meta name="twitter:card" content="summary_large_image">
 
+<!-- What the page says about the app, in a form a search engine reads without
+     guessing. Every value here is checkable against something: the price, the
+     age rating and the seller come from the App Store listing, the license
+     from LICENSE, the requirements from the specs table below. There is no
+     aggregateRating and there must never be one that nobody left.
+
+     It is written once and in English rather than per language, because these
+     are facts about the app rather than prose — and because a script-written
+     one would arrive after the crawl for the same reason the OG card is
+     single. -->
+<script type="application/ld+json">
+{
+  "@context": "https://schema.org",
+  "@type": "SoftwareApplication",
+  "name": "Tortoise Blocks",
+  "description": "A visual programming app for kids on iPad, Mac and Apple Vision Pro. Snap blocks into a program, press play, and watch a tortoise draw your picture.",
+  "url": "https://temoki.github.io/TortoiseBlocks/",
+  "applicationCategory": "EducationalApplication",
+  "operatingSystem": "iPadOS 26 or later, macOS 26 or later, visionOS 26 or later",
+  "downloadUrl": "https://apps.apple.com/app/id6798677334",
+  "installUrl": "https://apps.apple.com/app/id6798677334",
+  "screenshot": "https://temoki.github.io/TortoiseBlocks/shots/ipad-en-1.png",
+  "inLanguage": [
+    "en",
+    "ja"
+  ],
+  "isFamilyFriendly": true,
+  "author": {
+    "@type": "Person",
+    "name": "Tomoki Kobayashi"
+  },
+  "license": "https://opensource.org/license/mit",
+  "isAccessibleForFree": true,
+  "offers": {
+    "@type": "Offer",
+    "price": "0",
+    "priceCurrency": "USD"
+  },
+  "privacyPolicy": "https://temoki.github.io/TortoiseBlocks/privacy.html",
+  "codeRepository": "https://github.com/temoki/TortoiseBlocks"
+}
+</script>
+
 <style>
   /* The palette is the app's own: the accent is the mascot's purple, the same
      literal both appearances use in the app. Kept in step with privacy.html. */
diff --git a/site/sitemap.xml b/site/sitemap.xml
new file mode 100644
index 0000000..6fec477
--- /dev/null
+++ b/site/sitemap.xml
@@ -0,0 +1,58 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+  Six URLs, not two: an hreflang set has to name every variant from every
+  variant, so each of the three addresses each page answers to gets its own
+  entry carrying the whole set. They are the same alternates the pages
+  declare in their heads — a sitemap is where a crawler finds the Japanese
+  URL before it has rendered anything.
+
+  No <lastmod>, <changefreq> or <priority>. Google ignores the last two
+  outright, and lastmod only counts while it is honest: the site is
+  deployed by hand at release time, so a date in here would be one more
+  thing to remember and would go stale the first time it was forgotten.
+
+  This file is submitted in Search Console rather than announced from a
+  robots.txt, because a robots.txt is only read at the host root —
+  temoki.github.io/robots.txt — which belongs to no repository here. A
+  sitemap has no such rule: it may sit at any level at or above the URLs
+  it lists.
+-->
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"
+        xmlns:xhtml="http://www.w3.org/1999/xhtml">
+  <url>
+    <loc>https://temoki.github.io/TortoiseBlocks/?lang=en</loc>
+    <xhtml:link rel="alternate" hreflang="en" href="https://temoki.github.io/TortoiseBlocks/?lang=en"/>
+    <xhtml:link rel="alternate" hreflang="ja" href="https://temoki.github.io/TortoiseBlocks/?lang=ja"/>
+    <xhtml:link rel="alternate" hreflang="x-default" href="https://temoki.github.io/TortoiseBlocks/"/>
+  </url>
+  <url>
+    <loc>https://temoki.github.io/TortoiseBlocks/?lang=ja</loc>
+    <xhtml:link rel="alternate" hreflang="en" href="https://temoki.github.io/TortoiseBlocks/?lang=en"/>
+    <xhtml:link rel="alternate" hreflang="ja" href="https://temoki.github.io/TortoiseBlocks/?lang=ja"/>
+    <xhtml:link rel="alternate" hreflang="x-default" href="https://temoki.github.io/TortoiseBlocks/"/>
+  </url>
+  <url>
+    <loc>https://temoki.github.io/TortoiseBlocks/</loc>
+    <xhtml:link rel="alternate" hreflang="en" href="https://temoki.github.io/TortoiseBlocks/?lang=en"/>
+    <xhtml:link rel="alternate" hreflang="ja" href="https://temoki.github.io/TortoiseBlocks/?lang=ja"/>
+    <xhtml:link rel="alternate" hreflang="x-default" href="https://temoki.github.io/TortoiseBlocks/"/>
+  </url>
+  <url>
+    <loc>https://temoki.github.io/TortoiseBlocks/privacy.html?lang=en</loc>
+    <xhtml:link rel="alternate" hreflang="en" href="https://temoki.github.io/TortoiseBlocks/privacy.html?lang=en"/>
+    <xhtml:link rel="alternate" hreflang="ja" href="https://temoki.github.io/TortoiseBlocks/privacy.html?lang=ja"/>
+    <xhtml:link rel="alternate" hreflang="x-default" href="https://temoki.github.io/TortoiseBlocks/privacy.html"/>
+  </url>
+  <url>
+    <loc>https://temoki.github.io/TortoiseBlocks/privacy.html?lang=ja</loc>
+    <xhtml:link rel="alternate" hreflang="en" href="https://temoki.github.io/TortoiseBlocks/privacy.html?lang=en"/>
+    <xhtml:link rel="alternate" hreflang="ja" href="https://temoki.github.io/TortoiseBlocks/privacy.html?lang=ja"/>
+    <xhtml:link rel="alternate" hreflang="x-default" href="https://temoki.github.io/TortoiseBlocks/privacy.html"/>
+  </url>
+  <url>
+    <loc>https://temoki.github.io/TortoiseBlocks/privacy.html</loc>
+    <xhtml:link rel="alternate" hreflang="en" href="https://temoki.github.io/TortoiseBlocks/privacy.html?lang=en"/>
+    <xhtml:link rel="alternate" hreflang="ja" href="https://temoki.github.io/TortoiseBlocks/privacy.html?lang=ja"/>
+    <xhtml:link rel="alternate" hreflang="x-default" href="https://temoki.github.io/TortoiseBlocks/privacy.html"/>
+  </url>
+</urlset>