The language link ran one way

The Miyako de IT website has English pages that pair with its Japanese pages. The hreflang annotations in each page's HTML head are what tell search engines about that pairing. An audit on October 31, 2026 found that five Japanese pages were not emitting them. This article covers the three that were fixed. The English pages pointed to their Japanese counterparts, but the Japanese pages did not point back. The language relationship ran one way only.

This is a record of how we confirmed the problem, what we changed and what we checked in production. The change is PR #382, released to production on November 2, 2026. We have not yet measured any effect on search traffic or participation.

How it was found

It surfaced during a check of public pages in Issue #349, where we track our search-related work. On October 31 we fetched 22 key Japanese and English URLs again. All returned HTTP 200 and all had a title and description. However, five Japanese pages had zero hreflang links in the head, while each of their English counterparts emitted three.

PR #382 fixed three of those pairs:

The English side emitted ja, en and x-default; the Japanese side emitted only a canonical. For the same pair, only one side said "there is a matching page." The site's i18n design also prohibits one-sided hreflang.

The cause: metadata written directly on each page

The site has a shared function, buildAlternates (lib/i18n/metadata.ts), that builds the canonical and hreflang together. The English pages went through it. The three Japanese pages, however, still used an older pattern that wrote only the canonical directly.

The function works like this:

• It builds the absolute Japanese and English URLs and uses the URL for the language being shown as the canonical
• If the site-wide English publication flag is off, or the route has not passed English quality checks, it returns only the canonical
• When the publication conditions are met, it returns ja, en and x-default, with x-default set to the Japanese URL

Because the decision about whether a pair may be published lives inside the function, pages never need to write hreflang by hand. Only the pages that wrote their metadata directly sat outside that decision.

The same change in all three files

The fix replaces the metadata on the three Japanese pages with the shared function. This is the change on the FAQ page (excluding the added import line):

• Before alternates: { canonical: "https://www.miyakodeit.com/faq" },
• After ...buildAlternates("/faq", "ja"),

/sponsor and /guides/kyoto-mokumoku received the same replacement with their own paths. Body text, CSS, CTAs, titles, descriptions, OGP and structured data were not changed. The PR touched six files in total; the other three are a regression test, a visual-review record and a LEARNINGS entry recording what was learned.

A test that reads the real page definitions

The regression test (__tests__/lib/reciprocal-hreflang.test.ts) does not just exercise the shared function. It loads the metadata that each Japanese and English page file actually exports. Even if the function is correct, the bug remains if a page does not use it.

It checks two conditions per pair, six cases across the three pairs:

• With English publication ON, the Japanese page and the English page each emit their own canonical and exactly the same set of ja, en and x-default
• With English publication OFF, both emit only their canonical

When the Japanese sources were reverted to their pre-fix state and the same test was run, the three publication-ON cases failed because hreflang was missing, and the three OFF cases passed. After the fix, all six cases pass. Using an input that fails confirmed that the test can actually detect this bug, rather than simply passing.

Checks in production

PR #382 was accepted in this order:

An HTTP 200 alone is not evidence that a change is live. We read the canonical and hreflang actually emitted in the head of all six URLs.

What we do not know yet

What has been confirmed covers the implementation, the tests, CI, independent QC and production HTML. These remain unknown:

• When and how search engines will act on this relationship
• Whether search impressions or clicks, or participation and inquiries arriving via English pages, will increase

We plan to compare equal-length periods after release, and we do not count any of these as results of this fix.

The October 31 audit also found zero hreflang links on the Japanese /first-time and /contact pages. Those two pages were outside the scope of PR #382, and in the main-branch source as of November 2, 2026 their Japanese side still emits only a canonical. Their English side goes through the shared function, so the same one-way relationship remains. That will be handled as separate work.

Finding the same bug on your own site

If your site has English versions, these steps will find the same one-way relationship:

• Fetch the HTML of both the Japanese and the English page and count hreflang links in the head. If only one side has zero, the relationship is one-way
• Search for places where canonical or hreflang is written directly on individual pages, and move them to a shared function
• Make tests read the actual page definitions, not just the shared function, and confirm they fail when the fix is reverted

Miyako de IT publishes records of site-improvement work like this. If you are working on something similar, find a mokumoku session in the event list and bring the next step of your work.