Skip to the code

hreflang links between English and French tea pages

Leaf and Kettle is in English and French. Every page lives under app/[lang], and each language has its own slugs: the English green tea is /en/teas/green-tea, and the French one is /fr/teas/the-vert. Some teas are only written in one language so far. Google should show each searcher the version in their language, and know the two are one page. hreflang links say that, and alternates.languages in metadata makes them.

Write app/[lang]/teas/[slug]/page.tsx: the page and its generateMetadata, which both get params, a promise of { lang, slug }. @/lib/catalog has teas, each with text for the languages it's written in, and findTea(lang, slug), which finds a tea by its slug in one language.

Both start the same way. A lang that isn't in locales is a 404, with notFound(). A slug that's another language's slug for a tea that's in this language too, like /fr/teas/green-tea, gets a permanent redirect to this language's page, /fr/teas/the-vert, with permanentRedirect(). Any other slug that no tea has in this language is a 404.

generateMetadata returns the tea's name in this language as title, and in alternates, the page's own path as canonical. When the tea is in both languages, languages has each version's path under its language code, en and fr, the same from both pages, and x-default with the English path, for searchers who read neither. A tea in one language has no other version to point to, so it has no languages.

In openGraph, locale is ogLocale's name for this language, and alternateLocale lists the other language's name when the tea is in it.

The page shows the tea's name in an <h1> and its about text, in this language.

/fr/teas/the-vert → {
  title: "Thé vert",
  alternates: {
    canonical: "/fr/teas/the-vert",
    languages: { en: "/en/teas/green-tea", fr: "/fr/teas/the-vert", "x-default": "/en/teas/green-tea" },
  },
  openGraph: { locale: "fr_FR", alternateLocale: ["en_US"] },
}
/fr/teas/green-tea        → 308 to /fr/teas/the-vert
/fr/teas/lapsang-souchong → 404 (no French page yet)

The app's other files

lib/catalog.ts, read-only. Import it as @/lib/catalog.

export type Locale = "en" | "fr";
 
/** The languages the shop is written in. Every page lives under app/[lang], like app/[lang]/teas/[slug]/page.tsx. */
export const locales: Locale[] = ["en", "fr"];
 
/** The shop's main language: the version for searchers who read neither. */
export const defaultLocale: Locale = "en";
 
/** Open Graph's name for each language's audience. */
export const ogLocale: Record<Locale, string> = { en: "en_US", fr: "fr_FR" };
 
/** A tea's page in one language: its slug, its name, and its description. */
export type TeaText = { slug: string; name: string; about: string };
 
/** A tea, with its text in each language it's written in. A tea not translated yet has only one. */
export type Tea = { id: string; text: Partial<Record<Locale, TeaText>> };
 
export const teas: Tea[] = [
  {
    id: "green",
    text: {
      en: { slug: "green-tea", name: "Green tea", about: "Light and grassy." },
      fr: { slug: "the-vert", name: "Thé vert", about: "Léger et herbacé." },
    },
  },
  {
    id: "mint",
    text: {
      en: { slug: "mint-tea", name: "Mint tea", about: "Cool and sweet." },
      fr: { slug: "the-a-la-menthe", name: "Thé à la menthe", about: "Frais et doux." },
    },
  },
  {
    id: "lapsang",
    text: { en: { slug: "lapsang-souchong", name: "Lapsang souchong", about: "Smoky and bold." } },
  },
  {
    id: "verveine",
    text: { fr: { slug: "tisane-verveine", name: "Tisane de verveine", about: "Douce et apaisante." } },
  },
];
 
/** The tea whose slug in `lang` is `slug`, or undefined when there's none. */
export async function findTea(lang: Locale, slug: string): Promise<Tea | undefined> {
  return teas.find((tea) => tea.text[lang]?.slug === slug);
}

