How to set the document language in TanStack Start v1

Declare page language for browsers and screen readers

Problem

Web pages must declare their primary language to function correctly across different user agents. Without an explicit language declaration on the root HTML element, browsers cannot determine the content's language and must guess. This causes screen readers to default to the user's system language, resulting in incorrect pronunciation when the content language differs. Browsers cannot offer accurate translation features because they lack source language information. Search engines struggle to confidently index content for the appropriate language audience, reducing discoverability for users searching in that language.

Solution

Add a lang attribute to the html tag to set the default language of your page. In TanStack Start, the HTML shell is defined in the root route's shellComponent, which renders the document structure including the <html> element. By adding the lang attribute with the appropriate language code to this element, you inform browsers, assistive technologies, and search engines of the content's language, enabling them to process and present it correctly.

Steps

1. Identify the current locale

The root route's shellComponent property defines the HTML shell that wraps all route content and is always server-side rendered. Determine the current locale from your application's locale detection mechanism, such as route parameters, cookies, or headers.

import type { ReactNode } from "react";
import {
  Outlet,
  createRootRoute,
  HeadContent,
  Scripts,
} from "@tanstack/react-router";

export const Route = createRootRoute({
  shellComponent: RootDocument,
  component: RootComponent,
});

function RootComponent() {
  return <Outlet />;
}

function RootDocument({ children }: { children: ReactNode }) {
  const locale = "en";

  return (
    <html>
      <head>
        <HeadContent />
      </head>
      <body>
        {children}
        <Scripts />
      </body>
    </html>
  );
}

This establishes the shell structure where you will add the language attribute.

2. Add the lang attribute to the html element

Set the lang attribute on the <html> element using the locale value. Use a valid BCP 47 language tag that matches your content's language.

function RootDocument({ children }: { children: ReactNode }) {
  const locale = "en";

  return (
    <html lang={locale}>
      <head>
        <HeadContent />
      </head>
      <body>
        {children}
        <Scripts />
      </body>
    </html>
  );
}

The lang attribute now declares the document language, enabling browsers and assistive technologies to handle the content appropriately.

3. Use dynamic locale values

If your application supports multiple locales, retrieve the current locale from your routing or state management system and pass it to the shell component.

function RootDocument({ children }: { children: ReactNode }) {
  const locale = getCurrentLocale();

  return (
    <html lang={locale}>
      <head>
        <HeadContent />
      </head>
      <body>
        {children}
        <Scripts />
      </body>
    </html>
  );
}

function getCurrentLocale(): string {
  return "en";
}

The document language now updates based on the active locale, ensuring the lang attribute always reflects the current content language.