DEV Community

Ian
Ian

Posted on

Four locales, one Next.js app: the hreflang mistakes I made so you don't have to

I run a small product in four languages — Japanese, English, French, Spanish. Japanese is the primary market, which means the usual English-first advice does not apply.

Here are the mistakes I made, in the order I made them.

Mistake 1: slug translation that broke the URL map

The obvious approach is to translate slugs. /ja/examples/yujin-daihyo and /fr/examples/frere-soeur-fr describe the same concept, so they should obviously have different slugs, right?

They should. But then hreflang needs to know which slug maps to which, in every direction:

export function categoryHreflang(slug: string) {
  const group = groups.find((g) => Object.values(g).includes(slug));
  if (!group) return undefined;
  const out: Record<string, string> = {};
  for (const [locale, s] of Object.entries(group)) {
    out[locale] = `${SITE_URL}/${locale}/examples/${s}`;
  }
  return out;
}
Enter fullscreen mode Exit fullscreen mode

This is a hand-maintained map. If you add a category in one locale and forget the others, hreflang silently points at 404s. Google does not tell you. You find out in Search Console three weeks later, if at all.

What I'd do differently: generate the map from the data, not by hand. One slug per category shared across locales, with translated title/intro only. Less charming URLs, zero broken hreflang.

Mistake 2: treating <meta name="description"> as unique

I wrote a check that looked for [name="description"] and asserted it had content. It passed on pages where the description was empty, because the selector also matched the <meta> tag's own attributes rather than a form field elsewhere on the page.

// What I meant:
document.querySelector('textarea[name="description"]').value

// What also matched, and hid the bug:
document.querySelector('[name="description"]')
Enter fullscreen mode Exit fullscreen mode

Small lesson: when a selector passes, check that it selected the thing you think it did.

Mistake 3: same word-length rule for every language

English wedding speeches: 350–600 words, 3–5 minutes. That's ~130 words per minute.

Japanese: 600–900 characters, 2–3 minutes. That's ~300 characters per minute.

These are not the same measurement, and a rule written for one produces nonsense in the other. Japanese has no word delimiters, so body.split(/\s+/).length gives you a number that means nothing:

const count = locale === "ja"
  ? body.length                      // characters
  : body.trim().split(/\s+/).length; // words
Enter fullscreen mode Exit fullscreen mode

The same applies to anything that measures text: density, reading time, keyword frequency. Every one of those needs a locale branch.

Mistake 4: assuming the same content depth works everywhere

I compared my pages against competitors in French and found this:

Site Body text
mariages.net 21,746
blog.ungrandjour.com 16,115
parlerdamour.fr 10,971
mine 3,653

I was ranking around position 82. Not because the site had a technical problem, and not because the content was wrong — but because it was one-sixth the size of everything around it.

After adding examples and FAQ blocks, that page went to 7,437 characters. Exposure roughly doubled in the following days. Not proof, but not nothing.

The part worth noting: I assumed my per-locale pages were equivalent because they used the same template. They had wildly different depth depending on how much I'd happened to write for each language.

Mistake 5: FAQ markup with no visible FAQ

Schema markup must match what's on the page. Adding FAQPage JSON-LD without rendering the same questions as visible content is at best ignored and at worst a manual action.

So the FAQ data lives in one place and produces both:

{cat.faq?.length > 0 && <FaqJsonLd items={cat.faq} />}
{/* and, further down */}
{cat.faq?.map((item) => (
  <details key={item.q}>
    <summary>{item.q}</summary>
    <p>{item.a}</p>
  </details>
))}
Enter fullscreen mode Exit fullscreen mode

One array, two outputs. If they ever diverge, it's a bug, not a choice.

The uncomfortable summary

None of these are hard problems. Each one cost me days anyway, because the feedback loop on SEO is measured in weeks and the failure mode is silence.

If I were starting again, the checklist would be:

  1. Shared slugs across locales; translate content, not URLs
  2. Every text metric gets a locale branch
  3. Compare content depth to competitors per locale, not per site
  4. Generate hreflang from data
  5. Schema and visible content come from the same source

(The product is Speech Kobo — wedding speeches in four languages. The etiquette dataset behind it is open on GitHub.)

Top comments (1)

Collapse
 
fivehandsstudio profile image
Five Hands Studio •

Mistake 1 matches something we see a lot checking indie founder sites: in a sample of 10, missing or wrong hreflang/language tags showed up as one of the five most common problems, alongside slogan-only headings and brand-first titles. Most weren't multi-locale sites like yours, just a single language tag that didn't match the actual content. Your point about generating the map from data instead of hand-maintaining it is the right fix either way, since the hand-maintained version is exactly where it silently breaks.