What the tests check

  1. each page's title and canonical URL are its own, in its language
    const metadataFor = (lang, slug) => generateMetadata({ params: params({ lang, slug }) });
    const en = await metadataFor("en", "green-tea");
    expect(en.title).toBe("Green tea");
    expect(en.alternates?.canonical).toBe("/en/teas/green-tea");
    const fr = await metadataFor("fr", "the-vert");
    expect(fr.title).toBe("Thé vert");
    expect(fr.alternates?.canonical).toBe("/fr/teas/the-vert");
    
  2. hreflang links name both versions and x-default, the same from either page
    const metadataFor = (lang, slug) => generateMetadata({ params: params({ lang, slug }) });
    const green = { en: "/en/teas/green-tea", fr: "/fr/teas/the-vert", "x-default": "/en/teas/green-tea" };
    expect((await metadataFor("en", "green-tea")).alternates?.languages).toEqual(green);
    expect((await metadataFor("fr", "the-vert")).alternates?.languages).toEqual(green);
    expect((await metadataFor("fr", "the-a-la-menthe")).alternates?.languages).toEqual({
      en: "/en/teas/mint-tea",
      fr: "/fr/teas/the-a-la-menthe",
      "x-default": "/en/teas/mint-tea",
    });
    
  3. a tea in one language has no hreflang links
    const metadataFor = (lang, slug) => generateMetadata({ params: params({ lang, slug }) });
    const lapsang = await metadataFor("en", "lapsang-souchong");
    expect(lapsang.alternates?.canonical).toBe("/en/teas/lapsang-souchong");
    expect(lapsang.alternates.languages).toBeUndefined();
    const verveine = await metadataFor("fr", "tisane-verveine");
    expect(verveine.alternates?.canonical).toBe("/fr/teas/tisane-verveine");
    expect(verveine.alternates.languages).toBeUndefined();
    
  4. Open Graph names the page's locale, and the other one when there is one
    const metadataFor = (lang, slug) => generateMetadata({ params: params({ lang, slug }) });
    const others = (meta) => [].concat(meta.openGraph?.alternateLocale ?? []);
    const fr = await metadataFor("fr", "the-vert");
    expect(fr.openGraph?.locale).toBe("fr_FR");
    expect(others(fr)).toEqual(["en_US"]);
    const en = await metadataFor("en", "mint-tea");
    expect(en.openGraph?.locale).toBe("en_US");
    expect(others(en)).toEqual(["fr_FR"]);
    const lapsang = await metadataFor("en", "lapsang-souchong");
    expect(lapsang.openGraph?.locale).toBe("en_US");
    expect(others(lapsang)).toEqual([]);
    
  5. the other language's slug redirects for good to this language's page
    const metadataFor = (lang, slug) => generateMetadata({ params: params({ lang, slug }) });
    const toFrench = await redirectOf(() => metadataFor("fr", "green-tea"));
    expect([toFrench.url, toFrench.status]).toEqual(["/fr/teas/the-vert", 308]);
    const toEnglish = await redirectOf(() => renderServer(<Page params={params({ lang: "en", slug: "the-a-la-menthe" })} />));
    expect([toEnglish.url, toEnglish.status]).toEqual(["/en/teas/mint-tea", 308]);
    
  6. an unknown language, an unknown tea, or a tea not in that language is a 404
    const metadataFor = (lang, slug) => generateMetadata({ params: params({ lang, slug }) });
    for (const [lang, slug] of [["de", "green-tea"], ["en", "coffee"], ["fr", "lapsang-souchong"], ["en", "tisane-verveine"]]) {
      expect(await accessErrorOf(() => metadataFor(lang, slug))).toBe(404);
      expect(await accessErrorOf(() => renderServer(<Page params={params({ lang, slug })} />))).toBe(404);
    }
    
  7. the page shows the tea in its language
    await renderServer(<Page params={params({ lang: "fr", slug: "the-vert" })} />);
    expect(screen.getByRole("heading", { level: 1, name: "Thé vert" })).toBeInTheDocument();
    expect(screen.getByText("Léger et herbacé.")).toBeInTheDocument();
    

Learn more

app/[lang]/teas/[slug]/page.tsxSaved in this browser

Run tests runs every test on your code, here in your browser. The problem is solved when they all pass.

Ctrl + Enter runs the tests (⌘ + Enter on a Mac).